Skip to content
SonoraSonora API

Create an enrichment

POST
/enrichment-configs
curl --request POST \
  --url https://api.usesonora.com/v1/enrichment-configs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "title": "example", "description": "example", "prompt": "example", "outputType": "short_text", "options": [ "example" ], "multiple": true, "dataSources": [ "meetings" ] }'

Add an enrichment to your customers: a question the AI answers for each one, the shape of the answer, and what it may read. It is visible to everyone in the workspace, like one made in Sonora and shared. Creating it runs nothing and spends no credits — start a run with POST /enrichment-configs/{configId}/runs. Send an Idempotency-Key to make a retry safe.

Requires the enrichments:manage scope. API keys only.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “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 Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

An enrichment to add to every customer: a question for the AI, the shape of its answer, and what it may read.

object
title
required
string
>= 1 characters <= 120 characters
description
Any of:
string
<= 1000 characters
prompt
required

The question the AI answers for each customer, in plain language (Markdown is fine): What is the main reason this account might not renew?

string
>= 1 characters <= 12000 characters
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
options

select only, and required for it: the 2–10 values it picks from.

Array<string>
>= 2 items <= 10 items
multiple

select only: a value is a list of options rather than one. Defaults to false.

boolean
dataSources
required

What the AI may read to answer: the customer’s meetings, emails, notes, issues, feature_requests, product_usage, ecsat and engagement, or web_search. A run usually costs 1 credit per customer, or 4 with web_search, which also needs web search on your plan. emails is read with the access of the person who made the enrichment, so only one someone made in Sonora takes it: one created through the API has no owner.

Array<string>
>= 1 items <= 9 items
Allowed values: meetings emails notes issues feature_requests product_usage ecsat engagement web_search

Responses

Section titled “Responses”

201

Section titled “201”

The enrichment, created.

Media typeapplication/json

An enrichment: a field Sonora’s AI fills in on each record, from your calls, emails and tickets.

object
id
required

Stable across edits to the enrichment: the configId its values carry.

string
title
required
string
description
required
string | null
entityType
required

The kind of record it describes. Only customer today.

string
Allowed values: customer
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
options
required
Any of:
Array<string>
multiple
required

select only: whether a value is a list of options.

boolean
createdAt
required
string format: date-time
updatedAt
required

When the enrichment was last edited.

string format: date-time
links
required
object
self
required

This resource’s canonical URL on the API host.

string
Example
{
  "entityType": "customer",
  "outputType": "short_text"
}

Headers

Section titled “Headers”
ETag
string

A fingerprint of the enrichment’s current version. Send it back as If-Match to update only if nobody has edited it since.

Idempotent-Replayed
string

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

400

Section titled “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.

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

409

Section titled “409”

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

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

413

Section titled “413”

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

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

422

Section titled “422”

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

invalid_fields: A field’s value can’t be saved, so nothing was; details.issues names each field and why.

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

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