Create a customer
const url = 'https://api.usesonora.com/v1/customers';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"domain":"example","name":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.usesonora.com/v1/customers \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "domain": "example", "name": "example" }'Add a customer by its domain, as Add customer in Sonora does. The domain becomes its website and email domain, so the calls, emails and tickets Sonora sees from that domain land on it. A domain another customer already has — archived or not — is 409 customer_exists, naming that customer. Set the rest of its fields with PATCH /customers/{customerId}. Send an Idempotency-Key to make a retry safe.
Requires the customers:write scope. API keys only.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”1–255 printable characters. A retry with the same key and request answers with the first call’s result instead of acting twice.
Request Bodyrequired
Section titled “Request Bodyrequired”A customer to create, named by its domain.
object
The company’s website or email domain — acme.com, https://www.acme.com/pricing — kept as the bare domain. It becomes the customer’s website and its email domain, so the people Sonora sees writing from it belong to the customer.
Defaults to a name made from the domain: acme-cloud.com becomes Acme Cloud.
Examplegenerated
{ "domain": "example", "name": "example"}Responses
Section titled “Responses”The customer, created.
A customer account, with its account team and the fields edits have taken over.
object
Domains whose email addresses belong to this customer.
Annual recurring revenue.
Sonora’s running summary of the account.
Your workspace’s custom fields, by key — only fields visible in Sonora.
object
As the field’s type says (GET /customer-fields). A user field is a list of people: [{ name, email }].
The record’s id in another system.
object
The system the id is from: salesforce, hubspot, zendesk, intercom, …
The customer’s health, as the customers page shows it.
object
The state’s key on your workspace’s health scale — by default thriving, healthy, emerging_concerns or at_risk — or no_data when nothing could be scored.
The state as Sonora shows it: Thriving, At Risk, …
0–10, higher is healthier. Null when there is nothing to score (no_data).
Whether your scale counts this state as at risk.
ECSAT: satisfaction Sonora estimates from what the customer says, averaged over recent touchpoints.
object
The average estimated satisfaction of the customer’s scored calls, emails and tickets, 0–10, to one decimal.
The days back the average covers.
Only with ?include=enrichments: the latest value of each enrichment that has one, in GET /enrichment-configs order.
A record’s latest value of one enrichment.
object
The enrichment’s id (GET /enrichment-configs/{configId}).
What the value is: short_text/long_text a string, number a number, score 1–10 (10 strongest), boolean, date YYYY-MM-DD, email, url, or select one of options (a list of them with multiple).
As outputType says. Null when there wasn’t enough to go on, for any outputType.
Why the AI gave this value, when it said.
Calls, emails, meetings and tickets Sonora has seen.
Moves on any change to the record, including Sonora’s own bookkeeping (engagement counts), so a sync may see a customer again with no field you read changed.
object
This resource’s canonical URL on the API host.
The account team beyond the owner, with each member’s role where the CRM gives one.
object
Null for a name typed in by hand or synced without a user.
Fields an edit — in Sonora or through this API — has taken over from sync: your CRM’s changes to them are held back until someone resumes sync on the field in Sonora. Standard fields by name (arr, owner), custom fields as customFields.<key>.
Example
{ "ecsat": { "windowDays": 90 }, "enrichments": [ { "outputType": "short_text" } ]}Headers
Section titled “Headers”A fingerprint of the fields PATCH can change. Send it back as If-Match to update only if none of them has changed since.
true when this answers a retry with an earlier call’s Idempotency-Key: the first call’s body, replayed.
invalid_json: The request body is not valid JSON.
invalid_request: A parameter or body field is missing, malformed or unknown; details.issues names each.
The one error shape every endpoint answers with.
object
object
Stable snake_case code to branch on; see the error table.
For humans; may change.
object
Quote it when asking for help.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": { "additionalProperty": "example" }, "requestId": "example" }}unauthorized: The Authorization header is missing, or the key is invalid, revoked or expired.
The one error shape every endpoint answers with.
object
object
Stable snake_case code to branch on; see the error table.
For humans; may change.
object
Quote it when asking for help.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": { "additionalProperty": "example" }, "requestId": "example" }}insufficient_scope: The key or token lacks the scope this endpoint needs, and details.required names it; or an OAuth access token called an endpoint only an API key can.
The one error shape every endpoint answers with.
object
object
Stable snake_case code to branch on; see the error table.
For humans; may change.
object
Quote it when asking for help.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": { "additionalProperty": "example" }, "requestId": "example" }}customer_exists: A customer already has that domain; details.customerId names it (archived or not).
idempotency_key_in_use: A request with this Idempotency-Key is still being processed. Retry once it has finished.
The one error shape every endpoint answers with.
object
object
Stable snake_case code to branch on; see the error table.
For humans; may change.
object
Quote it when asking for help.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": { "additionalProperty": "example" }, "requestId": "example" }}payload_too_large: The request body is too large; details.maxBytes gives the limit.
The one error shape every endpoint answers with.
object
object
Stable snake_case code to branch on; see the error table.
For humans; may change.
object
Quote it when asking for help.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": { "additionalProperty": "example" }, "requestId": "example" }}idempotency_key_mismatch: The Idempotency-Key was used before with a different request.
invalid_fields: A field’s value can’t be saved, so nothing was; details.issues names each field and why.
The one error shape every endpoint answers with.
object
object
Stable snake_case code to branch on; see the error table.
For humans; may change.
object
Quote it when asking for help.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": { "additionalProperty": "example" }, "requestId": "example" }}rate_limited: Too many requests for this key; retry after Retry-After seconds.
The one error shape every endpoint answers with.
object
object
Stable snake_case code to branch on; see the error table.
For humans; may change.
object
Quote it when asking for help.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": { "additionalProperty": "example" }, "requestId": "example" }}internal_error: Something went wrong on Sonora’s side. Retry, and quote requestId if it persists.
The one error shape every endpoint answers with.
object
object
Stable snake_case code to branch on; see the error table.
For humans; may change.
object
Quote it when asking for help.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": { "additionalProperty": "example" }, "requestId": "example" }}Try it
Try it runs the reference's read endpoints, and this one changes data, so it needs an API key with the customers:write scope. Create a key in Sonora under Settings → API and call it from your own code.