Skip to content
Docs
Sign in

Customers API

Create and update your customers and their contacts from your own system, by your own ids.

For integrators

The customers API keeps a team's customers and the contacts at them. Both are optional records that other parts of the app can point at; an artwork in Approvals, for example, can name its customer and contact (see Approvals API). Calls need an API key (see the API overview), and any member of the team can read and write.

All paths start with /a/<team_slug>/customers/api/v1/.

External references#

Every customer and contact has an external_ref: the id the record has in your own system, such as an ERP or CRM. It is optional, up to 100 characters, and unique in the team for customers and, separately, for contacts.

With it, a sync never has to look a record up first. PUT …/customers/external/<ref>/ makes the customer with that reference, or updates it when it exists, and answers 201 or 200 to say which. GET on the same address reads it, and ?external_ref=<ref> filters a list.

curl -sS -X PUT -H "Authorization: Api-Key $API_KEY" -H "Content-Type: application/json" \
  "https://app.example.com/a/acme/customers/api/v1/customers/external/C-1042/" \
  -d '{"name": "Birch Labels"}'

An update through this address changes only the fields you send; the others keep their values.

Customers#

GET /a/{team_slug}/customers/api/v1/customers/

customers_list · View in API reference

POST /a/{team_slug}/customers/api/v1/customers/

customers_create · View in API reference

GET /a/{team_slug}/customers/api/v1/customers/{id}/

customers_retrieve · View in API reference

PATCH /a/{team_slug}/customers/api/v1/customers/{id}/

customers_partial_update · View in API reference

PUT /a/{team_slug}/customers/api/v1/customers/{id}/

customers_update · View in API reference

DELETE /a/{team_slug}/customers/api/v1/customers/{id}/

customers_destroy · View in API reference

GET /a/{team_slug}/customers/api/v1/customers/external/{external_ref}/

customers_external_retrieve · View in API reference

PUT /a/{team_slug}/customers/api/v1/customers/external/{external_ref}/

Create the customer with this external reference, or update it when it exists.

customers_external_upsert · View in API reference

A customer has id, name, external_ref, notes, archived_at, contact_count, created_at and updated_at. Names are unique in the team whatever their capitals: a second "birch labels" answers 400.

The list is sorted by name and paged. ?search= matches part of a name or external reference. Archived customers (those with an archived_at) are left out unless you add ?archived=true. Deleting a customer keeps its contacts and whatever pointed at it, which then have no customer.

Contacts#

GET /a/{team_slug}/customers/api/v1/contacts/

contacts_list · View in API reference

POST /a/{team_slug}/customers/api/v1/contacts/

contacts_create · View in API reference

GET /a/{team_slug}/customers/api/v1/contacts/{id}/

contacts_retrieve · View in API reference

PATCH /a/{team_slug}/customers/api/v1/contacts/{id}/

contacts_partial_update · View in API reference

PUT /a/{team_slug}/customers/api/v1/contacts/{id}/

contacts_update · View in API reference

DELETE /a/{team_slug}/customers/api/v1/contacts/{id}/

contacts_destroy · View in API reference

GET /a/{team_slug}/customers/api/v1/contacts/external/{external_ref}/

contacts_external_retrieve · View in API reference

PUT /a/{team_slug}/customers/api/v1/contacts/external/{external_ref}/

Create the contact with this external reference, or update it when it exists.

contacts_external_upsert · View in API reference

A contact has id, customer, customer_name, name, email, phone, title, external_ref, notes, archived_at, created_at and updated_at. It needs a name or an email. An email address belongs to one contact in the team, whatever its capitals.

Name the contact's customer by customer (its id) or, when writing, by customer_external_ref:

curl -sS -X PUT -H "Authorization: Api-Key $API_KEY" -H "Content-Type: application/json" \
  "https://app.example.com/a/acme/customers/api/v1/contacts/external/P-77/" \
  -d '{"name": "Jordan Lee", "email": "jordan@example.com", "customer_external_ref": "C-1042"}'

A customer_external_ref that no customer has answers 400, so send customers before their contacts. The list takes ?search= (name, email, external reference or customer name), ?customer=<id> and ?archived=true.

Last updated Nov. 18, 2026