List contacts
const url = 'https://api.usesonora.com/v1/contacts?departed=true&includeArchived=true&sort=-createdAt&limit=25';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.usesonora.com/v1/contacts?departed=true&includeArchived=true&sort=-createdAt&limit=25' \ --header 'Authorization: Bearer <token>'The people at your customers. Newest first, or — with sort=updatedAt — oldest change first, to keep another system in step with Sonora. People who have left their customer are included (departedAt set); archived contacts are left out unless includeArchived=true.
Requires the contacts:read scope.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Only the people at this customer (its Sonora id).
The person’s email address, matched without regard to case.
true: only people who have left their customer. false: only people still there. Omit for both.
Also list archived contacts. A sync should set it, so it sees a contact leave.
Contacts changed at or after this instant. With sort=updatedAt, resume a sync from the last updatedAt you saw, a few minutes back.
-createdAt: newest first (the default). updatedAt: oldest change first, for syncing.
Page size, 1–100.
The previous page’s nextCursor, unchanged. Omit for the first page.
Comma-separated optional parts of the response: totalCount.
Responses
Section titled “Responses”A page of contacts.
object
A person at one of your customers.
object
The customer the person works at. Null when Sonora hasn’t matched them to one.
First and last name together; null when Sonora has neither.
Job title.
Marked as a champion at their account.
Someone on your team marked the person do-not-contact, so Sonora never emails them. The mark is on the address, so changing it doesn’t move updatedAt.
The record’s id in another system.
object
The system the id is from: salesforce, hubspot, zendesk, intercom, …
Calls, emails, meetings and tickets Sonora has seen the person in.
Moves on any change to the record, including Sonora’s own bookkeeping (engagement counts).
object
This resource’s canonical URL on the API host.
Only with ?include=totalCount: every match under the same filters.
Pass as cursor for the next page; null on the last page.
Examplegenerated
{ "data": [ { "id": "example", "customerId": "example", "firstName": "example", "lastName": "example", "name": "example", "email": "example", "phone": "example", "title": "example", "linkedinUrl": "example", "isChampion": true, "departedAt": "2026-04-15T12:00:00Z", "archivedAt": "2026-04-15T12:00:00Z", "doNotContact": true, "externalIds": [ { "source": "example", "id": "example" } ], "engagementsCount": 1, "lastEngagementAt": "2026-04-15T12:00:00Z", "createdAt": "2026-04-15T12:00:00Z", "updatedAt": "2026-04-15T12:00:00Z", "links": { "self": "example" } } ], "totalCount": 1, "nextCursor": "example"}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" }}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
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.
Signed in.
As curl
$SONORA_TOKEN is your access token or an API key; the page never shows the token.