Skip to content
SonoraSonora API

Update a customer

PATCH
/customers/{customerId}
curl --request PATCH \
  --url https://api.usesonora.com/v1/customers/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "arr": 1, "stage": "example", "tier": "example", "renewalDate": "2026-04-15", "contractStartDate": "2026-04-15", "owner": { "email": "hello@example.com", "name": "example" }, "customFields": { "additionalProperty": "example" } }'

Change a customer’s fields, all or nothing. A field you change is taken over from your CRM exactly as an edit in Sonora is: its value sticks, and the CRM’s later changes to it are held back until someone resumes sync on it in Sonora. A field you send unchanged is left alone, so sending a whole record back only takes over what differs. Send If-Match with the ETag you read to refuse the write if the customer changed in between. The key needs customers:read as well as customers:write, since the response is the customer as saved.

Requires the customers:write scope. API keys only.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
customerId
required
string

The customer’s Sonora id — or, with idType, its id in another system, or its domain.

Query Parameters

Section titled “Query Parameters”
idType
string

How id names the account: sonora (the default; Sonora’s customer id), salesforce, hubspot, domain, or custom_field:<key>. So GET /customers/001Ab…?idType=salesforce finds a customer by its Salesforce Account id.

Header Parameters

Section titled “Header Parameters”
If-Match
string

The ETag from your last read. If the resource has changed since, nothing is written and the call answers 412 precondition_failed. Without it, the last write wins.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

The fields to change. A field you leave out is kept, null clears one, and a value equal to what the customer already holds is not a change.

object
name
string
arr

Annual recurring revenue, 0–9,999,999,999.99; kept to the cent.

number | null
stage
string | null
tier
string | null
renewalDate
Any of:
string format: date
contractStartDate
Any of:
string format: date
owner
Any of:

A person on your team, named by email.

object
email
required
Any of:
string format: email
name

Ignored — a person is named by email — so a Person you read can be sent back.

string | null
customFields

Custom fields by key, each as its type says (GET /customer-fields); null clears one. A user field takes a list of people, [{ "email" }]. Keys you leave out are kept.

object
key
additional properties
Examplegenerated
{
  "name": "example",
  "arr": 1,
  "stage": "example",
  "tier": "example",
  "renewalDate": "2026-04-15",
  "contractStartDate": "2026-04-15",
  "owner": {
    "email": "hello@example.com",
    "name": "example"
  },
  "customFields": {
    "additionalProperty": "example"
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

The customer, as saved.

Media typeapplication/json

A customer account, with its account team and the fields edits have taken over.

object
id
required
string
name
required
string
websiteUrl
required
string | null
emailDomains
required

Domains whose email addresses belong to this customer.

Array<string>
arr
required

Annual recurring revenue.

number | null
stage
required
string | null
tier
required
string | null
owner
required
Any of:

A person on your team.

object
name
required
string | null
email
required

Null for a name typed in by hand or synced without a user.

string | null
renewalDate
required
Any of:
string format: date
contractStartDate
required
Any of:
string format: date
contractLengthDays
required
Any of:
integer
summary
required

Sonora’s running summary of the account.

string | null
customFields
required

Your workspace’s custom fields, by key — only fields visible in Sonora.

object
key
additional properties

As the field’s type says (GET /customer-fields). A user field is a list of people: [{ name, email }].

externalIds
required
Array<object>

The record’s id in another system.

object
source
required

The system the id is from: salesforce, hubspot, zendesk, intercom, …

string
id
required
string
health
required
Any of:

The customer’s health, as the customers page shows it.

object
state
required

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.

string
label
required

The state as Sonora shows it: Thriving, At Risk, …

string
score
required

0–10, higher is healthier. Null when there is nothing to score (no_data).

number | null
atRisk
required

Whether your scale counts this state as at risk.

boolean
computedAt
required
string format: date-time
ecsat
required
Any of:

ECSAT: satisfaction Sonora estimates from what the customer says, averaged over recent touchpoints.

object
score
required

The average estimated satisfaction of the customer’s scored calls, emails and tickets, 0–10, to one decimal.

number
windowDays
required

The days back the average covers.

number
Allowed value: 90
enrichments

Only with ?include=enrichments: the latest value of each enrichment that has one, in GET /enrichment-configs order.

Array<object>

A record’s latest value of one enrichment.

object
configId
required

The enrichment’s id (GET /enrichment-configs/{configId}).

string
title
required
string
outputType
required

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).

string
Allowed values: short_text long_text number score boolean date email url select
value
required

As outputType says. Null when there wasn’t enough to go on, for any outputType.

reason
required

Why the AI gave this value, when it said.

string | null
computedAt
required
string format: date-time
engagementsCount
required

Calls, emails, meetings and tickets Sonora has seen.

integer
lastEngagementAt
required
Any of:
string format: date-time
archivedAt
required
Any of:
string format: date-time
createdAt
required
string format: date-time
updatedAt
required

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.

string format: date-time
links
required
object
self
required

This resource’s canonical URL on the API host.

string
accountTeam
required

The account team beyond the owner, with each member’s role where the CRM gives one.

Array<object>
object
name
required
string | null
email
required

Null for a name typed in by hand or synced without a user.

string | null
role
required
string | null
overriddenFields
required

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>.

Array<string>
Example
{
  "ecsat": {
    "windowDays": 90
  },
  "enrichments": [
    {
      "outputType": "short_text"
    }
  ]
}

Headers

Section titled “Headers”
ETag
string

A fingerprint of the fields PATCH can change. Send it back as If-Match to update only if none of them has changed since.

400

Section titled “400”

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.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

401

Section titled “401”

unauthorized: The Authorization header is missing, or the key is invalid, revoked or expired.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

403

Section titled “403”

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.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

404

Section titled “404”

customer_not_found: No customer matches the id (and idType) in the path.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

409

Section titled “409”

customer_archived: The customer is archived; unarchive it before changing it.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

412

Section titled “412”

precondition_failed: The resource changed since the ETag that If-Match names. Read it again, then retry.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

413

Section titled “413”

payload_too_large: The request body is too large; details.maxBytes gives the limit.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

422

Section titled “422”

invalid_fields: A field’s value can’t be saved, so nothing was; details.issues names each field and why.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

429

Section titled “429”

rate_limited: Too many requests for this key; retry after Retry-After seconds.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

500

Section titled “500”

internal_error: Something went wrong on Sonora’s side. Retry, and quote requestId if it persists.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
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.