Managing Contacts

A contact is the party on the other side of a payment from your originator: the party you pay on an outbound payment, and the party you debit on an inbound one. This guide covers creating a contact, then reading, listing, and updating one as their details change, and deleting one when it is no longer needed. Making Your First Payment walks a contact and a payment through end to end.

Create a contact

Send a POST request with the contact's name, address, and bank account. entityType decides which name fields the contact carries -- see Entity type and names below.

curl -X POST "https://staging.api.now.luqra.com/v1/contacts/" \
  -H "Authorization: Bearer luqra-now.org.test.YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "originatorId": "ORIGINATOR_ID",
    "entityType": "INDIVIDUAL",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane.smith@example.com",
    "phoneNumber": "+19497037012",
    "legalAddress": {
      "addressLine1": "123 Main St",
      "city": "Springfield",
      "state": "IL",
      "postalCode": "62701",
      "countryCode": "US"
    },
    "bankAccount": {
      "subType": "CHECKING",
      "achRoutingNumber": "021000021",
      "achAccountNumber": "123456789"
    }
  }'

Request fields

FieldTypeRequiredDescription
originatorIdstring (UUID)YesThe originator this contact belongs to
entityTypestringYesINDIVIDUAL or BUSINESS
companyNamestring or nullConditionalRequired for BUSINESS. Rejected for INDIVIDUAL -- see below. Max 100 characters. Printable ASCII only -- accented letters, non-Latin scripts, and control characters are rejected.
firstNamestring or nullConditionalRequired for INDIVIDUAL, optional for BUSINESS (null accepted). 1-50 characters. Letters, spaces, hyphens, apostrophes, and periods only.
lastNamestring or nullConditionalRequired for INDIVIDUAL, optional for BUSINESS (null accepted). 1-50 characters. Letters, spaces, hyphens, apostrophes, and periods only.
emailstring or nullNoValid email address. Max 254 characters. Nothing in payment processing needs it.
phoneNumberstring or nullNoUS phone number. Accepts various formats (e.g., +19497037012, (949) 703-7012, 949-703-7012). Stored and returned in E.164 format.
legalAddressobjectYesFull address object (see Nested objects)
bankAccountobjectYesFull bank account object (see Nested objects)

Entity type and names

Which name fields a contact may carry depends on entityType, and one of the rules is a rejection rather than a relaxation:

  • companyName is required for BUSINESS. A business is identified by its company name, so a BUSINESS contact without one is rejected with Company name is required for business entity type.
  • companyName is rejected for INDIVIDUAL. This is not merely optional: sending a company name on an INDIVIDUAL contact returns 400 with Company name is not allowed for individual entity type, even if the value is a valid name. If your own records carry a business or "doing business as" name on every customer, omit it (or send null) when the contact is an individual.
  • firstName and lastName are required for INDIVIDUAL. Both must be present; each missing one returns a 400 with issue: "validation_name_required" on that field.
  • firstName and lastName are optional for BUSINESS. Send them if you have a contact person, or leave them out (null and omitted are both accepted). A BUSINESS contact is identified by companyName alone.

A business contact therefore looks like this:

curl -X POST "https://staging.api.now.luqra.com/v1/contacts/" \
  -H "Authorization: Bearer luqra-now.org.test.YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "originatorId": "ORIGINATOR_ID",
    "entityType": "BUSINESS",
    "companyName": "Acme Supply Co",
    "legalAddress": {
      "addressLine1": "500 Industrial Way",
      "city": "Springfield",
      "state": "IL",
      "postalCode": "62701",
      "countryCode": "US"
    },
    "bankAccount": {
      "subType": "CHECKING",
      "achRoutingNumber": "021000021",
      "achAccountNumber": "987654321"
    }
  }'

Response

A 201 returns the new contact's identifier and creation timestamp -- not the full contact. Read it back with Get a contact if you need the stored values.

{
  "data": {
    "contactId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "createdAt": "2026-03-15T14:30:00.000Z"
  },
  "meta": { "timestamp": "2026-03-15T14:30:00.000Z" }
}

Error responses

CodeReason
400Invalid request body
companyName missing on a BUSINESS contact -- Company name is required for business entity type
companyName sent on an INDIVIDUAL contact -- Company name is not allowed for individual entity type
firstName or lastName missing on an INDIVIDUAL contact
achRoutingNumber not found in the Fed directory
401API key is missing, malformed, unknown, revoked, or expired
403The API key is valid but is not an organization key
404originatorId does not match an originator in your organization
409The originator already has a contact with this name, routing and account number -- A contact with this name and bank account already exists for this originator. See Duplicate contacts
503The bank directory behind routing number validation is temporarily down. Retry-safe.

5xx responses aren't listed here. See Errors for the full status and error-code reference.

List contacts

Retrieve a paginated list of contacts for an originator.

curl "https://staging.api.now.luqra.com/v1/contacts?originatorId=ORIGINATOR_ID" \
  -H "Authorization: Bearer luqra-now.org.test.YOUR_API_KEY"

Query parameters

ParameterTypeDefaultDescription
originatorIdstring (UUID)requiredThe originator whose contacts to list
searchstring—Case-insensitive filter. Every whitespace-separated word must match part of the first name, last name, email, or company name, and different words may match different fields — so Jane Smith matches a contact with first name Jane and last name Smith. Only the first 10 words are used. Every character is matched literally, so % and _ carry no wildcard meaning. Maximum 100 characters
limitinteger20Number of contacts per page (1–100)
cursorstring—Pagination cursor from a previous response's meta.pagination.nextCursor

Response

{
  "data": [
    {
      "contactId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "entityType": "INDIVIDUAL",
      "companyName": null,
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "ja*******h@example.com",
      "phoneNumber": null,
      "legalAddress": {
        "addressLine1": "123 Main St",
        "addressLine2": null,
        "city": "Springfield",
        "state": "IL",
        "postalCode": "62701",
        "countryCode": "US"
      },
      "bankAccount": null,
      "createdAt": "2026-03-15T14:30:00.000Z"
    }
  ],
  "meta": {
    "timestamp": "2026-05-19T10:00:00.000Z",
    "pagination": {
      "limit": 20,
      "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTAzLTE1VDE0OjMwOjAwLjAwMFoiLCJpZCI6IjZiYTdiODEwLTlkYWQtMTFkMS04MGI0LTAwYzA0ZmQ0MzBjOCJ9"
    }
  }
}

When nextCursor is null, there are no more pages. To fetch the next page, pass the cursor value as the cursor query parameter:

curl "https://staging.api.now.luqra.com/v1/contacts?originatorId=ORIGINATOR_ID&cursor=NEXT_CURSOR&limit=20" \
  -H "Authorization: Bearer luqra-now.org.test.YOUR_API_KEY"

Sensitive fields (email, phone number, bank account numbers, and routing numbers) are masked in all responses.

email is optional on a contact, so a contact created without one returns email: null and never matches an email search term.

A search term longer than 100 characters returns 400 with VALIDATION_ERROR rather than a list.

Get a contact

Retrieve a single contact by its identifier. The contact must belong to the originator you pass, the same way the list is scoped to one originator.

curl "https://staging.api.now.luqra.com/v1/contacts/CONTACT_ID?originatorId=ORIGINATOR_ID" \
  -H "Authorization: Bearer luqra-now.org.test.YOUR_API_KEY"

Parameters

ParameterTypeDefaultDescription
idstring (UUID)requiredPath parameter. The contact to retrieve
originatorIdstring (UUID)requiredThe originator the contact belongs to

Response

The contact carries the same fields, and the same masking, as an entry in the list response.

{
  "data": {
    "contactId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "entityType": "INDIVIDUAL",
    "companyName": null,
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "ja*******h@example.com",
    "phoneNumber": "********1234",
    "legalAddress": {
      "addressLine1": "123 Main St",
      "addressLine2": null,
      "city": "Springfield",
      "state": "IL",
      "postalCode": "62701",
      "countryCode": "US"
    },
    "bankAccount": {
      "bankName": null,
      "swiftCode": null,
      "subType": "CHECKING",
      "achRoutingNumber": "*****0021",
      "achAccountNumber": "*****6789"
    },
    "createdAt": "2026-03-15T14:30:00.000Z"
  },
  "meta": { "timestamp": "2026-05-19T10:00:00.000Z" }
}

Error responses

CodeReason
400id or originatorId is missing or not a UUID
401API key is missing, malformed, unknown, revoked, or expired
403The API key is valid but is not an organization key
404Contact not found, deleted, belonging to another originator, or not part of your organization. These cases are not distinguished.

5xx responses aren't listed here. See Errors for the full status and error-code reference.

Update a contact

Send a PATCH request with only the fields you want to change. At least one field must be provided.

curl -X PATCH "https://staging.api.now.luqra.com/v1/contacts/CONTACT_ID" \
  -H "Authorization: Bearer luqra-now.org.test.YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.smith@newdomain.com",
    "phoneNumber": "+14155551234"
  }'

Updatable fields

FieldTypeDescription
companyNamestring or nullCannot be cleared on a BUSINESS contact -- null returns 400. Rejected for an INDIVIDUAL one -- a non-null value returns 400; null is accepted and clears a stored one. Max 100 characters. Printable ASCII only -- accented letters, non-Latin scripts, and control characters are rejected.
firstNamestring or null1-50 characters. Letters, spaces, hyphens, apostrophes, and periods only. Optional for BUSINESS, which is identified by companyName -- null clears a stored one. Cannot be cleared on an INDIVIDUAL contact -- null returns 400.
lastNamestring or null1-50 characters. Letters, spaces, hyphens, apostrophes, and periods only. Optional for BUSINESS, which is identified by companyName -- null clears a stored one. Cannot be cleared on an INDIVIDUAL contact -- null returns 400.
emailstring or nullValid email address. Max 254 characters. null clears a stored one.
phoneNumberstring or nullUS phone number. Accepts various formats (e.g., +19497037012, (949) 703-7012, 949-703-7012). Stored and returned in E.164 format.
legalAddressobjectFull address object (see below)
bankAccountobjectFull bank account object (see below)

A companyName or name change is validated against the contact's stored entity type -- the same rules as on create, see Entity type and names. Omitting a field means "leave unchanged", so null is how a BUSINESS contact drops a contact person's name it was created with.

Not updatable

entityType cannot be changed after creation.

Sending entityType in the request body returns 400 rather than being ignored -- switching between BUSINESS and INDIVIDUAL would make the contact a different entity. To use a different entity type, delete the contact and create a new one with the same bank account details if needed.

Nested objects

legalAddress and bankAccount take the same shape on create and on update. Both are required on create, and on update you provide the full object -- partial nested updates are not supported.

legalAddress:

{
  "legalAddress": {
    "addressLine1": "456 Oak Ave",
    "addressLine2": "Suite 200",
    "city": "Springfield",
    "state": "IL",
    "postalCode": "62702",
    "countryCode": "US"
  }
}
FieldRequiredDescription
addressLine1YesMust contain at least one letter and one digit. Max 100 characters.
addressLine2NoOptional. Max 100 characters.
cityYesMust contain at least one letter. Max 50 characters.
stateYesUS state or territory code (e.g., IL, CA, PR).
postalCodeYes5-digit US ZIP code (no ZIP+4).
countryCodeYesCurrently only US is accepted.

bankAccount:

{
  "bankAccount": {
    "subType": "CHECKING",
    "achRoutingNumber": "021000021",
    "achAccountNumber": "987654321"
  }
}
FieldRequiredDescription
subTypeYesCHECKING or SAVINGS
achRoutingNumberYes9-digit ABA routing number with valid checksum
achAccountNumberYes5-17 alphanumeric characters
swiftCodeNoSWIFT/BIC code. Max 11 characters.

Response

The response returns the full contact with updated values. Sensitive fields (bank account numbers, routing numbers, email, and phone number) are masked in the response.

{
  "data": {
    "contactId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "entityType": "INDIVIDUAL",
    "companyName": null,
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "ja*******h@newdomain.com",
    "phoneNumber": "********1234",
    "legalAddress": {
      "addressLine1": "123 Main St",
      "addressLine2": null,
      "city": "Springfield",
      "state": "IL",
      "postalCode": "62701",
      "countryCode": "US"
    },
    "bankAccount": {
      "bankName": null,
      "swiftCode": null,
      "subType": "CHECKING",
      "achRoutingNumber": "*****0021",
      "achAccountNumber": "*****6789"
    },
    "updatedAt": "2026-03-15T14:30:00.000Z"
  },
  "meta": { "timestamp": "2026-03-15T14:30:00.000Z" }
}

Error responses

CodeReason
400Invalid request body or no fields provided
entityType included in the body -- Entity type cannot be changed after creation. Create a new contact with the desired entity type.
A non-null companyName on an INDIVIDUAL contact -- Company name is not allowed for individual entity type
companyName: null on a BUSINESS contact -- Company name is required for business entity type
401API key is missing, malformed, unknown, revoked, or expired
403The API key is valid but is not an organization key
404Contact not found or does not belong to your organization
409The new bank account already belongs to a contact of this originator with this contact's name -- A contact with this name and bank account already exists for this originator. See Duplicate contacts
The new name matches a contact holding the same bank account -- same code and message. A rename alone can conflict; see Duplicate contacts
The contact's bank account was changed by a concurrent request -- Contact bank account was updated by a concurrent request, please retry. Only a request that changes bankAccount can hit this; fetch the contact again and retry

5xx responses aren't listed here. See Errors for the full reference, including the retry-safe 503 SERVICE_UNAVAILABLE returned when the bank directory behind routing number validation is temporarily down.

Delete a contact

Send a DELETE request to remove a contact. The contact must belong to the originator you pass, the same way the single-contact read is scoped to one originator.

curl -X DELETE "https://staging.api.now.luqra.com/v1/contacts/CONTACT_ID?originatorId=ORIGINATOR_ID" \
  -H "Authorization: Bearer luqra-now.org.test.YOUR_API_KEY"

Parameters

ParameterTypeDefaultDescription
idstring (UUID)requiredPath parameter. The contact to delete
originatorIdstring (UUID)requiredThe originator the contact belongs to

Response

204 No Content with an empty body.

What deleting does

  • The contact stops appearing in GET /v1/contacts and returns 404 from GET /v1/contacts/{id}.
  • Its bank account is released. The routing and account number pair becomes available again, so you can create a new contact with those same details under the same originator. See Duplicate contacts.
  • Existing payments are untouched. A payment that references a deleted contact keeps resolving and reads back with the same fields it returned before the delete.
  • New payments for the contact are refused -- POST /v1/payments returns 404.
  • An open payment link for the contact still works, but their account on file is no longer offered as a pre-fill, so the payer enters their bank details on the page.

Deleting is not reversible through the API.

Error responses

CodeReason
400id or originatorId is missing or not a UUID
401API key is missing, malformed, unknown, revoked, or expired
403The API key is valid but is not an organization key
404Contact not found, already deleted, belonging to another originator, or not part of your organization. These cases are not distinguished.

5xx responses aren't listed here. See Errors for the full status and error-code reference.

Duplicate contacts

An originator cannot have two contacts with the same name and bank account. A contact is a duplicate when all four of the following match an existing contact:

  • the originatorId
  • the contact's name -- firstName and lastName for an INDIVIDUAL, companyName for a BUSINESS
  • bankAccount.achRoutingNumber
  • bankAccount.achAccountNumber

Names compare ignoring letter case, leading or trailing spaces, and repeated spaces between words, so Anna Smith and anna smith are the same name. Because the name is part of the check, two contacts with different names can hold the same routing and account number -- spouses or business partners paying from one joint account each get their own contact. Nothing else is part of the check. Email plays no part, so two contacts of the same originator can share an email address. subType and swiftCode are not compared either. And because contacts are scoped to an originator, the same bank account under a different originatorId is not a duplicate.

The rule is enforced everywhere names and bank details enter the system:

  • Create -- POST /v1/contacts returns 409 with code CONFLICT and the message A contact with this name and bank account already exists for this originator.
  • Update -- PATCH /v1/contacts/{id} returns the same 409 when the request changes the bank account to one that a contact of the originator with this name already holds, or renames the contact to the name of a contact holding the same bank account. A contact never conflicts with itself: resubmitting its own current name and bank details succeeds and changes nothing, and a rename combined with a bank account change succeeds whenever the resulting name and account combination is unique.

When safely resolved, error.resources identifies the conflicting contact with type: "contact". On a shared bank account it names the contact with the matching name, never a partner who only shares the account. Use its id anywhere a contact ID is accepted. This applies to both create and update conflicts. If no readable contact can safely be identified, the field is absent.

When the reference is absent, locate the existing contact by listing the originator's contacts with GET /v1/contacts?originatorId=.... Each entry's bankAccount.achRoutingNumber and bankAccount.achAccountNumber show up to the last four characters, which is usually enough to identify the record you collided with. bankAccount is null on a contact that has no bank account, and such a contact can never be the one you collided with.

Deleting a contact releases its bank account, so a deleted contact is never the record you collided with. Both DELETE /v1/contacts/{id} and deleting in the Luqra Now dashboard free the routing and account number pair immediately, and those details can be registered again under the same originator straight away. A 409 therefore always points at a contact the list can show you.