The Sonora API: read and change your customer data
from your own stack

Overview

Somewhere in your stack there’s a script that knows something Sonora should: a usage alert, a billing change, a CRM field that only your ops team keeps current. And somewhere else there’s a system that should know what Sonora knows: the health score, the open issues, the last time anyone talked to the account. The Sonora API connects the two, so your own tools can read and change your customer data without anyone exporting a CSV.

It’s plain HTTPS and JSON at one base URL, authenticated with an API key that belongs to your workspace.

What you can reach

Each resource has its own scope, so a key only opens what its integration needs:

• Customers — list and look up accounts, with ARR, stage, owner, renewal date, custom fields, health, and eCSAT on every record. Create customers, change their fields, manage account teams, archive and unarchive them, and define custom fields.
• Contacts — read the people at your customers, and mark someone do-not-contact so Sonora stops emailing them.
• Issues and feature requests — read what customers are asking for and struggling with, with the sources and quotes behind each. Resolve and reopen issues that no support ticket backs.
• Meetings and notes — read meeting summaries and attendees, read the notes your team shares on an account, and write new ones.
• Enrichments — create, edit, and run enrichments on customers from code. Runs spend your workspace’s credits.
• Workflows — start API-triggered workflows with your own payload, name the recipients by role, and poll what each run did.

Built to be wired into production

The details that make an integration safe to run unattended are in from the start:

• Scoped keys. Each key carries only the scopes you tick, plus an expiry. A write scope needs its resource’s read scope. You can only grant scopes your own role allows, and you can revoke a key at any time.
• Safe retries and updates. Creates take an Idempotency-Key, so a retry after a timeout doesn’t make a second customer. Customer, note, and enrichment updates support ETag and If-Match: send the resource’s ETag back as If-Match to reject a write if someone changed it in the meantime. Without that header, the last write wins.
• Predictable behavior. Cursor paging, per-key rate limits with Retry-After, a stable error code on every failure, and an X-Request-Id to quote to support.
• A stable contract. /v1 only grows. New fields and endpoints can appear, and anything that would break a client ships as /v2.

Try it before you write a line of code

The API reference is generated from the same definitions the API enforces, and every read endpoint has a Try it panel that runs the request against your own workspace. Sign in with Sonora, approve read access, and see real responses with the curl to reproduce them. The whole API is also published as an OpenAPI 3.1 document at https://api.usesonora.com/v1/openapi.json, so you can load it into Postman or generate a typed client.

Get started

In Sonora, open Settings → API → API keys, name a key, tick the scopes it needs, and copy it. It’s shown once. Then check it works:

curl https://api.usesonora.com/v1/me \
  -H "Authorization: Bearer sonora_sk_…"

From there, the API reference lists every endpoint, and there’s a step-by-step guide for starting Sonora workflows from n8n.