Notes

Notes are what your team writes on a customer in Sonora: call prep, account plans, the context a new owner needs. Reading them needs a key with the notes:read scope; writing them needs notes:write as well. Every field is in the API reference; this page covers how to use them.

Only shared notes are readable. A note in Sonora starts out private to the person who wrote it, and a private note never shows up through the API — not in a list, and not by id. Once its author shares it with the team, a key can read it.

List a customer’s notes

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

{
  "data": [
    {
      "id": "5e6f…",
      "customerId": "c1d2…",
      "title": "Rollout plan",
      "contentMarkdown": "## Goals\n\nShip to **support** first.\n\n- [x] Kickoff\n- [ ] Training",
      "contentText": "Goals Ship to support first. Kickoff Training",
      "author": { "type": "user", "name": "Olive Ortiz", "email": "olive@yourco.com" },
      "createdAt": "2026-09-01T10:00:00.000Z",
      "updatedAt": "2026-09-02T10:00:00.000Z",
      "links": { "self": "https://api.usesonora.com/v1/notes/5e6f…" }
    }
  ],
  "nextCursor": null
}

Notes come newest first. Name the customer by its Sonora id, or by your own system’s id with idType — salesforce, hubspot, domain or custom_field:<key> — exactly as GET /customers/{customerId} does. A customer that doesn’t exist is 404 customer_not_found; one with no shared notes is an empty page.

The content

Each note comes two ways:

• contentMarkdown keeps the note’s structure: headings, bold and italic, links, bulleted and numbered lists, and checklists as - [x] / - [ ]. Use it to show the note somewhere else, or to hand it to a model.
• contentText is the words alone, on one line — for search, or a preview.

A note someone opened but never wrote in is an empty string in both.

updatedAt moves whenever anyone edits it.

GET /notes/{noteId} returns one note in the same shape, with an ETag. A private note is 404 note_not_found, as an unknown id is.

Who wrote it

author is who wrote the note, and its type says what kind of author that is:

• user — someone on your team, in Sonora: { "type": "user", "name": "Olive Ortiz", "email": "olive@yourco.com" }.
• api_key — an integration, through the API: { "type": "api_key", "name": "Zapier", "email": null }. The name is the key’s, as it’s called on Settings → API. A key’s note is never put down to the person who created the key; they may since have left, and the key belongs to your workspace. Revoking the key leaves its notes as they are, still under its name.

In Sonora, a note written through the API reads “via API · Zapier” where a person’s would show their avatar.

Write a note

A key with the notes:write scope can add notes to customers, and change or delete the notes written through the API. Use it to bring in what your team already writes elsewhere — a summary from your call recorder, a handover from your ticketing system — so it sits next to everything else Sonora knows about the account.

Add a note

POST /customers/{customerId}/notes writes a note from Markdown:

curl -X POST "https://api.usesonora.com/v1/customers/c1d2…/notes" \
  -H "Authorization: Bearer sonora_sk_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: call-summary-77120" \
  -d '{
    "title": "QBR follow-ups",
    "contentMarkdown": "## Asks\n\nThey want **SSO** before renewal.\n\n- [ ] Send the SSO timeline\n- [ ] Book a call with IT"
  }'

The answer is 201 Created with the note, in the shape GET /notes/{noteId} returns, and its ETag:

{
  "id": "9a8b…",
  "customerId": "c1d2…",
  "title": "QBR follow-ups",
  "contentMarkdown": "## Asks\n\nThey want **SSO** before renewal.\n\n- [ ] Send the SSO timeline\n- [ ] Book a call with IT",
  "contentText": "Asks They want SSO before renewal. Send the SSO timeline Book a call with IT",
  "author": { "type": "api_key", "name": "Zapier", "email": null },
  "createdAt": "2026-10-15T16:40:00.000Z",
  "updatedAt": "2026-10-15T16:40:00.000Z",
  "links": { "self": "https://api.usesonora.com/v1/notes/9a8b…" }
}

• contentMarkdown is required, up to 50,000 characters. Headings, bold and italic, links, lists, code and - [ ] checklists all come through, and your team can tick a checklist’s boxes in Sonora. HTML in the Markdown is shown as text, never rendered, so nothing you send can change how Sonora’s pages behave.
• title is optional, up to 255 characters; without it the note is “Untitled”, as a new note in Sonora is.
• A note written through the API is always shared: everyone in your workspace who can read notes sees it on the customer. There’s no private note for a key, because a key acts for no one in particular.

Name the customer by its Sonora id, or by your own system’s id with idType (?idType=salesforce), as for reading. An unknown customer is 404 customer_not_found.

Send an Idempotency-Key so a retry after a timeout can’t write the note twice: the retry gets the first call’s answer back, marked Idempotent-Replayed: true. See Idempotency.

Change a note

PATCH /notes/{noteId} changes a note’s title, its body, or both. Send only what you want to change:

curl -X PATCH https://api.usesonora.com/v1/notes/9a8b… \
  -H "Authorization: Bearer sonora_sk_…" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "Jd8m2Q0fKc1sVb7tYx4LhR9pWn3zEa6u"' \
  -d '{ "contentMarkdown": "## Asks\n\nThey want **SSO** before renewal.\n\n- [x] Send the SSO timeline\n- [ ] Book a call with IT" }'

The answer is the note as saved, with a new ETag. contentMarkdown replaces the whole body: to change part of it, read the note, edit its contentMarkdown, and send it back. A body equal to what the note already says is not a change.

Use If-Match when someone else might edit the note too. Your team can tick a checklist’s boxes in Sonora, and that changes the body. Send the ETag you read as If-Match, and if the note changed in between, nothing is written and the call answers 412 precondition_failed: read it again and apply your change to what’s there now. Without If-Match, the last write wins. See Conditional requests.

Delete a note

DELETE /notes/{noteId} deletes a note for good, as deleting it in Sonora does, and answers 204 No Content. A second delete is 404 note_not_found.

Which notes a key can change

A key can change or delete any note written through the API in your workspace — whichever key wrote it. Keys belong to the workspace rather than to a person, so a note one integration wrote can be kept up to date by its replacement; author still names the key that wrote it.

A key can’t change or delete a note someone wrote in Sonora: that’s theirs, and the call answers 403 note_not_editable. A private note can’t be seen at all, so it’s 404 note_not_found, as for a read.

Every change a key makes is recorded as that key’s, with the names of the fields it changed.