Skip to content
SonoraSonora API

Get a customer

GET
/customers/{customerId}
curl --request GET \
  --url https://api.usesonora.com/v1/customers/example \
  --header 'Authorization: Bearer <token>'

One customer, with its account team, health and eCSAT; add ?include=enrichments for its enrichment values. Name it by its Sonora id, or by your own system’s id with idType. A Sonora, Salesforce or HubSpot id finds a customer whether or not it is archived; a domain or custom_field:<key> value matches live customers only, since an archived account can share it with a live one.

Requires the customers:read scope.

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.

include
string

Comma-separated optional parts of the response: enrichments.

Responses

Section titled “Responses”

200

Section titled “200”

The customer.

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_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"
  }
}

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

Run this request against your own Sonora workspace. Sign in, pick the workspace, and the page gets an access token that only reads, only what your role covers, for an hour.

GEThttps://api.usesonora.com/v1/customers/{customerId}

As curl

$SONORA_TOKEN is your access token or an API key; the page never shows the token.