Add a note to a customer

POST

/customers/{customerId}/notes

const url = 'https://api.usesonora.com/v1/customers/example/notes';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"title":"example","contentMarkdown":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.usesonora.com/v1/customers/example/notes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "title": "example", "contentMarkdown": "example" }'

Write a shared note on a customer, from Markdown. Everyone in your workspace who can read notes sees it on the customer, with the key named as its author. Send an Idempotency-Key to make a retry safe.

Requires the notes:write scope. API keys only.

Authorizations

apiKey

Parameters

Path Parameters

customerId

required

string

The customer’s Sonora id — or, with idType, its id in another system, or its domain.

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.

Header Parameters

Idempotency-Key

string

>= 1 characters <= 255 characters

1–255 printable characters. A retry with the same key and request answers with the first call’s result instead of acting twice.

Request Body^required

application/json

A shared note to add to a customer.

object

title

Defaults to Untitled, as a new note in Sonora does.

string

>= 1 characters <= 255 characters

contentMarkdown

required

The note as Markdown: headings, lists, - [ ] checklists, links, emphasis and code. Raw HTML is shown as text, never rendered.

string

<= 50000 characters

Example^generated

{
  "title": "example",
  "contentMarkdown": "example"
}

Responses

201

The note, created.

application/json

A note your team shares on a customer.

object

required

string

customerId

required

string

title

required

string

contentMarkdown

required

The note as Markdown: headings, lists, checklists, links and emphasis kept.

string

contentText

required

The note as plain text, for search or a preview.

string

author

required

Who wrote a note: a person on your team, or an API key — never the person who created the key.

object

type

required

user for a note someone wrote in Sonora; api_key for one written through the API.

string

Allowed values: user api_key

name

required

The person’s name, or the API key’s. Null for a key since deleted.

string | null

email

required

The person’s email. Always null for an API key.

string | null

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

links

required

object

self

required

This resource’s canonical URL on the API host.

string

Example

{
  "author": {
    "type": "user"
  }
}

Headers

ETag

string

A fingerprint of the note’s title and body. Send it back as If-Match to update only if neither has changed since.

Idempotent-Replayed

string

true when this answers a retry with an earlier call’s Idempotency-Key: the first call’s body, replayed.

400

invalid_json: The request body is not valid JSON.

invalid_request: A parameter or body field is missing, malformed or unknown; details.issues names each.

application/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

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

401

unauthorized: The Authorization header is missing, or the key is invalid, revoked or expired.

application/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

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

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.

application/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

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

404

customer_not_found: No customer matches the id (and idType) in the path.

application/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

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

409

idempotency_key_in_use: A request with this Idempotency-Key is still being processed. Retry once it has finished.

application/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

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

413

payload_too_large: The request body is too large; details.maxBytes gives the limit.

application/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

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

422

idempotency_key_mismatch: The Idempotency-Key was used before with a different request.

application/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

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

429

rate_limited: Too many requests for this key; retry after Retry-After seconds.

application/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

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

500

internal_error: Something went wrong on Sonora’s side. Retry, and quote requestId if it persists.

application/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

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

Try it

Try it runs the reference's read endpoints, and this one changes data, so it needs an API key with the notes:write scope. Create a key in Sonora under Settings → API and call it from your own code.

Add a note to a customer

Authorizations

Parameters

Path Parameters

Query Parameters

Header Parameters

Request Bodyrequired

Examplegenerated

Responses

201

Example

Headers

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

404

Examplegenerated

409

Examplegenerated

413

Examplegenerated

422

Examplegenerated

429

Examplegenerated

500

Examplegenerated

Try it

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated