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#
/a/{team_slug}/customers/api/v1/customers/
customers_list ·
View in API reference
/a/{team_slug}/customers/api/v1/customers/
customers_create ·
View in API reference
/a/{team_slug}/customers/api/v1/customers/{id}/
customers_retrieve ·
View in API reference
/a/{team_slug}/customers/api/v1/customers/{id}/
customers_partial_update ·
View in API reference
/a/{team_slug}/customers/api/v1/customers/{id}/
customers_update ·
View in API reference
/a/{team_slug}/customers/api/v1/customers/{id}/
customers_destroy ·
View in API reference
/a/{team_slug}/customers/api/v1/customers/external/{external_ref}/
customers_external_retrieve ·
View in API reference
/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#
/a/{team_slug}/customers/api/v1/contacts/
contacts_list ·
View in API reference
/a/{team_slug}/customers/api/v1/contacts/
contacts_create ·
View in API reference
/a/{team_slug}/customers/api/v1/contacts/{id}/
contacts_retrieve ·
View in API reference
/a/{team_slug}/customers/api/v1/contacts/{id}/
contacts_partial_update ·
View in API reference
/a/{team_slug}/customers/api/v1/contacts/{id}/
contacts_update ·
View in API reference
/a/{team_slug}/customers/api/v1/contacts/{id}/
contacts_destroy ·
View in API reference
/a/{team_slug}/customers/api/v1/contacts/external/{external_ref}/
contacts_external_retrieve ·
View in API reference
/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.