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
| Field | Type | Required | Description |
|---|---|---|---|
originatorId | string (UUID) | Yes | The originator this contact belongs to |
entityType | string | Yes | INDIVIDUAL or BUSINESS |
companyName | string or null | Conditional | Required for BUSINESS. Rejected for INDIVIDUAL -- see below. Max 100 characters. Printable ASCII only -- accented letters, non-Latin scripts, and control characters are rejected. |
firstName | string or null | Conditional | Required for INDIVIDUAL, optional for BUSINESS (null accepted). 1-50 characters. Letters, spaces, hyphens, apostrophes, and periods only. |
lastName | string or null | Conditional | Required for INDIVIDUAL, optional for BUSINESS (null accepted). 1-50 characters. Letters, spaces, hyphens, apostrophes, and periods only. |
email | string or null | No | Valid email address. Max 254 characters. Nothing in payment processing needs it. |
phoneNumber | string or null | No | US phone number. Accepts various formats (e.g., +19497037012, (949) 703-7012, 949-703-7012). Stored and returned in E.164 format. |
legalAddress | object | Yes | Full address object (see Nested objects) |
bankAccount | object | Yes | Full 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:
companyNameis required forBUSINESS. A business is identified by its company name, so aBUSINESScontact without one is rejected withCompany name is required for business entity type.companyNameis rejected forINDIVIDUAL. This is not merely optional: sending a company name on anINDIVIDUALcontact returns400withCompany 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 sendnull) when the contact is an individual.firstNameandlastNameare required forINDIVIDUAL. Both must be present; each missing one returns a400withissue: "validation_name_required"on that field.firstNameandlastNameare optional forBUSINESS. Send them if you have a contact person, or leave them out (nulland omitted are both accepted). ABUSINESScontact is identified bycompanyNamealone.
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
| Code | Reason |
|---|---|
400 | Invalid 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 | |
401 | API key is missing, malformed, unknown, revoked, or expired |
403 | The API key is valid but is not an organization key |
404 | originatorId does not match an originator in your organization |
409 | The 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 |
503 | The 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
| Parameter | Type | Default | Description |
|---|---|---|---|
originatorId | string (UUID) | required | The originator whose contacts to list |
search | string | — | 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 |
limit | integer | 20 | Number of contacts per page (1–100) |
cursor | string | — | 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
| Parameter | Type | Default | Description |
|---|---|---|---|
id | string (UUID) | required | Path parameter. The contact to retrieve |
originatorId | string (UUID) | required | The 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
| Code | Reason |
|---|---|
400 | id or originatorId is missing or not a UUID |
401 | API key is missing, malformed, unknown, revoked, or expired |
403 | The API key is valid but is not an organization key |
404 | Contact 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
| Field | Type | Description |
|---|---|---|
companyName | string or null | Cannot 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. |
firstName | string or null | 1-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. |
lastName | string or null | 1-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. |
email | string or null | Valid email address. Max 254 characters. null clears a stored one. |
phoneNumber | string or null | US phone number. Accepts various formats (e.g., +19497037012, (949) 703-7012, 949-703-7012). Stored and returned in E.164 format. |
legalAddress | object | Full address object (see below) |
bankAccount | object | Full 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"
}
}
| Field | Required | Description |
|---|---|---|
addressLine1 | Yes | Must contain at least one letter and one digit. Max 100 characters. |
addressLine2 | No | Optional. Max 100 characters. |
city | Yes | Must contain at least one letter. Max 50 characters. |
state | Yes | US state or territory code (e.g., IL, CA, PR). |
postalCode | Yes | 5-digit US ZIP code (no ZIP+4). |
countryCode | Yes | Currently only US is accepted. |
bankAccount:
{
"bankAccount": {
"subType": "CHECKING",
"achRoutingNumber": "021000021",
"achAccountNumber": "987654321"
}
}
| Field | Required | Description |
|---|---|---|
subType | Yes | CHECKING or SAVINGS |
achRoutingNumber | Yes | 9-digit ABA routing number with valid checksum |
achAccountNumber | Yes | 5-17 alphanumeric characters |
swiftCode | No | SWIFT/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
| Code | Reason |
|---|---|
400 | Invalid 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 | |
401 | API key is missing, malformed, unknown, revoked, or expired |
403 | The API key is valid but is not an organization key |
404 | Contact not found or does not belong to your organization |
409 | The 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
| Parameter | Type | Default | Description |
|---|---|---|---|
id | string (UUID) | required | Path parameter. The contact to delete |
originatorId | string (UUID) | required | The originator the contact belongs to |
Response
204 No Content with an empty body.
What deleting does
- The contact stops appearing in
GET /v1/contactsand returns404fromGET /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/paymentsreturns404. - 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
| Code | Reason |
|---|---|
400 | id or originatorId is missing or not a UUID |
401 | API key is missing, malformed, unknown, revoked, or expired |
403 | The API key is valid but is not an organization key |
404 | Contact 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 --
firstNameandlastNamefor anINDIVIDUAL,companyNamefor aBUSINESS bankAccount.achRoutingNumberbankAccount.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/contactsreturns409with codeCONFLICTand the messageA contact with this name and bank account already exists for this originator. - Update --
PATCH /v1/contacts/{id}returns the same409when 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.