Add a customer before they write in, on a unique email

Add a customer record by hand. Email is unique within a workspace when present. Inbound channel traffic creates customers automatically, so use this for a customer you know about before they contact you.

A duplicate address is refused with 409 customer_email_taken and nothing is written, so an importer can treat that as "already here" rather than as a failure. Uniqueness is per workspace, and only when an address is given: several customers with no address are allowed.

email is what threads inbound mail onto this customer, so setting it up front is what makes their first message land on the right record.

Tenancy: the request is scoped to one workspace, and the credential presented is what selects it. A caller with no membership in that workspace is refused with 404, which is indistinguishable from a workspace that does not exist.

Authorisation: editor, admin or owner. A viewer receives 403 insufficient_role.

Access: Authorization: Bearer carrying either a realm access token or an API key. A key must hold the customers:write scope, and the workspace role of the person who owns it must meet the floor above.

Response Body

curl -X POST "https://example.com/v1/customers" \  -H "Content-Type: application/json" \  -d '{    "display_name": "Sam Okafor",    "email": "sam.okafor@northwind.example",    "company": "Northwind Ltd",    "country": "GB",    "metadata": {      "plan": "enterprise"    }  }'

{  "id": "9f1d6c4e-6b6e-4b31-9a5b-2f1c9a4d5e60",  "display_name": "Sam Okafor",  "email": "sam.okafor@northwind.example",  "company": "Northwind Ltd",  "country": "GB",  "metadata": {    "plan": "enterprise"  },  "created_at": "2026-08-14T09:00:00+00:00",  "updated_at": "2026-08-14T09:00:00+00:00"}