Skip to content
SonoraSonora API

List customers

GET
/customers
curl --request GET \
  --url 'https://api.usesonora.com/v1/customers?includeArchived=true&sort=-createdAt&limit=25' \
  --header 'Authorization: Bearer <token>'

Customers newest first, or — with sort=updatedAt — oldest change first, to keep another system in step with Sonora. Archived customers are left out unless includeArchived=true.

Requires the customers:read scope.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
search
string
>= 1 characters <= 200 characters

Matches the name, website or an email domain, as the customers page’s search does.

stage
string

Comma-separated stages, matched exactly (ignoring case); a customer in any of them matches.

tier
string

Comma-separated tiers, matched exactly (ignoring case).

owner
string format: email

The owner’s email address.

includeArchived
string
Allowed values: true false

Also list archived customers. A sync should set it, so it sees a customer leave.

createdAfter
string format: date-time
updatedAfter
string format: date-time

Customers changed at or after this instant. With sort=updatedAt, resume a sync from the last updatedAt you saw, a few minutes back.

sort
string
default: -createdAt
Allowed values: -createdAt updatedAt

-createdAt: newest first (the default). updatedAt: oldest change first, for syncing.

limit
integer
default: 25 >= 1 <= 100

Page size, 1–100.

cursor
string
<= 200 characters

The previous page’s nextCursor, unchanged. Omit for the first page.

include
string

Comma-separated optional parts of the response: totalCount, enrichments.

Responses

Section titled “Responses”

200

Section titled “200”

A page of customers.

Media typeapplication/json
object
data
required
Array<object>

A customer account.

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
totalCount

Only with ?include=totalCount: every match under the same filters.

integer
nextCursor
required

Pass as cursor for the next page; null on the last page.

string | null
Example
{
  "data": [
    {
      "ecsat": {
        "windowDays": 90
      },
      "enrichments": [
        {
          "outputType": "short_text"
        }
      ]
    }
  ]
}

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

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

As curl

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