Run an enrichment
const url = 'https://api.usesonora.com/v1/enrichment-configs/example/runs';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"customerIds":["2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"],"all":true,"onlyMissing":true}'};
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/enrichment-configs/example/runs \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "customerIds": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "all": true, "onlyMissing": true }'Queue the enrichment to be worked out for some customers, or all of them, as running it in Sonora does. Runs spend credits: usually 1 per customer, or 4 when the enrichment reads web_search, and more for some enrichments made in Sonora, which read sources the API doesn’t name. If your workspace’s credits can’t cover the run, nothing is queued and the call answers 402 credits_exhausted. Values arrive on the customers as they are worked out — read them with GET /customers?include=enrichments. Send an Idempotency-Key so a retry of a run that answered doesn’t run and charge twice; see Run an enrichment for a call that got no answer.
Requires the enrichments:manage scope. API keys only.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The enrichment’s id.
Header Parameters
Section titled “Header Parameters”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”The customers to run the enrichment on: customerIds, or all.
object
Up to 100 customers to run it on, by Sonora id.
Run it on every customer that isn’t archived.
Skip customers that already have a value, so only the rest are run and charged. Defaults to false: every customer named is worked out again.
Responses
Section titled “Responses”The run is queued.
A run, queued: each customer’s value arrives as it is worked out.
object
How many customers the run was queued for — fewer than you named when some are outside the enrichment’s segment, or already have a value with onlyMissing.
Examplegenerated
{ "queued": 1}Headers
Section titled “Headers”true when this answers a retry with an earlier call’s Idempotency-Key: the first call’s body, replayed.
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.
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" }}credits_exhausted: Your workspace’s credits can’t cover the run, so nothing was queued; details.required and details.remaining give the credits.
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" }}enrichment_config_not_found: No enrichment with that id, or not one a key can read.
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" }}idempotency_key_in_use: A request with this Idempotency-Key is still being processed. Retry once it has finished.
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" }}payload_too_large: The request body is too large; details.maxBytes gives the limit.
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" }}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.
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
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.