# Entrovox Developers: full documentation > Entrovox takes outbound-calling leads over a REST API. An AI voice agent calls each lead and warm-transfers qualified buyers to licensed agents; dispositions, transcripts and recordings come back to you. Base URL: https://api.entrovox.com/v1. Every page below is also available as Markdown at the same address with .md added. --- # Post leads, get outcomes back Send Entrovox a data lead. An AI voice agent calls it, follows up on the sequence we set up with you, and warm-transfers qualified buyers to your licensed agents. Dispositions, transcripts and recordings come back to you. - Base URL: `https://api.entrovox.com/v1` - Auth: `Authorization: ApiKey $ENTROVOX_KEY` - Format: JSON, E.164 phones ## Your first request `is_test` leads are stored and never called or texted. Safe to run right now. cURL: ```bash curl -X POST https://api.entrovox.com/v1/leads \ -H "Authorization: ApiKey $ENTROVOX_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "first_name": "Test", "last_name": "Lead", "phone": "+15555550100", "external_id": "hw-1", "is_test": true }' ``` Python: ```python import os, uuid, requests r = requests.post( "https://api.entrovox.com/v1/leads", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "first_name": "Test", "last_name": "Lead", "phone": "+15555550100", "external_id": "hw-1", "is_test": True, }, ) ``` Node.js: ```javascript import { randomUUID } from "node:crypto"; const res = await fetch("https://api.entrovox.com/v1/leads", { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, "Idempotency-Key": randomUUID(), "Content-Type": "application/json", }, body: JSON.stringify({ first_name: "Test", last_name: "Lead", phone: "+15555550100", external_id: "hw-1", is_test: true, }), }); ``` Response `201 Created`: ```json { "data": { "id": "7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40", "current_disposition": "pending", "is_test": true, "status_url": "https://api.entrovox.com/v1/leads/7c2e…" } } ``` ## Send us leads Pick the path that matches how you sell leads today. - [Direct post](/developers/post-a-live-lead): One lead at a time, as it arrives. First dial is immediate inside calling hours. `POST /v1/leads` - [Batch post](/developers/batch-post): Up to 500 aged or unsold leads per request, with one result per row. `POST /v1/leads/batch` - [MediaAlpha native post](/developers/mediaalpha-native-post): Post your MediaAlpha JSON unchanged. We map the fields to an Entrovox lead. OpenAPI spec · JSON or YAML - [Ping, then post](/developers/ping-before-you-post): Only if your publisher already speaks ping/post. A ping creates and reserves nothing. `POST /v1/leads/ping` ## Get outcomes back ### Poll the status URL (live) Every accepted lead returns a `status_url`. It holds the lead-level disposition and each call attempt, with links to its transcript, recording and analysis. - `current_disposition`: `qualified_transfer` - `calls[0].call_outcome`: `connected_transferred` - `calls[0].recording_url`: `/v1/calls/…/recording-url` ### Receive webhooks (preview) Signed events pushed to your URL. The contract is final; delivery turns on in a later release. Write your LMS on `call.recording.ready`. Events: `lead.accepted`, `call.completed`, `call.transferred`, `call.recording.ready`, `callback.scheduled`, and 5 more. [Webhooks reference](/developers/webhooks) ## API reference ### Leads - **POST** [Create a lead](/developers/reference/create-a-lead) - **POST** [Batch create leads](/developers/reference/create-leads-in-a-batch) - **POST** [Ping a lead](/developers/reference/ping-a-lead) - **GET** [Retrieve a lead](/developers/reference/retrieve-a-lead) - **GET** [List leads](/developers/reference/list-leads) - **POST** [Pause a lead](/developers/reference/pause-a-lead) - **POST** [Resume a lead](/developers/reference/resume-a-lead) ### Calls - **GET** [List a lead’s calls](/developers/reference/list-calls-for-a-lead) - **GET** [Retrieve call analysis](/developers/reference/retrieve-a-call-analysis) - **GET** [Retrieve a transcript](/developers/reference/retrieve-a-call-transcript) - **GET** [Get a recording URL](/developers/reference/retrieve-a-call-recording-url) ### Concepts - [Authentication and keys](/developers/authentication) - [Idempotency and safe retries](/developers/retries-and-idempotency) - [Rate limits](/developers/rate-limits) - [Dispositions](/developers/status-url#dispositions) - [Compliance: what we enforce](/developers/compliance) ### Webhooks and errors - [Event catalog](/developers/webhooks#event-catalog) - [Verify signatures](/developers/webhooks#verify-signatures) - [Retries and replay](/developers/webhooks#retries-and-replay) - [Error codes](/developers/errors) - [API reference](/developers/reference) ## Building with an AI coding assistant? Every page is also plain Markdown. Point Claude, Cursor or ChatGPT at the index and it reads the whole API. - [/developers/llms.txt](/developers/llms.txt) - [/developers/llms-full.txt](/developers/llms-full.txt) - [OpenAPI spec](https://api.entrovox.com/developer/openapi.json) ## All guides ### Get started - [Quickstart](/developers/quickstart) - [Authentication and keys](/developers/authentication) ### Send leads - [Post a live lead](/developers/post-a-live-lead) - [Batch post](/developers/batch-post) - [MediaAlpha native post](/developers/mediaalpha-native-post) - [Ping before you post](/developers/ping-before-you-post) - [Pause a lead you sold](/developers/pause-a-lead) ### Place calls - [Place a call](/developers/place-a-call) ### Get outcomes - [The status URL](/developers/status-url) - [Recordings and transcripts](/developers/recordings-and-transcripts) - [Webhooks](/developers/webhook-delivery) ### Go to production - [Safe retries and idempotency](/developers/retries-and-idempotency) - [Rate limits and volume](/developers/rate-limits) - [Compliance: what we enforce](/developers/compliance) - [Go-live checklist](/developers/go-live-checklist) --- # Quickstart Post a test lead, read it back, then send one we will call. About five minutes. > **Note** > > **You need an API key.** We mint one bound to your campaign once a partner agreement is in place. You do not set up campaigns, caller IDs or scripts: Entrovox runs those. [Request access](mailto:support@entrovox.com?subject=API%20access%20request) ## Export your key Keep it server-side. Every request sends it as `Authorization: ApiKey …`. `terminal` ```bash export ENTROVOX_KEY="sk_entrovox_…" ``` ## Post a test lead `"is_test": true` stores the lead and nothing else. We never call or text it, it never blocks a later live lead on the same phone, and it stays out of `GET /v1/leads`. **cURL** — `terminal` ```bash curl -X POST https://api.entrovox.com/v1/leads \ -H "Authorization: ApiKey $ENTROVOX_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "first_name": "Test", "last_name": "Lead", "phone": "+15555550100", "external_id": "hw-1", "is_test": true }' ``` **Python** — `quickstart.py` ```python import os, uuid, requests r = requests.post( "https://api.entrovox.com/v1/leads", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "first_name": "Test", "last_name": "Lead", "phone": "+15555550100", "external_id": "hw-1", "is_test": True, }, timeout=15, ) lead = r.json()["data"] print(lead["status_url"]) # bookmark this ``` **Node.js** — `quickstart.mjs` ```javascript import { randomUUID } from "node:crypto"; const res = await fetch("https://api.entrovox.com/v1/leads", { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, "Idempotency-Key": randomUUID(), "Content-Type": "application/json", }, body: JSON.stringify({ first_name: "Test", last_name: "Lead", phone: "+15555550100", external_id: "hw-1", is_test: true, }), }); const { data: lead } = await res.json(); console.log(lead.status_url); // bookmark this ``` ## Read it back from the status URL Every accepted lead returns a `status_url`. It is the one place outcomes land: the lead-level disposition, then each call attempt with its transcript, recording and analysis. **cURL** — `terminal` ```bash curl https://api.entrovox.com/v1/leads/7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40 \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` **Python** — `read_back.py` ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/leads/7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40", headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"}, timeout=15, ) print(r.json()["data"]["current_disposition"]) ``` **Node.js** — `read_back.mjs` ```javascript const res = await fetch( "https://api.entrovox.com/v1/leads/7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40", { headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}` } }, ); const { data: lead } = await res.json(); console.log(lead.current_disposition); ``` **Response 200 OK** ```json { "data": { "id": "7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40", "external_id": "hw-1", "current_disposition": "pending", "is_test": true, "calls": [] } } ``` ## Send a live lead Drop `is_test` and use your own lead id. Qualified leads warm-transfer to the campaign number we set up with you. These are the fields to send: **`first_name`** (string, required) Who to call. Not blank. **`last_name`** (string, required) Who to call. Not blank. **`phone`** (string, required) Phone in E.164, like `+14255551234`. **`external_id`** (string, required) Your lead id, unique per campaign. Makes retries safe. **`zip_code`** (string) 5-digit or ZIP+4. Sets the lead's timezone, which decides calling hours, when you send no `timezone` or US `state`. Missing geography still accepts: we queue, we do not reject. **`trustedform_cert_url`** (string) TrustedForm certificate URL (`https://cert.trustedform.com/` plus 40 hex characters). We check the format only: a malformed URL is `400 CONSENT_INVALID`, and you remain responsible for the certificate's validity. **`jornaya_leadid`** (string) Jornaya LeadiD. Stored, not validated. **`metadata`** (object) Your own extras, echoed back on reads. These keys can help an AI voice agent the agency has set up verify lead details. Send them here, not at the top level. - **`metadata.address`** (string) Street address. - **`metadata.city`** (string) City. - **`metadata.date_of_birth`** (string) ISO `YYYY-MM-DD`. > **Warning** > > **A definitive rejection means we will never call this lead.** `DNC_BLOCKED`, `VALIDATION_ERROR`, `CONSENT_INVALID`, `SOURCE_PAUSED` and `SOURCE_INACTIVE` create no row. Resell the lead and do not retry. Three errors are different and safe to retry: `409 IDEMPOTENCY_IN_PROGRESS` (the first request may still finish, so resend with the same `Idempotency-Key`), `429 RATE_LIMIT_EXCEEDED` and `503 PROVIDER_UNAVAILABLE` (wait for `Retry-After`). ## Endpoints used **POST** `/v1/leads` creates a lead. **GET** `/v1/leads/{id}` reads it back. ## Next steps Read [Authentication and keys](/developers/authentication) for what your key can reach, then [Post a live lead](/developers/post-a-live-lead) for the full field list. [Batch post](/developers/batch-post) takes 500 leads per request, [Safe retries and idempotency](/developers/retries-and-idempotency) says which codes to retry, and [Webhooks](/developers/webhook-delivery) will push outcomes instead of you polling. --- # Authentication and keys One header on every request. Partner keys are bound to a campaign; agency keys come from Settings. You post a data lead. An AI voice agent calls it, follows up on a sequence we already configured, and warm-transfers qualified buyers to your licensed agents. You get dispositions, transcripts and recordings back. You do not provision campaigns, caller IDs or scripts: Entrovox runs those. You integrate two things, posting leads and receiving outcomes. ## Base URL and format | | | |---|---| | Base URL | `https://api.entrovox.com/v1`. Every path in these guides is relative to it. | | Auth | `Authorization: ApiKey sk_entrovox_…`. We mint and bind a partner key; agencies create their own in Settings. | | Format | JSON. Success is `{ "data": … }`, and lists add `meta`. Errors are `{ "error": { "code", "message", … } }`, so branch on `code`, not on the sentence. | | Phone numbers | E.164, like `+14255551234`. | Send the key on every request and keep it server-side: **cURL** — `terminal` ```bash curl "https://api.entrovox.com/v1/leads?external_id=hw-1" \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` **Python** — `whoami.py` ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/leads", params={"external_id": "hw-1"}, headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"}, timeout=15, ) print(r.status_code, r.json()) ``` **Node.js** — `whoami.mjs` ```javascript const res = await fetch("https://api.entrovox.com/v1/leads?external_id=hw-1", { headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}` }, }); console.log(res.status, await res.json()); ``` A missing or malformed header is `401 AUTHENTICATION_REQUIRED`. A key that is not found or has the wrong format is `401 TOKEN_INVALID`. A key past its expiry is `401 API_KEY_EXPIRED`. ## Partner keys Partner keys we mint are bound to one campaign. You do not create campaigns or caller IDs, and the key already knows which campaign it posts to. - You may omit `lead_source_id` on writes. Naming a different campaign is `403 LEAD_SOURCE_NOT_ALLOWED`. - Call reads (`GET /v1/calls`) are scoped to your campaign. - `POST /v1/calls` is for agencies. A bound key gets `403 CALLS_NOT_ALLOWED_ON_BOUND_KEY`, and the AI voice agent, phone number and call stats routes are closed to it. - Your lead ids are unique per campaign. The same `external_id` posted to another campaign is a separate lead. > **Note** > > **Keys are shown once.** We show the full key when we mint it. If a key lands in a log or a ticket, tell us and we will rotate it. [Request access](mailto:support@entrovox.com?subject=API%20access%20request) ### Scopes **`read`** (scope) `GET` leads, calls and artifacts, plus ping. **`write`** (scope) Everything `read` can do, plus post, batch, pause and resume. `write` implies `read`. A `read` key that tries to write is `403 INSUFFICIENT_SCOPE`. ## Agency keys An agency creates its own keys to place calls and read their outcomes. In the console, go to **Settings → API Keys → Create key**, choose a permission tier and copy the key. It is shown only once. | Tier | Can do | Mirrors | |---|---|---| | Read & write | Initiate calls, post, pause and resume leads, and read call and lead data | An admin | | Read only | Read call and lead data only | A member | Keys can carry an optional expiry and can be revoked at any time. A revoked or expired key stops working within about a minute. Once you have a key, [place your first call](/developers/place-a-call). An API key reaches only the public API surface. Any other path answers `403 API_KEY_ENDPOINT_NOT_ALLOWED`, and so do the `/webhooks` routes today while webhook delivery is a preview. ## What this API does not cover Campaign setup, DID inventory, prompt edits, SIP and priced ping bids are out of scope. Entrovox operates those. `POST /v1/calls` is the agency one-shot dialer, and a campaign-bound partner key cannot use it. Questions while you integrate: reply to the thread that included your key, or email the Entrovox contact who provisioned you. ## Next steps [Post a live lead](/developers/post-a-live-lead) with your own ids, or read [Compliance: what we enforce](/developers/compliance) for what you certify before we activate your campaign. --- # Post a live lead Enroll one lead the moment it arrives. First dial is immediate inside calling hours. A live post is the [quickstart](/developers/quickstart) request with your own lead id and no `is_test`. We enroll the lead in the campaign your key is bound to, and an AI voice agent calls it. Qualified leads warm-transfer to the campaign number we provisioned with you. ## Post the lead Send the four required fields and any geography you have. Send a fresh `Idempotency-Key` with every request. **cURL** — `terminal` ```bash curl -X POST https://api.entrovox.com/v1/leads \ -H "Authorization: ApiKey $ENTROVOX_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "first_name": "Jordan", "last_name": "Lee", "phone": "+14255551234", "zip_code": "98101", "external_id": "px-88421" }' ``` **Python** — `post_lead.py` ```python import os, uuid, requests r = requests.post( "https://api.entrovox.com/v1/leads", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "first_name": "Jordan", "last_name": "Lee", "phone": "+14255551234", "zip_code": "98101", "external_id": "px-88421", }, timeout=15, ) r.raise_for_status() lead = r.json()["data"] print(lead["status_url"]) # persist this ``` **Node.js** — `post_lead.mjs` ```javascript import { randomUUID } from "node:crypto"; const res = await fetch("https://api.entrovox.com/v1/leads", { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, "Idempotency-Key": randomUUID(), "Content-Type": "application/json", }, body: JSON.stringify({ first_name: "Jordan", last_name: "Lee", phone: "+14255551234", zip_code: "98101", external_id: "px-88421", }), }); if (!res.ok) throw new Error(`${res.status} ${JSON.stringify(await res.json())}`); const { data: lead } = await res.json(); console.log(lead.status_url); // persist this ``` ## Read the 201 `201` means we enrolled the lead. First dial is immediate when we are inside TCPA calling hours and have capacity. Otherwise `next_attempt_at` tells you when. Persist `id` and `status_url`. **Response 201 Created** ```json { "data": { "id": "7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40", "external_id": "px-88421", "phone": "+14255551234", "current_disposition": "pending", "is_test": false, "replayed": false, "status_url": "https://api.entrovox.com/v1/leads/7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40", "calls_url": "https://api.entrovox.com/v1/leads/7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40/calls", "calls": [] } } ``` ## Know when we will not call If we will never call this lead (DNC, a bad phone, a paused campaign, invalid consent), you get a `4xx` and no row is created. Resell that lead and do not retry. The few codes that are safe to retry are in [Safe retries and idempotency](/developers/retries-and-idempotency). ## Fields **`first_name`** (string, required) Who to call. 1 to 200 characters, not blank. **`last_name`** (string, required) Who to call. 1 to 200 characters, not blank. **`phone`** (string, required) E.164. US and Canada numbers are `+1` plus 10 digits. Anything else is `400 VALIDATION_ERROR`. **`external_id`** (string, required) Your lead id, 1 to 128 characters, unique per campaign. Retries are safe. The same id posted to another campaign is a separate lead. **`lead_source_id`** (string) The campaign. A key bound to one campaign may omit it, and naming a different campaign is `403`. An unbound agency key must send it on every post. **`phone_alt`** (string) A second E.164 number. Stored. It is not dialed in v1. **`owned_line_of_business`** (string) Cross-sell: the line of business the person already has. **`target_line_of_business`** (string) The line of business we should quote. **`email`** (string) Stored on the lead. **`state`** (string) Two-letter USPS code. Sets the lead's timezone, which decides calling hours. A state wins over a ZIP and gives that state's main zone. **`zip_code`** (string) 5-digit or ZIP+4. With no `state` and no `timezone`, the ZIP sets the timezone, accurate to 5 digits in states with two zones. **`timezone`** (string) An IANA zone. It decides calling hours, so with a `state` it must be a zone that state uses. Otherwise `400 VALIDATION_ERROR` with `param` `timezone`. **`preferred_language`** (string, one of en, es) `es` opens the first call in Spanish. **`lead_generated_at`** (string) Your create time, as a date-time. Drives oldest-first and newest-first dial order. Defaults to when we received the post. **`is_test`** (boolean, default false) `true` stores a test lead we never call or text. Omit it for a real lead. See the [quickstart](/developers/quickstart). **`trustedform_cert_url`** (string) A TrustedForm certificate URL. We check the format only: a malformed URL is `400 CONSENT_INVALID`. **`jornaya_leadid`** (string) Jornaya LeadiD. Stored, not validated. **`metadata`** (object) Your own extras, echoed back on reads. Send them here, not at the top level: top-level fields we do not list are ignored. At most 64 KB serialized. > **Note** > > **Geography never blocks a post.** A missing ZIP, state or timezone still accepts: we queue the lead, we do not reject it. ## Address and date of birth If the agency's AI voice agent is set up to confirm details with the lead, it can use an address and date of birth you send. Nest them inside `metadata`: ```json "metadata": { "address": "9041 Orchard Ln, Austin, TX 78701", "city": "Austin", "date_of_birth": "1985-01-05" } ``` `date_of_birth` is ISO `YYYY-MM-DD`. By default, the AI uses these only to verify the lead, after the person on the line states a matching detail themselves, and it then confirms only part of a detail (for an address, the street name and never the house number). Some agency scripts instead read the details back to confirm them, once the person has identified themselves as the lead, and an address is then read as the street and unit only. Either way, the AI never shares them with a call screener, in a voicemail, or with anyone who says they are not the lead. `email` and `zip_code` are top-level fields, as above. ## Per-lead transfer numbers `transfer_phone` is not supported yet: any value is rejected with `400 VALIDATION_ERROR`. Qualified leads transfer to the campaign number we provisioned with you. ## Next steps Follow the lead with its [status URL](/developers/status-url), or send inventory in bulk with [Batch post](/developers/batch-post). --- # Batch post Send up to 500 aged or unsold leads in one request and reconcile one result per row. Batch post is for aged or unsold inventory. Each item has the same shape as a [single post](/developers/post-a-live-lead). The response has one result per input row, in the same order, so you can always reconcile. > **Warning** > > **HTTP 200 does not mean the whole batch landed.** A bad row never fails the batch. Persist every `status_url` and check each item's `status`. ## Post the batch **POST** `/v1/leads/batch` takes 1 to 500 leads. Put `is_test: true` on any row to store it as a test lead, the same as on a single post. **cURL** — `terminal` ```bash curl -X POST https://api.entrovox.com/v1/leads/batch \ -H "Authorization: ApiKey $ENTROVOX_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "leads": [ { "first_name": "Alex", "last_name": "Nguyen", "phone": "+14255550001", "external_id": "inv-1001" }, { "first_name": "Sam", "last_name": "Ortiz", "phone": "+14255550002", "external_id": "inv-1002" } ] }' ``` **Python** — `post_batch.py` ```python import os, uuid, requests r = requests.post( "https://api.entrovox.com/v1/leads/batch", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "leads": [ { "first_name": "Alex", "last_name": "Nguyen", "phone": "+14255550001", "external_id": "inv-1001", }, { "first_name": "Sam", "last_name": "Ortiz", "phone": "+14255550002", "external_id": "inv-1002", }, ] }, timeout=60, ) r.raise_for_status() batch = r.json() for item in batch["items"]: print(item["index"], item["status"], item["status_url"] or item["code"]) ``` **Node.js** — `post_batch.mjs` ```javascript import { randomUUID } from "node:crypto"; const res = await fetch("https://api.entrovox.com/v1/leads/batch", { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, "Idempotency-Key": randomUUID(), "Content-Type": "application/json", }, body: JSON.stringify({ leads: [ { first_name: "Alex", last_name: "Nguyen", phone: "+14255550001", external_id: "inv-1001" }, { first_name: "Sam", last_name: "Ortiz", phone: "+14255550002", external_id: "inv-1002" }, ], }), }); const batch = await res.json(); for (const item of batch.items) console.log(item.index, item.status, item.status_url ?? item.code); ``` ## Reconcile every row `200` always means the request was well formed. Partial success lives in `items`. **Response 200 OK** ```json { "lead_source_id": "c222…", "created": 1, "replayed": 0, "rejected": 1, "items": [ { "index": 0, "status": "created", "external_id": "inv-1001", "lead_id": "a111…", "status_url": "https://api.entrovox.com/v1/leads/a111…", "code": null, "message": null }, { "index": 1, "status": "rejected", "external_id": "inv-1002", "lead_id": null, "status_url": null, "code": "DNC_BLOCKED", "message": "Phone is on the DNC list, so we did not create a lead. Remove it from your list or pause it; do not retry." } ] } ``` Each item's `status` is one of `created`, `replayed`, `conflict` or `rejected`. The totals `created`, `replayed` and `rejected` are conveniences. `rejected` counts rows whose status is `rejected` or `conflict`. ## Resend only what is safe to resend A row with `code` `PROVIDER_UNAVAILABLE` created nothing. It is safe to resend in a new batch, and its `external_id` makes the resend idempotent. Every other `rejected` row is final for that payload: fix it (a `VALIDATION_ERROR` row is fixable) or resell it. ## Choosing the campaign The campaign for the whole batch comes from the envelope, next to `leads`. **`lead_source_id`** (string) The campaign id. Required for an unbound agency key: without it the batch answers `422` with `param` `lead_source_id`. A bound partner key may omit it, and naming a different campaign is `403 LEAD_SOURCE_NOT_ALLOWED`. A campaign that is not in your organization is `404 LEAD_SOURCE_NOT_FOUND`. **`leads`** (array, required) 1 to 500 lead objects. A row-level `lead_source_id` does not pick the batch's campaign. A row that repeats the batch's campaign is accepted. A row that names a different campaign is rejected as that item, with `param` `lead_source_id`, and the rest of the batch continues. An agency key that is not bound to a campaign posts like this: **cURL** — `terminal` ```bash curl -X POST https://api.entrovox.com/v1/leads/batch \ -H "Authorization: ApiKey $ENTROVOX_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "lead_source_id": "YOUR_CAMPAIGN_ID", "leads": [ { "first_name": "Alex", "last_name": "Nguyen", "phone": "+14255550001", "external_id": "inv-1001" } ] }' ``` **Python** — `post_batch_agency.py` ```python import os, uuid, requests r = requests.post( "https://api.entrovox.com/v1/leads/batch", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "lead_source_id": "YOUR_CAMPAIGN_ID", "leads": [ { "first_name": "Alex", "last_name": "Nguyen", "phone": "+14255550001", "external_id": "inv-1001", }, ], }, timeout=60, ) r.raise_for_status() print(r.json()["items"]) ``` **Node.js** — `post_batch_agency.mjs` ```javascript import { randomUUID } from "node:crypto"; const res = await fetch("https://api.entrovox.com/v1/leads/batch", { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, "Idempotency-Key": randomUUID(), "Content-Type": "application/json", }, body: JSON.stringify({ lead_source_id: "YOUR_CAMPAIGN_ID", leads: [ { first_name: "Alex", last_name: "Nguyen", phone: "+14255550001", external_id: "inv-1001" }, ], }), }); if (!res.ok) throw new Error(`${res.status} ${await res.text()}`); console.log((await res.json()).items); ``` ## Rules that apply to every batch - **A bad row never fails the batch.** DNC, a bad phone, a missing `external_id` or a paused campaign comes back as a `rejected` item with its `code`. The whole request fails only when it is malformed (`422`: no `leads`, an empty array, more than 500 rows) or names a campaign your key cannot use (`403 LEAD_SOURCE_NOT_ALLOWED`, `404 LEAD_SOURCE_NOT_FOUND`). - **Rows that share a phone run in order.** Rows run in parallel, except that rows with the same `phone` (or `external_id`) run in input order. The first is `created`; a later one is `conflict` (`LEAD_PHONE_CONFLICT`) or `replayed`. - **Retrying a whole batch.** The batch `Idempotency-Key` must be a UUID, or the request gets `400 VALIDATION_ERROR`. Send the same key and the same body. You get the original response back and no row is processed again. - **Limits.** 500 leads per request and 20 batches per minute on a standard partner key. See [Rate limits and volume](/developers/rate-limits). ## Next steps Follow each created lead from its [status URL](/developers/status-url), and read [Safe retries and idempotency](/developers/retries-and-idempotency) before you automate resends. --- # MediaAlpha native post Post your native insurance JSON unchanged. We map it to an Entrovox lead, so you do not remap fields. Post your native insurance JSON. We map it. An AI voice agent calls the lead and warm-transfers a qualified buyer to the customer's licensed agents. One API key is one customer campaign: one agency and one line of business. A second agency gets a second key. A second vertical for the same agency, such as auto and home, gets a second key and its own URL. For the generic partner contract, start at the [quickstart](/developers/quickstart). ## OpenAPI specification Download the complete OpenAPI 3.1 specification for the MediaAlpha lead intake adapter, and import it into Postman, Insomnia or your API gateway to explore and test the endpoint. - [OpenAPI JSON](https://api.entrovox.com/developer/mediaalpha/openapi.json) - [OpenAPI YAML](https://api.entrovox.com/developer/mediaalpha/openapi.yaml) ## Endpoint | Form | Request | |---|---| | Header (preferred) | `POST https://api.entrovox.com/v1/leads/mediaalpha` | | URL only | `POST https://api.entrovox.com/v1/leads/mediaalpha/` | Send `Content-Type: application/json`. The body is your flat lead object. ## Auth - Preferred: `Authorization: ApiKey sk_entrovox_…`. - URL form: the same key is the last path segment. Use it when your delivery config can set a URL and cannot set a header. - Never put the key in the query string (`api_key`, `key`, `token` and similar). That returns `400`. - If you send both a header and a path key, they must be the same key. A mismatch is `401 TOKEN_INVALID`. - The key is bound to one Entrovox organization and one `api` campaign. A different `lead_source_id` in the body is `403 LEAD_SOURCE_NOT_ALLOWED`, so omit `lead_source_id`. - A read-only key cannot post: `403 INSUFFICIENT_SCOPE`. > **Warning** > > **Treat a URL that contains the key like a password.** We show the full key once, when we mint it. If that URL is copied into a proxy log or a ticket, tell us and we will rotate the key. ## Field mapping | Your field | Our field | Required | |---|---|---| | `contact_first_name` | `first_name` | Yes | | `contact_last_name` | `last_name` | Yes | | `phone` | `phone`, as E.164 `+1` plus 10 digits | Yes | | `unique_identifier`, else `token` | `external_id` | Yes: one of the two, as a non-empty string. `null` counts as absent | | `email` | `email` | No | | `zip` | `zip_code`. Residence `state` and timezone come from the ZIP only | Yes | | TrustedForm names below | `trustedform_cert_url` | No | | Jornaya names below | `jornaya_leadid` | No | | Lead-time names below | `lead_generated_at` | No | | Every other field | `metadata`, same name, same JSON type | No | `unique_identifier` wins when both it and `token` are present, even if they differ. `token` is still stored in `metadata`. A post with `"unique_identifier": null` and no `token` is `422` and is not enrolled. We do not fall back to a Jornaya or TrustedForm id, because `unique_identifier` is the id you use to look the lead up and reconcile returns. ### Phone Send 10 digits, like `3602179499`. A leading `1`, `+1`, spaces, dashes and parentheses are accepted. The area code and exchange cannot start with `0` or `1`. We store `+13602179499`. ### ZIP, state, timezone We do not read `driver_1_license_state` or a posted `state` as the residence. Those values stay in `metadata`. State comes from `zip`. When that ZIP is one timezone, we store it: `90210` becomes `CA` and `America/Los_Angeles`, `79901` (El Paso) becomes `TX` and `America/Denver`, and `32501` (Pensacola) becomes `FL` and `America/Chicago`. A ZIP we can place in a state but not in one zone is still enrolled. We store the state and do not pick a zone, so calling hours have to be legal in every zone that state uses. A missing ZIP, or a ZIP we cannot place in a US state, is `400` and is not enrolled. We do not guess the state from the phone area code, and we do not use the agency timezone for that lead. Send `zip` as text so leading zeroes survive, like `"02134"`. A JSON number is accepted and padded to 5 digits: `2134` becomes `02134`. ### Lines of business One key is one campaign. The campaign's configured line of business (`auto`, `home`, `medicare`, `life`, `health`) decides which script the AI voice agent runs and what we store as the lead's `owned_line_of_business` and `target_line_of_business`. We do not use the payload to pick the campaign, but we do refuse a post whose fields contradict it. `vehicle_*`, `driver_*` or `incident_*` fields on a home key, or `properties_*` fields on an auto key, are `400 VALIDATION_ERROR` with `param` `lead_source_id` and no lead. A post with both kinds of fields, or neither, is accepted. Campaigns on other lines are not checked. Send each vertical to its own key and URL: auto to the auto campaign's key, home to the home campaign's key. A cross-sell campaign rejects the post with `CROSS_SELL_PAIR_INVALID`. **One phone, one live lead per agency.** A phone whose existing lead is still in a live sequence (pending or connected) in one of the agency's active campaigns is `409 LEAD_PHONE_CONFLICT`, whether or not that lead is paused. The second post is not enrolled, unless the agency has allowed duplicate phones. A lead whose sequence already finished does not block: the second post is `201` and a new lead. A consumer who requests both an auto and a home quote while the first lead is live is therefore enrolled once, under whichever post arrived first. Treat that `409` as a duplicate for returns reconciliation, not as a quality reject. ### Consent (optional) A lead without consent fields is still accepted. The agency certifies consent on the campaign before it is activated. **TrustedForm.** The first non-empty value wins. A second non-empty value must be the same certificate or we return `400`. A 40-character hex id is expanded to `https://cert.trustedform.com/`. We read these names: `trustedform_cert_url`, `trusted_form_cert_url`, `trustedform_url`, `trusted_form_url`, `trustedform`, `trusted_form`, `xxTrustedFormCertUrl`, `xxTrustedFormToken`, `trustedform_token`, `tf_cert_url`, and `trusted_form_certificate_id` (the home sample's name, a 40-character hex id). **Jornaya LeadID.** The same first-non-empty rule. Stored, not format-checked, at most 256 characters. A second non-empty Jornaya name must carry the same id or we return `400`, with `param` set to the later name. We read these names: `jornaya_leadid`, `jornaya_lead_id`, `leadid_token`, `universal_leadid`, `jornaya_token`, `leadid`, and `leadid_id` (the home sample's name). The field we consumed is removed from `metadata`. Any other consent-looking name stays in `metadata` and is not treated as consent. **TCPA flags.** `tcpa_call_consent` is read. `"0"`, `0` (any numeric zero, including `0.0`), `false` or `"false"` means the consumer did not consent to calls, and the post is `400 CONSENT_INVALID` with `param` `tcpa_call_consent` and no lead. Resell it. Any other value, or no field, is accepted and stored. `tcpa_sms_consent`, `tcpa_email_consent`, `tcpa_text` and `tcpa_url` are stored in `metadata` as sent and are not read. ### Lead time (optional) We use the first non-empty of `lead_generated_at`, `lead_timestamp`, `date_created`, `submitted_at` and `submission_time`, as ISO-8601. If it is missing or not a date we accept, we use the time we received the post. Consent timestamps are not lead time. ### Other fields Vehicle, driver, property and coverage fields stay in `metadata`. That includes empty strings, numbers that arrive as strings, real numbers (`vehicle_1_year`, `properties_1_year_built`) and a tab-separated string (`vehicle_1_year_make_model_base`). The property address in a home post (`properties_1_address`, `properties_1_city`, `properties_1_state`, `properties_1_zip`) is stored and is not the residence. `state`, timezone and calling hours come from `zip`, because we call the person, not the property. Limits: 64 KB, nesting depth 32, no NUL (`U+0000`). `_entrovox_source_status_at_arrival` is reserved and returns `400`. > **Warning** > > **Do not send `is_test` or `transfer_phone`.** Both are rejected until those features are enabled. `true`, `"true"`, `"1"` and `1` for `is_test` are rejected (`400`, `param` `is_test`) and never enrolled as a live lead. Any other `is_test` value is also rejected, except `false`, `0` and `"0"`, which are accepted as a live lead. Qualified buyers transfer to the campaign number we configured with the agency. ## Auto example Post to the auto campaign's key. The sample below is trimmed to the fields that matter. Send every field you have: whatever we do not map lands in `metadata`. **cURL** — `terminal` ```bash curl -X POST https://api.entrovox.com/v1/leads/mediaalpha \ -H "Authorization: ApiKey $ENTROVOX_KEY" \ -H "Content-Type: application/json" \ -d '{ "unique_identifier": "AD7RL34G4CQNGKFP27AX6ANP27AX6ABEHI", "contact_first_name": "Pamela", "contact_last_name": "Silverman", "phone": "3602179499", "email": "person@quotelab.com", "zip": "90210", "address": "120 Jenkins Rd", "city": "Beverly Hills", "vehicle_1_year": 2024, "vehicle_1_make": "HONDA", "vehicle_1_model": "CIVIC SI", "vehicle_1_vin": "19XFE1E50RE000000", "driver_1_birth_date": "1976-07-17", "driver_1_license_state": "GA", "currently_insured": "1", "current_company": "Progressive" }' ``` **Python** — `mediaalpha_auto.py` ```python import os, requests r = requests.post( "https://api.entrovox.com/v1/leads/mediaalpha", headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"}, json={ "unique_identifier": "AD7RL34G4CQNGKFP27AX6ANP27AX6ABEHI", "contact_first_name": "Pamela", "contact_last_name": "Silverman", "phone": "3602179499", "email": "person@quotelab.com", "zip": "90210", "address": "120 Jenkins Rd", "city": "Beverly Hills", "vehicle_1_year": 2024, "vehicle_1_make": "HONDA", "vehicle_1_model": "CIVIC SI", "vehicle_1_vin": "19XFE1E50RE000000", "driver_1_birth_date": "1976-07-17", "driver_1_license_state": "GA", "currently_insured": "1", "current_company": "Progressive", }, timeout=15, ) r.raise_for_status() lead = r.json()["data"] print(r.status_code, lead["status_url"]) ``` **Node.js** — `mediaalpha_auto.mjs` ```javascript const res = await fetch("https://api.entrovox.com/v1/leads/mediaalpha", { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ unique_identifier: "AD7RL34G4CQNGKFP27AX6ANP27AX6ABEHI", contact_first_name: "Pamela", contact_last_name: "Silverman", phone: "3602179499", email: "person@quotelab.com", zip: "90210", address: "120 Jenkins Rd", city: "Beverly Hills", vehicle_1_year: 2024, vehicle_1_make: "HONDA", vehicle_1_model: "CIVIC SI", vehicle_1_vin: "19XFE1E50RE000000", driver_1_birth_date: "1976-07-17", driver_1_license_state: "GA", currently_insured: "1", current_company: "Progressive", }), }); if (!res.ok) throw new Error(`${res.status} ${await res.text()}`); const { data: lead } = await res.json(); console.log(res.status, lead.status_url); ``` **Response 201 Created** ```json { "data": { "id": "7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40", "external_id": "AD7RL34G4CQNGKFP27AX6ANP27AX6ABEHI", "first_name": "Pamela", "last_name": "Silverman", "phone": "+13602179499", "email": "person@quotelab.com", "state": "CA", "zip_code": "90210", "timezone": "America/Los_Angeles", "current_disposition": "pending", "status_url": "https://api.entrovox.com/v1/leads/7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40", "metadata": { "address": "120 Jenkins Rd", "city": "Beverly Hills", "driver_1_birth_date": "1976-07-17", "driver_1_license_state": "GA", "vehicle_1_make": "HONDA", "vehicle_1_year": 2024, "currently_insured": "1", "current_company": "Progressive" } } } ``` Every other field you post is in `metadata` too. `contact_first_name`, `contact_last_name`, `phone`, `email`, `zip` and `unique_identifier` are not repeated there. `driver_1_license_state` stays `GA` in `metadata`, while the residence state on the lead is `CA`. Fields not shown on the lead follow the lead object in the [API reference](/developers/reference/lead-object). ## Home example Post to the home campaign's key. The consent fields use the names MediaAlpha's home sample ships: `trusted_form_certificate_id` and `leadid_id`. **cURL** — `terminal` ```bash curl -X POST https://api.entrovox.com/v1/leads/mediaalpha \ -H "Authorization: ApiKey $ENTROVOX_KEY" \ -H "Content-Type: application/json" \ -d '{ "unique_identifier": "HOME-SAMPLE-0001", "contact_first_name": "Pamela", "contact_last_name": "Silverman", "phone": "(360) 217-9499", "email": "person@quotelab.com", "zip": "90210", "trusted_form_certificate_id": "0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f", "leadid_id": "00000000-0000-4000-8000-000000000000", "tcpa_call_consent": "1", "properties_1_address": "1 Home St", "properties_1_city": "Redmond", "properties_1_state": "WA", "properties_1_zip": "98052", "properties_1_year_built": 1991, "properties_1_property_type": "Single Family Home" }' ``` **Python** — `mediaalpha_home.py` ```python import os, requests r = requests.post( "https://api.entrovox.com/v1/leads/mediaalpha", headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"}, json={ "unique_identifier": "HOME-SAMPLE-0001", "contact_first_name": "Pamela", "contact_last_name": "Silverman", "phone": "(360) 217-9499", "email": "person@quotelab.com", "zip": "90210", "trusted_form_certificate_id": "0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f", "leadid_id": "00000000-0000-4000-8000-000000000000", "tcpa_call_consent": "1", "properties_1_address": "1 Home St", "properties_1_city": "Redmond", "properties_1_state": "WA", "properties_1_zip": "98052", "properties_1_year_built": 1991, "properties_1_property_type": "Single Family Home", }, timeout=15, ) r.raise_for_status() lead = r.json()["data"] print(r.status_code, lead["status_url"]) ``` **Node.js** — `mediaalpha_home.mjs` ```javascript const res = await fetch("https://api.entrovox.com/v1/leads/mediaalpha", { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ unique_identifier: "HOME-SAMPLE-0001", contact_first_name: "Pamela", contact_last_name: "Silverman", phone: "(360) 217-9499", email: "person@quotelab.com", zip: "90210", trusted_form_certificate_id: "0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f", leadid_id: "00000000-0000-4000-8000-000000000000", tcpa_call_consent: "1", properties_1_address: "1 Home St", properties_1_city: "Redmond", properties_1_state: "WA", properties_1_zip: "98052", properties_1_year_built: 1991, properties_1_property_type: "Single Family Home", }), }); if (!res.ok) throw new Error(`${res.status} ${await res.text()}`); const { data: lead } = await res.json(); console.log(res.status, lead.status_url); ``` **Response 201 Created** ```json { "data": { "id": "3f9d2c61-7a4e-4b0b-9c21-5e6f7a8b9c0d", "external_id": "HOME-SAMPLE-0001", "first_name": "Pamela", "last_name": "Silverman", "phone": "+13602179499", "email": "person@quotelab.com", "state": "CA", "zip_code": "90210", "timezone": "America/Los_Angeles", "trustedform_cert_url": "https://cert.trustedform.com/0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f", "jornaya_leadid": "00000000-0000-4000-8000-000000000000", "current_disposition": "pending", "status_url": "https://api.entrovox.com/v1/leads/3f9d2c61-7a4e-4b0b-9c21-5e6f7a8b9c0d", "metadata": { "properties_1_address": "1 Home St", "properties_1_city": "Redmond", "properties_1_state": "WA", "properties_1_zip": "98052", "properties_1_year_built": 1991, "properties_1_property_type": "Single Family Home", "tcpa_call_consent": "1" } } } ``` `(360) 217-9499` is stored as `+13602179499`. `trusted_form_certificate_id` became `trustedform_cert_url` and `leadid_id` became `jornaya_leadid`. Neither is repeated in `metadata`. The property is in Redmond, WA, and the lead's state and calling window come from the contact ZIP `90210`. ## Errors ```json { "error": { "code": "VALIDATION_ERROR", "message": "phone must be a 10-digit US or Canadian number, so we did not create a lead. Send it like 3602179499 (a leading 1 is ok) and retry.", "param": "phone" } } ``` `param` is your field name. | HTTP | Code | When | |---|---|---| | 422 | `VALIDATION_ERROR` | Missing `contact_first_name`, `contact_last_name`, `phone`, or both ids. `"unique_identifier": null` with no `token` counts as missing | | 400 | `VALIDATION_ERROR` | A blank name, a bad `phone`, bad JSON types, or a reserved metadata key | | 400 | `CONSENT_INVALID` | A TrustedForm value is not a certificate URL or a 40-hex id. `param` is the field you sent | | 400 | `CONSENT_INVALID` | `tcpa_call_consent` is an explicit no. `param` is `tcpa_call_consent` | | 400 | `VALIDATION_ERROR` | The post's fields belong to the other vertical. `param` is `lead_source_id` | | 400 | `VALIDATION_ERROR` | Two TrustedForm names with different certificates, or two Jornaya names with different ids. `param` is the later name | | 401 | `AUTHENTICATION_REQUIRED` | No campaign key at all, neither header nor path segment | | 401 | `TOKEN_INVALID` | A malformed or mismatched campaign key | | 403 | `LEAD_SOURCE_NOT_ALLOWED` | The body's `lead_source_id` is not this key's campaign | | 403 | `INSUFFICIENT_SCOPE` | The key cannot create leads | | 409 | `EXTERNAL_ID_CONFLICT` | The same `unique_identifier` is already stored on this campaign with a different phone. The same id posted to the agency's other campaign is a separate lead | | 409 | `LEAD_PHONE_CONFLICT` | That phone is already enrolled under another id. `details` is empty when the existing lead belongs to a sibling campaign this key cannot read. A duplicate, not a quality reject | | 409 | `IDEMPOTENCY_IN_PROGRESS` | The same `Idempotency-Key` is still running: retry the same body | | 429 | `RATE_LIMIT_EXCEEDED` | Over the key's limit. `Retry-After` is set | | 503 | `PROVIDER_UNAVAILABLE` | We could not finish a compliance check or the campaign lookup. `Retry-After` is set | ## Idempotency and retries - `unique_identifier`, or `token` when that is the id, is the durable lead id. - The same id, phone and campaign returns `200` with the header `X-Duplicate: external_id` and `data.replayed=true`. It is one lead. - Send the optional `Idempotency-Key` header as a UUID. The same key and the same body returns the original response. A create stays `201`, with `X-Idempotency-Replayed: true`. - Do not retry a `4xx`, except `409 IDEMPOTENCY_IN_PROGRESS` (resend the same body with the same key) and `429 RATE_LIMIT_EXCEEDED` (wait for `Retry-After`, then resend with the same `Idempotency-Key`). - Retry a `5xx` or `503` with the same body and the same `Idempotency-Key`, and honor `Retry-After`. See [Safe retries and idempotency](/developers/retries-and-idempotency) for the general rules. ## Rate limit 100 requests per minute per key. The MediaAlpha route has no bucket of its own: it falls in the shared default bucket, which is separate from the `POST /leads`, `POST /leads/batch` and `POST /leads/ping` buckets. Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. The URL form counts as that key, not as an anonymous IP. A query-string key is `400` and still counts toward the anonymous per-IP limit. ## Test procedure 1. We send one key per customer campaign, one per vertical, each with the header URL and the path URL. Run steps 2 to 6 before we activate the campaigns, or only with phones you control, because a post to an active campaign dials. 2. Post the auto sample to the auto key. Expect `201`, `phone` `+13602179499`, `external_id` equal to `unique_identifier`, and `state` `CA`. 3. Post the same body again. Expect `200`, `X-Duplicate: external_id` and no second lead. 4. Post the home sample to the home key, with a non-null `unique_identifier` and a phone you control that differs from step 2. Both samples carry `360-217-9499`: the same phone on an active sibling campaign is `409 LEAD_PHONE_CONFLICT`, and before activation the second post is `201` and leaves two leads on one phone, which we delete before activating. Expect `201`, `trustedform_cert_url` and `jornaya_leadid` set, and `state` `CA`. 5. Drop `contact_first_name`. Expect `422` and `"param": "contact_first_name"`. 6. Send `"phone": "123"`. Expect `400` and `"param": "phone"`. 7. A live post dials. For a connectivity test, use a phone you control and tell us before you send it. ## Please confirm Confirm these with us before go-live: - `unique_identifier` is populated on every production post, auto and home. A null id is `422` and the lead is not enrolled. - Each vertical posts to its own key and URL. The auto campaign's key receives only auto leads and the home campaign's key receives only home leads. Tell us which of your campaign ids maps to which URL. - Will you send a lead timestamp, and under which name? Without one we use the time we received the post. - Can your delivery config set `Authorization`, or only a URL? - `zip` is the contact's residence ZIP. We will not treat `driver_1_license_state`, a posted `state` or `properties_1_zip` as the residence. - Production posts are this flat JSON object. Numbers may be strings, and one vehicle string may contain tabs. ## Next steps Follow each lead from its [status URL](/developers/status-url), and run the [go-live checklist](/developers/go-live-checklist). --- # Ping before you post An optional accept or reject pre-check for publishers that already run ping and post. Use ping only if your publisher already speaks ping and post. Direct post is the default path. A ping creates nothing, reserves nothing and ignores `Idempotency-Key`. A `read` key is enough. > **Note** > > **Ping is not a priced bid and not a reservation.** An accepted ping does not hold capacity for the post that follows it. ## Ping with the lead's phone and ZIP **POST** `/v1/leads/ping` is a POST on purpose: the phone must not land in query logs. It uses the same field names as a lead, so send `zip_code`, not `zip`. **cURL** — `terminal` ```bash curl -X POST https://api.entrovox.com/v1/leads/ping \ -H "Authorization: ApiKey $ENTROVOX_KEY" \ -H "Content-Type: application/json" \ -d '{"phone": "+14255551234", "zip_code": "98101"}' ``` **Python** — `ping.py` ```python import os, requests r = requests.post( "https://api.entrovox.com/v1/leads/ping", headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"}, json={"phone": "+14255551234", "zip_code": "98101"}, timeout=15, ) r.raise_for_status() ping = r.json() print(ping["accepted"], ping["reason"], ping["queued_reason"]) ``` **Node.js** — `ping.mjs` ```javascript const res = await fetch("https://api.entrovox.com/v1/leads/ping", { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ phone: "+14255551234", zip_code: "98101" }), }); const ping = await res.json(); console.log(ping.accepted, ping.reason, ping.queued_reason); ``` ## Branch on accepted **Response 200 OK** ```json { "accepted": true, "reason": null, "queued_reason": null, "lead_source_id": "c222…" } ``` `accepted: false` is the never-accepted class, with a `reason` of `dnc`, `already_enrolled`, `invalid_phone`, `source_paused` or `source_inactive`. Resell that lead. After-hours and unknown geography still return `accepted: true`, with a `queued_reason` of `outside_hours` or `missing_geography`. Post the lead: we call when we can. ## Post the lead Send the accepted lead with [Post a live lead](/developers/post-a-live-lead). A ping that answered `503 PROVIDER_UNAVAILABLE` means our DNC check could not run, so retry it after `Retry-After`. A campaign that is not in your organization is `404 LEAD_SOURCE_NOT_FOUND`, the same as a post. ## Fields All fields are optional. They match the lead write fields. **`phone`** (string) E.164. Without it, the phone checks are skipped. **`state`** (string) Two-letter USPS code. **`zip_code`** (string) 5-digit or ZIP+4. **`target_line_of_business`** (string) The line of business we should quote. **`lead_source_id`** (string) Campaign. A bound key may omit it. Naming another campaign is `403 LEAD_SOURCE_NOT_ALLOWED`. **`external_id`** (string) For the replay check below. Used for correlation only: it is not stored or echoed. ## Re-posting a lead you already sent Ping with its `phone` and `external_id`. Ping then answers the way the post would: `accepted: true` for a clean replay, and `dnc` or `already_enrolled` if the post would be refused. ## How a ping is decided The first match wins for `reason`: 1. The campaign is completed or otherwise not live: `source_inactive`. 2. The campaign is paused: `source_paused`. 3. `phone` is not a US or Canadian E.164 number: `invalid_phone`. 4. `phone` is on your DNC list, or a prior lead on it was marked DNC: `dnc`. 5. `phone` is in an active sequence under another lead: `already_enrolled`. ## Next steps Read [Rate limits and volume](/developers/rate-limits) for the ping bucket, then [Post a live lead](/developers/post-a-live-lead). --- # Pause a lead you sold Stop our calling sequence when your floor sold the lead on another path, and resume it if the sale falls through. If your floor sold a lead on another path, stop our sequence so we do not call someone who already has a buyer. A pause you send is recorded as yours, so it holds even against a callback the consumer booked. ## Pause the lead **POST** `/v1/leads/{id}/pause` needs the `write` scope. `{id}` is always the Entrovox lead id from our responses, never your `external_id`. Look a lead up by your own id with `GET /v1/leads?external_id=`. **cURL** — `terminal` ```bash curl -X POST https://api.entrovox.com/v1/leads/7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40/pause \ -H "Authorization: ApiKey $ENTROVOX_KEY" \ -H "Content-Type: application/json" \ -d '{"reason": "sold_elsewhere"}' ``` **Python** — `pause.py` ```python import os, requests lead_id = "7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40" r = requests.post( f"https://api.entrovox.com/v1/leads/{lead_id}/pause", headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"}, json={"reason": "sold_elsewhere"}, timeout=15, ) r.raise_for_status() print(r.json()["data"]) ``` **Node.js** — `pause.mjs` ```javascript const leadId = "7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40"; const res = await fetch(`https://api.entrovox.com/v1/leads/${leadId}/pause`, { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ reason: "sold_elsewhere" }), }); console.log((await res.json()).data); ``` **`reason`** (string) Why you paused, up to 140 characters. Echoed back as `paused_reason`. Do not reuse the reasons Entrovox uses for its own automatic pauses. ## Read the result **Response 200 OK** ```json { "data": { "paused_at": "2026-09-10T18:07:30Z", "paused_reason": "sold_elsewhere", "updated_count": 1, "already_paused": false } } ``` A call that is already ringing is not killed. It finishes, and we do not place the next one. Pausing a lead that is already paused answers `already_paused: true`. ## Resume it if the sale falls through **POST** `/v1/leads/{id}/resume` takes no body. **cURL** — `terminal` ```bash curl -X POST https://api.entrovox.com/v1/leads/7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40/resume \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` **Python** — `resume.py` ```python import os, requests lead_id = "7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40" r = requests.post( f"https://api.entrovox.com/v1/leads/{lead_id}/resume", headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"}, timeout=15, ) r.raise_for_status() print(r.json()["data"]) ``` **Node.js** — `resume.mjs` ```javascript const leadId = "7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40"; const res = await fetch(`https://api.entrovox.com/v1/leads/${leadId}/resume`, { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}` }, }); console.log((await res.json()).data); ``` The response carries `resumed_at`, `next_attempt_at`, `updated_count` and `already_resumed`. ## What you can and cannot resume Resuming works only on a pause your campaign's key set, including a key you rotated from. A pause your Entrovox contact, one of their integrations or the system set answers `409 LEAD_PAUSED_BY_AGENCY`. A lead Entrovox also runs elsewhere answers `409 LEAD_ENROLLED_ELSEWHERE`. A lead with no live sequence cannot be paused or resumed. That covers a test lead (`is_test: true`) and a lead whose sequence has already ended. Both answer `409 LEAD_NOT_PAUSEABLE` and change nothing. Pause and resume share a bucket of 60 requests per minute. See [Rate limits and volume](/developers/rate-limits). ## Next steps Check the lead's `paused` and `paused_reason` fields on its [status URL](/developers/status-url). --- # Place a call Dial one lead with an AI voice agent from your own caller ID, then read the outcome. For agencies with a Settings API key. The agency call API lets your systems start an AI voice agent call and read its outcome. It is for agencies. A campaign-bound partner key cannot place calls: it gets `403 CALLS_NOT_ALLOWED_ON_BOUND_KEY`. Create an agency key first in [Authentication and keys](/developers/authentication#agency-keys), with the **Read & write** tier. ## Call endpoints | Method | Path | Tier | Purpose | |---|---|---|---| | GET | `/voice-agents` | read | List your AI voice agents and get an `agent_id` | | GET | `/voice-agents/{id}` | read | One AI voice agent | | GET | `/phone-numbers` | read | List your numbers and get a caller ID | | GET | `/phone-numbers/{id}` | read | One number | | POST | `/calls` | write | Initiate an outbound call | | GET | `/calls` | read | List calls | | GET | `/calls/{id}` | read | Call status and detail | | GET | `/calls/{id}/analysis` | read | Post-call summary and outcome | | GET | `/calls/{id}/transcript` | read | Transcript | | GET | `/calls/{id}/recording-url` | read | Short-lived signed recording URL | The lead endpoints an agency key can also reach, `GET /leads`, `POST /leads`, `GET /leads/{id}`, `GET /leads/{id}/calls`, `POST /leads/{id}/pause` and `POST /leads/{id}/resume`, work as described in [Send leads](/developers/post-a-live-lead). A key that is not bound to a campaign sends `lead_source_id` on every lead post. ## Find an AI voice agent and a caller ID `agent_id` comes from your AI voice agents, and `from_number` must be a number you own. Both calls need only the `read` tier. Use the `id` of the AI voice agent and the `phone_number` of the number. **cURL** — `terminal` ```bash curl https://api.entrovox.com/v1/voice-agents \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` **Python** — `find_agent.py` ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/voice-agents", headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"}, timeout=15, ) agent = r.json()["data"][0] print(agent["id"]) ``` **Node.js** — `find_agent.mjs` ```javascript const res = await fetch("https://api.entrovox.com/v1/voice-agents", { headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}` }, }); const { data: agents } = await res.json(); console.log(agents[0].id); ``` **cURL** — `terminal` ```bash curl https://api.entrovox.com/v1/phone-numbers \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` **Python** — `find_number.py` ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/phone-numbers", headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"}, timeout=15, ) number = r.json()["data"][0] print(number["phone_number"]) ``` **Node.js** — `find_number.mjs` ```javascript const res = await fetch("https://api.entrovox.com/v1/phone-numbers", { headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}` }, }); const { data: numbers } = await res.json(); console.log(numbers[0].phone_number); ``` ## Place the call **POST** `/v1/calls` needs the `write` tier. Send an `Idempotency-Key` so a retry never dials twice. **cURL** — `terminal` ```bash curl -X POST https://api.entrovox.com/v1/calls \ -H "Authorization: ApiKey $ENTROVOX_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "to_number": "+15555551234", "from_number": "+15555550000", "agent_id": "agent_01J8K3Q7M2", "metadata": { "crm_id": "lead-42" } }' ``` **Python** — `place_call.py` ```python import os, uuid, requests r = requests.post( "https://api.entrovox.com/v1/calls", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "to_number": "+15555551234", "from_number": "+15555550000", "agent_id": "agent_01J8K3Q7M2", "metadata": {"crm_id": "lead-42"}, }, timeout=15, ) r.raise_for_status() call = r.json()["data"] print(call["id"], call["status"]) ``` **Node.js** — `place_call.mjs` ```javascript import { randomUUID } from "node:crypto"; const res = await fetch("https://api.entrovox.com/v1/calls", { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, "Idempotency-Key": randomUUID(), "Content-Type": "application/json", }, body: JSON.stringify({ to_number: "+15555551234", from_number: "+15555550000", agent_id: "agent_01J8K3Q7M2", metadata: { crm_id: "lead-42" }, }), }); const { data: call } = await res.json(); console.log(call.id, call.status); ``` **Response 201 Created** ```json { "data": { "id": "call_01J8K3Q7M2", "status": "initiated", "to_number": "+15555551234", "from_number": "+15555550000", "agent_id": "agent_01J8K3Q7M2", "scheduled_at": null, "created_at": "2026-07-03T15:00:00Z" } } ``` **`to_number`** (string, required) Who to call, in E.164. **`from_number`** (string, required) Your caller ID, in E.164. It must be a number you own: list yours with `GET /phone-numbers`. **`agent_id`** (string, required) The AI voice agent to use, from `GET /voice-agents`. **`variables`** (object) Key and value pairs injected into the AI voice agent's prompt, like `first_name`. **`metadata`** (object) A free-form object stored on the call and echoed back on reads. **`is_test`** (boolean) `true` marks an ad-hoc test call, excluded from your aggregate metrics. Use it only to call your own phone: test calls skip the spoken recording notice. **`scheduling`** (object) Dial later instead of now. - **`scheduling.scheduled_at`** (string) An ISO 8601 time. **`webhook_url`** (string) Where to send call events. Webhook delivery is a preview: the URL is accepted and stored, and nothing is sent yet. See [Webhooks](/developers/webhook-delivery). **`webhook_events`** (array) Which events to deliver once delivery is on. The default is `call.started`, `call.completed`, `call.failed` and `call.transferred`. `call.analysis.completed` and `call.answered` are opt-in: add them to receive them. `call.analysis.completed` is the last event for an agency callback. See [Webhooks](/developers/webhook-delivery#events). ## Get the outcome A call is asynchronous. Poll `GET /v1/calls/{id}` for `status`, then fetch the analysis, transcript and recording once the call has ended, as in [Recordings and transcripts](/developers/recordings-and-transcripts). Webhooks will push the same events once delivery ships. **cURL** — `terminal` ```bash curl https://api.entrovox.com/v1/calls/call_01J8K3Q7M2 \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` **Python** — `get_call.py` ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/calls/call_01J8K3Q7M2", headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"}, timeout=15, ) print(r.json()["data"]["status"]) ``` **Node.js** — `get_call.mjs` ```javascript const res = await fetch("https://api.entrovox.com/v1/calls/call_01J8K3Q7M2", { headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}` }, }); console.log((await res.json()).data.status); ``` ## Placing a test call Set `is_test: true` for a one-off call. It is the fastest way to check an AI voice agent end to end. It still respects DNC and calling hours, and it is excluded from your aggregate metrics. > **Warning** > > **Use a test call only to call your own phone.** Test calls skip the spoken recording notice, so never point one at a lead or any other person. In the samples below, replace `+1YOUROWNCELL` with your own mobile number in E.164. **cURL** — `terminal` ```bash curl -X POST https://api.entrovox.com/v1/calls \ -H "Authorization: ApiKey $ENTROVOX_KEY" \ -H "Content-Type: application/json" \ -d '{ "to_number": "+1YOUROWNCELL", "from_number": "+15555550000", "agent_id": "agent_01J8K3Q7M2", "is_test": true, "variables": { "first_name": "Alex" } }' ``` **Python** — `test_call.py` ```python import os, requests r = requests.post( "https://api.entrovox.com/v1/calls", headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"}, json={ "to_number": "+1YOUROWNCELL", "from_number": "+15555550000", "agent_id": "agent_01J8K3Q7M2", "is_test": True, "variables": {"first_name": "Alex"}, }, timeout=15, ) print(r.json()["data"]["id"]) ``` **Node.js** — `test_call.mjs` ```javascript const res = await fetch("https://api.entrovox.com/v1/calls", { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ to_number: "+1YOUROWNCELL", from_number: "+15555550000", agent_id: "agent_01J8K3Q7M2", is_test: true, variables: { first_name: "Alex" }, }), }); console.log((await res.json()).data.id); ``` ## Compliance is enforced Every call runs the same checks as the platform dialer: your internal DNC list and the destination's TCPA calling-hours window. A call outside the allowed window is rejected with a compliance error. It is not silently queued. To call later, include a `scheduling` block instead of relying on immediate dialing. A scheduled call is checked again when it fires. If the destination's window is closed at that moment, or closes within the next minute, the call is not dialed: it moves to the next time the window opens. If the destination's timezone cannot be resolved, the call fails instead of dialing. DNC is checked again at that moment too. If the number was added to your DNC list after you scheduled the call, or its lead is now marked Do Not Call, the call fails and is never dialed, and its disposition is `dnc_skipped`. If the DNC check itself cannot run, the call also fails rather than dialing. ## Idempotency (recommended) Pass a unique `Idempotency-Key` header. If a request times out and you retry with the same key and the same body, Entrovox replays the original response instead of dialing again. A duplicate call means a double bill and a second call to the consumer. A retry while the first is still in flight returns `409 IDEMPOTENCY_IN_PROGRESS`. The same key with a different body returns `409 IDEMPOTENCY_KEY_REUSED`, and so does the same key sent by a different API key in your organization. Keys are scoped to one endpoint: the same key on another path is an independent request. > **Warning** > > **Use a fresh key for each call you intend to place.** The same key with the same body replays the original call's response. The same key with a different body, such as another `to_number`, returns `409 IDEMPOTENCY_KEY_REUSED` and places no call, so a changed destination is never silently dropped. Reuse a key only to retry the exact same request. ## Full example No SDK is required: it is plain HTTP and JSON. This script finds an AI voice agent and a caller ID, places a call, then polls for the outcome. Analysis is written after the call ends, so the script waits for it a bounded number of times and gives up if the call's `analysis_status` is `failed`. To be told instead of polling, use the `call.analysis.completed` event, which is the last event for an agency callback once [webhook delivery](/developers/webhook-delivery) is live. **Python** — `call_flow.py` ```python # pip install requests import os, time, uuid, requests BASE = "https://api.entrovox.com/v1" H = {"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", "Content-Type": "application/json"} # 1. Discover an AI voice agent and a caller-ID number agent = requests.get(f"{BASE}/voice-agents", headers=H, timeout=15).json()["data"][0] number = requests.get(f"{BASE}/phone-numbers", headers=H, timeout=15).json()["data"][0] # 2. Initiate the call, retry-safe via Idempotency-Key call = requests.post( f"{BASE}/calls", headers={**H, "Idempotency-Key": str(uuid.uuid4())}, json={"to_number": "+15555551234", "from_number": number["phone_number"], "agent_id": agent["id"]}, timeout=15, ).json()["data"] # 3. Poll until the call reaches a terminal state, with a bound TERMINAL = {"completed", "failed", "no_answer", "voicemail"} for _ in range(180): if call["status"] in TERMINAL: break time.sleep(5) call = requests.get(f"{BASE}/calls/{call['id']}", headers=H, timeout=15).json()["data"] # 4. The analysis is written after the call ends. A 404 CALL_ANALYSIS_NOT_FOUND means "not ready yet". analysis = None for _ in range(12): r = requests.get(f"{BASE}/calls/{call['id']}/analysis", headers=H, timeout=15) if r.status_code == 200: analysis = r.json()["data"] break if r.status_code != 404: r.raise_for_status() call = requests.get(f"{BASE}/calls/{call['id']}", headers=H, timeout=15).json()["data"] if call.get("analysis_status") == "failed": break # no analysis is coming: keep the call outcome time.sleep(5) print(call["status"], analysis) ``` **Node.js** — `call_flow.mjs` ```javascript // Node 18+, native fetch const BASE = "https://api.entrovox.com/v1"; const H = { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, "Content-Type": "application/json" }; const json = (r) => r.json(); // 1. Discover an AI voice agent and a caller-ID number const [{ data: agents }, { data: numbers }] = await Promise.all([ fetch(`${BASE}/voice-agents`, { headers: H }).then(json), fetch(`${BASE}/phone-numbers`, { headers: H }).then(json), ]); // 2. Initiate the call, retry-safe via Idempotency-Key let { data: call } = await fetch(`${BASE}/calls`, { method: "POST", headers: { ...H, "Idempotency-Key": crypto.randomUUID() }, body: JSON.stringify({ to_number: "+15555551234", from_number: numbers[0].phone_number, agent_id: agents[0].id, }), }).then(json); // 3. Poll until the call reaches a terminal state, with a bound const TERMINAL = new Set(["completed", "failed", "no_answer", "voicemail"]); for (let i = 0; i < 180 && !TERMINAL.has(call.status); i++) { await new Promise((r) => setTimeout(r, 5000)); ({ data: call } = await fetch(`${BASE}/calls/${call.id}`, { headers: H }).then(json)); } // 4. The analysis is written after the call ends. A 404 CALL_ANALYSIS_NOT_FOUND means "not ready yet". let analysis = null; for (let i = 0; i < 12; i++) { const res = await fetch(`${BASE}/calls/${call.id}/analysis`, { headers: H }); if (res.ok) { const body = await res.json(); analysis = body.data; break; } if (res.status !== 404) throw new Error(`analysis ${res.status}`); ({ data: call } = await fetch(`${BASE}/calls/${call.id}`, { headers: H }).then(json)); if (call.analysis_status === "failed") break; // no analysis is coming: keep the call outcome await new Promise((r) => setTimeout(r, 5000)); } console.log(call.status, analysis); ``` ## Errors Every error returns `{ "error": { "code", "message", "details" } }`. The `code` is stable: branch on it, not on the message text. ### Authentication and authorization | HTTP | Code | Meaning | |---|---|---| | 401 | `AUTHENTICATION_REQUIRED` | Missing or malformed `Authorization` header | | 401 | `TOKEN_INVALID` | API key not found or wrong format | | 401 | `API_KEY_EXPIRED` | Key is past its expiry | | 403 | `INSUFFICIENT_SCOPE` | Key lacks the tier, like a `read` key calling `POST /calls` | | 403 | `API_KEY_ENDPOINT_NOT_ALLOWED` | The endpoint is outside the API-key surface | ### Request and compliance | HTTP | Code | Meaning | |---|---|---| | 400 | `DNC_BLOCKED` or a compliance code | Destination is on DNC or outside its calling-hours window | | 404 | `*_NOT_FOUND` | An id in the request, like `agent_id` or `from_number`, is not in your organization | | 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this `Idempotency-Key` is still running: retry shortly | | 409 | `IDEMPOTENCY_KEY_REUSED` | This `Idempotency-Key` was already used for a different request: send a fresh key for a new call | | 422 | `VALIDATION_ERROR` | The body failed validation, and `details` lists the fields | | 429 | `RATE_LIMIT_EXCEEDED` | Too many requests: honor `Retry-After` | **Retry guidance.** `401`, `403`, `404` and `422` are permanent: fix the request, do not retry. `409 IDEMPOTENCY_IN_PROGRESS`, `429` and `5xx` are transient. Retry with backoff and reuse the same `Idempotency-Key`, so a call is never placed twice. The full code list is in the [error reference](/developers/errors). ## Next steps Pull the [transcript and recording](/developers/recordings-and-transcripts) for the call you placed, or learn the [rate limits](/developers/rate-limits) that apply. `POST /calls` shares the 100 per minute default bucket, and reads have their own 300 per minute bucket. --- # The status URL Every accepted lead returns one URL that holds its disposition and every call attempt. Poll it until webhooks ship. Every accepted lead, single or batch, live or test, first post or replay, includes a `status_url`. It is the hub for outcomes: the lead-level disposition, then each call attempt with links to its transcript, recording and analysis. Poll it for outcomes. [Webhooks](/developers/webhook-delivery) will replace polling once delivery ships. ## Read the lead **GET** `/v1/leads/{id}` needs only the `read` scope. `{id}` is the Entrovox lead id. Persist the `status_url` we return rather than building it yourself. **cURL** — `terminal` ```bash curl https://api.entrovox.com/v1/leads/7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40 \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` **Python** — `status.py` ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/leads/7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40", headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"}, timeout=15, ) r.raise_for_status() lead = r.json()["data"] print(lead["current_disposition"], len(lead["calls"])) ``` **Node.js** — `status.mjs` ```javascript const res = await fetch( "https://api.entrovox.com/v1/leads/7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40", { headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}` } }, ); const { data: lead } = await res.json(); console.log(lead.current_disposition, lead.calls.length); ``` **Response 200 OK** ```json { "data": { "id": "7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40", "external_id": "px-88421", "phone": "+14255551234", "transfer_phone": null, "current_disposition": "qualified_transfer", "attempt_count": 2, "next_attempt_at": null, "status_url": "https://api.entrovox.com/v1/leads/7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40", "calls_url": "https://api.entrovox.com/v1/leads/7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40/calls", "calls": [ { "id": "call_01J8K3…", "attempt_number": 2, "status": "completed", "disposition": "qualified_transfer", "call_outcome": "connected_transferred", "duration_seconds": 186, "started_at": "2026-09-10T18:02:11Z", "ended_at": "2026-09-10T18:05:17Z", "transcript_url": "https://api.entrovox.com/v1/calls/call_01J8K3…/transcript", "recording_url": "https://api.entrovox.com/v1/calls/call_01J8K3…/recording-url", "analysis_url": "https://api.entrovox.com/v1/calls/call_01J8K3…/analysis" } ] } } ``` ## Know which field answers which question - `current_disposition` is lead-level, across the whole sequence. `pending` means nothing has been decided yet. - `calls[]` is each attempt, newest last. A lead with more than 200 attempts lists its 200 most recent, and `GET /v1/leads/{id}/calls` pages through all of them. - Within a call, `status` is the telephony state of the attempt. Use `call_outcome` for the result: a successful warm transfer is `connected_transferred`. - `next_attempt_at` is the next sequence step. It is `null` once the sequence is finished, and also before the first call starts for a lead that is dialed immediately. - After a call exists, fetch its [transcript, recording and analysis](/developers/recordings-and-transcripts) from the URLs on that row. ## Read the outcome from your code Follow the URLs you stored. A `null` `next_attempt_at` alone does not mean the lead is done: `next_attempt_at` can also be `null` before the first call starts, for a lead that is dialed immediately. Tell finished from pending or in flight with `sequence_status`. `pending` and `callback_scheduled` are still in progress: a scheduled callback is dialed later even though `next_attempt_at` is `null`. `connected` is finished (a transfer, a qualified or not-qualified conversation, or a dead number), and so are `exhausted`, `declined`, `replied`, `dnc` and `opted_out`. More values may be added, so treat an unknown one as opaque and keep polling until your bound. A lead that is `paused` or has a `dial_blocker` will not dial either. A call with `call_outcome` `connected_transferred` is a finished handoff. **Python** — `outcome.py` ```python import os, time, requests H = {"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"} status_url = os.environ["LEAD_STATUS_URL"] # the status_url you stored when you posted FINISHED = {"connected", "exhausted", "declined", "replied", "dnc", "opted_out"} for _ in range(48): # bounded: about four hours at five minutes lead = requests.get(status_url, headers=H, timeout=15).json()["data"] transferred = any(c["call_outcome"] == "connected_transferred" for c in lead["calls"]) if lead["sequence_status"] in FINISHED or lead["paused"] or lead["dial_blocker"] or transferred: break time.sleep(300) for call in lead["calls"]: print(call["disposition"], call["transcript_url"], call["recording_url"]) ``` **Node.js** — `outcome.mjs` ```javascript const headers = { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}` }; const statusUrl = process.env.LEAD_STATUS_URL; // the status_url you stored when you posted const FINISHED = new Set(["connected", "exhausted", "declined", "replied", "dnc", "opted_out"]); let lead; for (let i = 0; i < 48; i++) { // bounded: about four hours at five minutes ({ data: lead } = await fetch(statusUrl, { headers }).then((r) => r.json())); const transferred = lead.calls.some((c) => c.call_outcome === "connected_transferred"); if (FINISHED.has(lead.sequence_status) || lead.paused || lead.dial_blocker || transferred) break; await new Promise((r) => setTimeout(r, 300000)); } for (const call of lead.calls) { console.log(call.disposition, call.transcript_url, call.recording_url); } ``` ## Look up by your own id If you did not keep our id, look the lead up by yours. A bound partner key reaches one campaign, so this returns at most one lead. An unbound agency key can get one lead per campaign. **cURL** — `terminal` ```bash curl "https://api.entrovox.com/v1/leads?external_id=px-88421" \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` **Python** — `lookup.py` ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/leads", params={"external_id": "px-88421"}, headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"}, timeout=15, ) print(r.json()["data"]) ``` **Node.js** — `lookup.mjs` ```javascript const res = await fetch("https://api.entrovox.com/v1/leads?external_id=px-88421", { headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}` }, }); console.log((await res.json()).data); ``` Test leads are not listed. Read one by its `status_url`. The list also takes `lead_source_id`, `disposition`, `search` (name or phone), and `cursor` and `limit` for paging. ## Dispositions The lead-level `current_disposition` takes many values, and the full list lives in the [API reference](/developers/reference/lead-object). A few you will see most: `pending`, `no_answer`, `voicemail_left`, `qualified_transfer`, `declined`, `callback_scheduled`, `dnc_added` and `wrong_number`. Treat an unknown value as opaque: new ones may be added. Prefer `call_outcome` from the call analysis for analytics. ## Next steps Fetch the [recording and transcript](/developers/recordings-and-transcripts) for a finished call, or [subscribe to webhooks](/developers/webhook-delivery) when delivery turns on. --- # Recordings and transcripts Fetch a finished call's transcript, a fresh signed recording URL and the post-call analysis. Each row in a lead's `calls[]` carries three URLs: `transcript_url`, `recording_url` and `analysis_url`. They are Entrovox API paths that need your key, not public links, so no expiring URL ever sits in your logs. Fetch them once the call has ended. All three need only the `read` scope. > **Warning** > > **Do not store a signed recording URL.** The URL from `GET /v1/calls/{id}/recording-url` expires in one hour. Persist the `recording_url` path from the call and fetch a fresh one when you need it. ## Fetch the transcript **GET** `/v1/calls/{id}/transcript` returns the turns of the call. **cURL** — `terminal` ```bash curl https://api.entrovox.com/v1/calls/call_01J8K3Q7M2/transcript \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` **Python** — `transcript.py` ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/calls/call_01J8K3Q7M2/transcript", headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"}, timeout=15, ) for turn in r.json()["data"]["transcript"]: print(f"{turn['speaker']}: {turn['text']}") ``` **Node.js** — `transcript.mjs` ```javascript const res = await fetch("https://api.entrovox.com/v1/calls/call_01J8K3Q7M2/transcript", { headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}` }, }); const { data } = await res.json(); for (const turn of data.transcript) console.log(`${turn.speaker}: ${turn.text}`); ``` **Response 200 OK** ```json { "data": { "call_id": "call_01J8K3Q7M2", "word_count": 412, "transcript": [ { "speaker": "agent", "text": "Hi, this is Robin, an AI assistant…", "started_at": "2026-09-10T18:02:14Z", "duration_ms": 4200 }, { "speaker": "customer", "text": "Yeah, I was looking at auto.", "started_at": "2026-09-10T18:02:19Z", "duration_ms": 1800 } ] } } ``` `speaker` is `agent` (the AI), `customer` (the lead) or `human_agent` (your licensed agent after the transfer, when we have that audio). ## Get a fresh recording URL **GET** `/v1/calls/{id}/recording-url` returns a signed URL that is good for one hour. It covers the AI voice agent's session, and the audio after a transfer when we stored it. **cURL** — `terminal` ```bash curl https://api.entrovox.com/v1/calls/call_01J8K3Q7M2/recording-url \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` **Python** — `recording.py` ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/calls/call_01J8K3Q7M2/recording-url", headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"}, timeout=15, ) print(r.json()["data"]["url"]) # use now, do not store ``` **Node.js** — `recording.mjs` ```javascript const res = await fetch("https://api.entrovox.com/v1/calls/call_01J8K3Q7M2/recording-url", { headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}` }, }); const { data } = await res.json(); console.log(data.url); // use now, do not store ``` **Response 200 OK** ```json { "data": { "url": "https://storage.example.com/signed/recording.mp3?token=…", "expires_in": 3600 } } ``` Three different answers can come back when there is no URL to return. Branch on `error.code`, not on the status alone: | Status | `error.code` | Meaning | What to do | |---|---|---|---| | 404 | `RECORDING_NOT_FOUND` | The call has no recording: it never connected, recording was off, or no recording is available. A failed upload can sometimes be recovered later, in which case it appears on the call object. | Do not poll for it. Check the call object later if you need it. | | 404 | `RECORDING_NOT_READY` | The call has a recording that is still being processed. | Poll again after the `Retry-After` header (seconds). Partner subscriptions can also wait for `call.recording.ready`, once webhook delivery is live. | | 503 | `RECORDING_UNAVAILABLE` | The recording exists but a link could not be made right now. | Retry after `Retry-After`. Keep retrying with backoff. | `RECORDING_NOT_READY` does not last forever. A recording that is still pending a few hours after the call ended is reported as `RECORDING_NOT_FOUND`. The full list is on the [errors page](/developers/errors). ## Get the analysis **GET** `/v1/calls/{id}/analysis` returns the post-call record. Prefer its `call_outcome` for analytics over the attempt-level `disposition`. **cURL** — `terminal` ```bash curl https://api.entrovox.com/v1/calls/call_01J8K3Q7M2/analysis \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` **Python** — `analysis.py` ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/calls/call_01J8K3Q7M2/analysis", headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"}, timeout=15, ) analysis = r.json()["data"] print(analysis["call_outcome"], analysis["call_summary"]) ``` **Node.js** — `analysis.mjs` ```javascript const res = await fetch("https://api.entrovox.com/v1/calls/call_01J8K3Q7M2/analysis", { headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}` }, }); const { data: analysis } = await res.json(); console.log(analysis.call_outcome, analysis.call_summary); ``` The record includes `call_outcome`, `outcome_confidence`, `outcome_reasoning`, `overall_sentiment`, `sentiment_score`, `dnc_detected`, `dnc_phrases`, `callback_detected`, `callback_datetime`, `wrong_number_detected`, `extracted_data`, `call_summary` and `follow_up_actions`, plus timestamps. ## When the media is ready Hangup and analysis can arrive before the audio is uploaded, so a call can have a `call_outcome` while its recording is still pending. If the recording fetch answers `RECORDING_NOT_READY`, ask again after `Retry-After`. `analysis_status` on the call is `pending`, `completed` or `failed`. ## Next steps Back to the lead's [status URL](/developers/status-url), or read how [webhooks](/developers/webhook-delivery) will tell you when media is ready. --- # Webhooks Signed events pushed to your URL instead of polling. Delivery is a preview: build against the contract, poll for now. > **Warning** > > **Webhook delivery is a preview.** Subscriptions and event delivery ship in a later release. Until then the `/webhooks` routes answer an API key with `403 API_KEY_ENDPOINT_NOT_ALLOWED`, a `webhook_url` on a call is stored but never called, and no events are sent. Poll each lead's [status URL](/developers/status-url) for outcomes. We will announce when delivery goes live. Once delivery is on, we `POST` a signed JSON event to your URL as a lead and its calls move through their lifecycle. This page is the short version. The [webhooks reference](/developers/webhooks) holds the full event catalog, every payload and the signature code. There are two audiences. Partner subscriptions (`POST /v1/webhooks`) can receive all ten events, with the richer payloads. Agency integrations that set `webhook_url` on `POST /calls` get the `call.*` events except `call.recording.ready`, with leaner payloads. **Subscribing as a partner.** The default `events` are `lead.accepted`, `call.completed`, `call.transferred`, `call.analysis.completed`, `call.recording.ready` and `callback.scheduled`. `call.started`, `call.answered`, `call.failed` and `webhook.test` are allowed but opt-in: list them in `events` to receive them. ## Events | Event | When | Audience | |---|---|---| | `lead.accepted` | We enrolled the lead | Partner only | | `call.started` | The outbound dial was placed | Both | | `call.answered` | The lead picked up and the AI conversation began | Both | | `call.completed` | An attempt ended. Provisional | Both | | `call.transferred` | A warm transfer to a licensed agent has a result | Both | | `call.failed` | An accepted call could not complete | Both | | `call.analysis.completed` | The post-call summary is ready. Media may still be pending | Both | | `call.recording.ready` | The recording and transcript are fetchable | Partner only | | `callback.scheduled` | The lead asked to be called back | Partner only | | `webhook.test` | You asked us to send a test | Partner only | **Which event is final.** `call.recording.ready` is final for partner subscriptions: write the disposition and artifacts to your system on it. Agency `webhook_url` callbacks never receive `call.recording.ready`, so `call.analysis.completed` is the last event for agency callbacks. **Leaner agency payloads.** Agency callbacks carry no `external_id` and no `media_pending`, and a transfer carries `transfer.to_agent` in place of `transfer.to_number` and `human_talk_seconds`. **Choosing events on a call.** `webhook_events` defaults to `call.started`, `call.completed`, `call.failed` and `call.transferred`. `call.analysis.completed` and `call.answered` are opt-in: add them to receive them. The `disposition` on `call.completed` is one of `qualified_transfer`, `transferred`, `declined`, `no_answer`, `voicemail`, `callback_scheduled` or `connected_other`. ## Verify a delivery We sign every delivery with the [Standard Webhooks](https://www.standardwebhooks.com/) scheme, so you can verify it with an off-the-shelf library instead of hand-rolling HMAC. Each request carries three headers. **`webhook-id`** (string) The event `id`, stable across retries. Dedupe on it: delivery is at least once. **`webhook-timestamp`** (string) Unix seconds when we sent it. Reject a delivery more than 300 seconds off your clock, which stops replays. The libraries enforce this. **`webhook-signature`** (string) One or more space-separated `v1,` entries. Several appear while a secret is being rotated, and any one match passes. The signing secret starts with `whsec_` and is shown once, when you enable webhooks. Keep it server-side. Verify against the raw request body, before any JSON parsing. **Python** — `verify.py` ```python # pip install standardwebhooks import os from standardwebhooks.webhooks import Webhook wh = Webhook(os.environ["ENTROVOX_WEBHOOK_SECRET"]) # whsec_… def handle(raw_body: bytes, headers: dict): # Raises WebhookVerificationError on a bad signature or a stale timestamp. event = wh.verify(raw_body, headers) return event ``` **Node.js** — `verify.mjs` ```javascript // npm install standardwebhooks import { Webhook } from "standardwebhooks"; const wh = new Webhook(process.env.ENTROVOX_WEBHOOK_SECRET); // whsec_… export function handle(rawBody, headers) { // Throws on a bad signature or a stale timestamp. return wh.verify(rawBody, headers); } ``` To verify by hand: the HMAC-SHA256 key is the base64-decoded part of your secret after `whsec_`. Sign `{webhook-id}.{webhook-timestamp}.{raw body bytes}` exactly, base64-encode the digest and compare it in constant time against each `v1,` entry. ## Delivery semantics - **At least once.** You may receive duplicates. Dedupe on `webhook-id`. - **No ordering guarantee.** Under retries `call.completed` can arrive before `call.answered`. Reconcile against the call's own state, not arrival order. - **Respond fast.** Return `2xx` within about five seconds and process asynchronously. A non-`2xx` or a timeout triggers retries with exponential backoff, about five attempts over a few hours. ## Events and payloads Every delivery is a `POST` with this body: ```json { "id": "evt_01J8…", "type": "call.completed", "created_at": "2026-07-04T19:30:00Z", "api_version": "2026-09-10", "data": {} } ``` `id` is unique per event, so dedupe on it. `api_version` is date-versioned so payloads can evolve safely. What `data` holds, per event, for a partner subscription: | `type` | `data` | Final? | |---|---|---| | `lead.accepted` | `lead`, `external_id` | n/a | | `webhook.test` | `ok: true` | Ignore | | `call.started`, `call.answered`, `call.failed` | `call`, `external_id` | No | | `call.completed` | `call`, `external_id`, `analysis_pending`, `media_pending` | No | | `call.transferred` | `call`, `external_id`, `transfer` with `status`, `to_number`, `initiated_at`, `connected_at`, `human_talk_seconds` | Transfer result | | `call.analysis.completed` | `call_id`, `external_id`, `analysis`, `links`, `media_pending` | No, if `media_pending` | | `call.recording.ready` | `call_id`, `external_id`, `links` with `recording` and `transcript`, `status` of `uploaded` or `failed` | Yes | | `callback.scheduled` | `lead_id`, `call_id`, `external_id`, `callback_datetime`, `timezone` | n/a | `transfer.status` is `connected`, `no_answer`, `voicemail` or `failed`. For agency callbacks, drop `external_id` and `media_pending` and read `transfer.to_agent`. Agency `call.completed`, the outcome promptly at hangup: ```json { "type": "call.completed", "data": { "call": { "id": "call_01J8…", "status": "completed", "direction": "outbound", "to_number": "+15555551234", "from_number": "+15555550000", "agent_id": "agent_01J…", "disposition": "declined", "duration_seconds": 73, "talk_time_seconds": 58, "answered_at": "2026-07-04T19:29:10Z", "ended_at": "2026-07-04T19:30:23Z", "metadata": { "crm_id": "lead-42" } }, "analysis_pending": true } } ``` Agency `call.analysis.completed`, the AI result plus links to fetch the artifacts: ```json { "type": "call.analysis.completed", "data": { "call_id": "call_01J8…", "analysis": { "summary": "Shopping auto+home bundle; renewal in 3 weeks; currently with Geico. Open to a quote.", "outcome": "qualified_transfer", "qualification_score": 0.82, "qualification_data": { "line_of_business": "auto", "current_carrier": "Geico", "renewal_date": "2026-07-25" } }, "links": { "recording": "https://api.entrovox.com/v1/calls/call_01J8…/recording-url", "transcript": "https://api.entrovox.com/v1/calls/call_01J8…/transcript" } } } ``` Recordings and transcripts arrive as links to API paths, not embedded and not as expiring URLs. Fetch them with your key from [Recordings and transcripts](/developers/recordings-and-transcripts). The retry policy in full is in [Retries and replay](/developers/webhooks#retries-and-replay). ## Next steps Until delivery is live, poll the [status URL](/developers/status-url). Read [Safe retries and idempotency](/developers/retries-and-idempotency) for the same dedupe habits on the way in. --- # Safe retries and idempotency Which errors to retry, which to resell, and how external_id and Idempotency-Key keep a retry from starting a second sequence. Two things make a retry safe: your `external_id` and an `Idempotency-Key`. Send the same `external_id` and the same `Idempotency-Key` on a retry and we will not start a second sequence. > **Warning** > > **A definitive rejection means we will never call this lead.** Resell it and do not retry. Only the transient errors below are safe to retry. ## Errors you can branch on Every error is an envelope with a stable `code`. Branch on `code`, not on the sentence. ```json { "error": { "code": "DNC_BLOCKED", "message": "Phone is on the DNC list, so we did not create a lead. Remove it from your list or pause it; do not retry.", "param": "phone", "doc_url": "…", "request_id": "…" } } ``` `param` is the JSON field that failed, when there is one. When present, `doc_url` is a link to that code's entry in the [error reference](/developers/errors). The link goes through the older `api.entrovox.com/developer/docs` address, which redirects to the entry in a browser. The last step needs JavaScript, so a script that follows redirects ends on the reference home instead. | Class | HTTP | What it means | Retry? | |---|---|---|---| | Never accepted | `400` or `422` | DNC, a bad E.164 phone, a paused campaign, invalid consent, a missing `external_id` | No. Resell or fix. | | Conflict | `409` | The same `external_id` in this campaign with a different phone or `is_test`, or this phone is already enrolled under another id | No. Use the existing `status_url` in `details` when we include one, which we do only for a lead your key can read. | | Not found | `404` | `LEAD_SOURCE_NOT_FOUND` (the campaign is not in your organization) or `LEAD_NOT_FOUND` | No. Check the id. | | Idempotency in flight | `409` | The same `Idempotency-Key` is still writing | Yes, with the same key. | | Rate limit | `429` | You are over a limit | Yes, after `Retry-After`, with the same key. | | Temporary | `503` | Our DNC check could not run, or other posts for the same phone were being written at that moment | Yes, after `Retry-After`. No row was created. | | Server error | `500` | Something failed mid-post | Yes, with the same `external_id`. We normally remove a lead that never enrolled. If one was left, the retry enrolls it or refuses it. | | Auth | `401` or `403` | A bad key, or a partner key calling `POST /calls` | No. | ## Retry a post Generate one `Idempotency-Key` per logical request and reuse it on every retry, including after a timeout or a dropped connection. The server may already have accepted the lead before the connection failed, and the same key makes the retry safe. In cURL, `--retry-all-errors` needs curl 7.71 or newer. Do not add `--fail`: without it an HTTP 4xx or 5xx is not a curl error, so only transport failures are resent and a `409` or `422` is never blindly retried. **cURL** — `terminal` ```bash # Generate the key once, then reuse it on every retry of this request. # Same key, same body: a retry returns the original response. IDEMPOTENCY_KEY=$(uuidgen) curl --retry 5 --retry-all-errors --retry-max-time 60 --max-time 15 -X POST https://api.entrovox.com/v1/leads \ -H "Authorization: ApiKey $ENTROVOX_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $IDEMPOTENCY_KEY" \ -d '{ "first_name": "Jordan", "last_name": "Lee", "phone": "+14255551234", "external_id": "px-88421" }' ``` **Python** — `retry.py` ```python import os, time, uuid, requests key = str(uuid.uuid4()) # one key per logical request, reused on every retry body = {"first_name": "Jordan", "last_name": "Lee", "phone": "+14255551234", "external_id": "px-88421"} r = None for attempt in range(5): try: r = requests.post( "https://api.entrovox.com/v1/leads", headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", "Idempotency-Key": key}, json=body, timeout=15, ) except (requests.exceptions.ConnectionError, requests.exceptions.Timeout): time.sleep(2**attempt) # the lead may already be accepted; the same key makes the retry safe continue code = None if r.status_code == 409: # only a 409 needs its body read; a 5xx may not be JSON try: code = r.json()["error"]["code"] except ValueError: pass if r.status_code in (429, 503) or r.status_code >= 500 or code == "IDEMPOTENCY_IN_PROGRESS": time.sleep(int(r.headers.get("Retry-After", 2**attempt))) continue break # success, or a final answer you must not retry if r is None: raise SystemExit("no response after 5 attempts") print(r.status_code, r.headers.get("X-Idempotency-Replayed")) ``` **Node.js** — `retry.mjs` ```javascript import { randomUUID } from "node:crypto"; const key = randomUUID(); // one key per logical request, reused on every retry const body = JSON.stringify({ first_name: "Jordan", last_name: "Lee", phone: "+14255551234", external_id: "px-88421" }); let res; for (let attempt = 0; attempt < 5; attempt++) { try { const signal = AbortSignal.timeout(15000); res = await fetch("https://api.entrovox.com/v1/leads", { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, "Idempotency-Key": key, "Content-Type": "application/json", }, body, signal, }); } catch (err) { // Network error or timeout. The lead may already be accepted; the same key makes the retry safe. res = undefined; await new Promise((r) => setTimeout(r, 2 ** attempt * 1000)); continue; } // Only a 409 needs its body read; a 5xx may not be JSON. let code = null; if (res.status === 409) code = (await res.clone().json().catch(() => ({}))).error?.code; if (res.status === 429 || res.status === 503 || res.status >= 500 || code === "IDEMPOTENCY_IN_PROGRESS") { const wait = Number(res.headers.get("Retry-After") ?? 2 ** attempt); await new Promise((r) => setTimeout(r, wait * 1000)); continue; } break; // success, or a final answer you must not retry } if (!res) throw new Error("no response after 5 attempts"); console.log(res.status, res.headers.get("X-Idempotency-Replayed")); ``` ## What a replay returns This section covers lead posts. `POST /calls` follows the same rule: the same key and body replays the original call, and a different body or another API key answers `409 IDEMPOTENCY_KEY_REUSED`, as described in [Place a call](/developers/place-a-call#idempotency-recommended). What you get back depends on which identifier matched. - **Same `Idempotency-Key` and body.** The original response, unchanged. A create stays `201` with `data.replayed=false`, plus the header `X-Idempotency-Replayed: true`. - **Same `external_id` only**, with a new key or none. The original lead as `200` with `data.replayed=true`, the header `X-Duplicate: external_id` and the same `status_url`. An `Idempotency-Key` belongs to one path: the same key on `POST /leads` and on `POST /leads/batch` is two separate requests. The same key on this path with a different body, or a key already used by another API key, answers `409 IDEMPOTENCY_KEY_REUSED`. Send a fresh UUID per request. The key is a transport-retry guard. `external_id` is the durable identity. ## Two posts for one phone at the same moment If two of your servers post the same phone together, one gets `201`. The other gets `409 LEAD_PHONE_CONFLICT` pointing at the lead that won, or a `503` to retry if it could not be decided in time. If your agency allows duplicate phones, both are accepted. ## Count a lead once Count a lead once per `external_id`, not once per `201`. A retry of a lead that never finished enrolling can still be refused, as `400 DNC_BLOCKED` or `409 LEAD_PHONE_CONFLICT`, if its phone went DNC or into another live sequence in the meantime. No row is kept in that case. ## Next steps See [Rate limits and volume](/developers/rate-limits) for the `Retry-After` you will honor, and the [go-live checklist](/developers/go-live-checklist) before you turn volume on. --- # Rate limits and volume The per-key limits on a standard partner key, the headers that report them, and how to ask for more. Partner traffic is a lead post, not a chatty per-attempt API. This is the same `/v1` we run for agencies, and posting a lead returns after enrollment, typically well under a second. Dialing is asynchronous. ## Limits on a standard partner key | Bucket | Limit | |---|---| | `POST /leads` | 120 per minute | | `POST /leads/batch` | 20 per minute, 500 leads each | | `POST /leads/ping` | 300 per minute | | `GET` status, calls and artifacts | 300 per minute | | `POST /leads/{id}/pause` and `/resume` | 60 per minute | | Anything else a key may reach | 100 per minute | Ping is optional. Direct post is the default path, and ping is for publishers who already have ping and post. Limits are counted per API key, and each bucket is independent: posting does not use up your read quota. They are enforced per API instance, in memory, so these numbers are the guaranteed floor. The MediaAlpha native route has no bucket of its own. It falls in the shared default bucket of 100 requests per minute, separate from the `POST /leads` bucket: see [MediaAlpha native post](/developers/mediaalpha-native-post#rate-limit). ## Read the headers Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (unix seconds) and `X-Request-ID`. Quote the request id when you contact us. **cURL** — `terminal` ```bash curl -i "https://api.entrovox.com/v1/leads?external_id=px-88421" \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` **Python** — `limits.py` ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/leads", params={"external_id": "px-88421"}, headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"}, timeout=15, ) print(r.headers["X-RateLimit-Remaining"], "left until", r.headers["X-RateLimit-Reset"]) ``` **Node.js** — `limits.mjs` ```javascript const res = await fetch("https://api.entrovox.com/v1/leads?external_id=px-88421", { headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}` }, }); console.log(res.headers.get("X-RateLimit-Remaining"), "left until", res.headers.get("X-RateLimit-Reset")); ``` Over a limit you get `429 RATE_LIMIT_EXCEEDED` with `Retry-After`. Wait that long and retry with the same `Idempotency-Key`. See [Safe retries and idempotency](/developers/retries-and-idempotency). ## Concurrency and size Your campaign is provisioned with its own branded caller IDs and dial concurrency. We size this with you, for example 500 leads per day or 50 thousand attempts per month. ## Need more We raise a key's ceiling per program, with no API version change and no rewrite of your integration. Ask the Entrovox contact who provisioned you. ## Next steps Plan your first volume send with the [go-live checklist](/developers/go-live-checklist). --- # Compliance: what we enforce The checks Entrovox runs before every dial, and the consent basis you certify before a campaign goes live. Entrovox enforces some rules for you at dial time, and you certify the rest. Know which is which before you post volume. ## What we enforce We run these checks for every lead: - **AI disclosure.** Each agency sets AI disclosure per campaign, and it is on by default. When it is on, the AI voice agent's first words identify it as automated. If a call screener answers, the disclosure plays once the person takes the call. Some agency-specific scripts open with a name check before the AI introduces itself. Whatever the setting or script, the AI never denies being automated when asked. - **TCPA calling hours** in the lead's timezone. A lead outside its window is queued, not rejected. - **Your agency's DNC list**, and leads already marked DNC, before every dial. We do not screen the national DNC registry yet: the consent you certify below is what covers a number on it. - **Recording disclosure** in two-party consent states. - **Organization isolation.** A bound key cannot see another campaign. If a number is on DNC at ingest, we reject it so you can resell it. If it lands on DNC mid-sequence, we stop and the lead's disposition becomes `dnc_added`. ## What you certify > **Warning** > > **You certify consent. Posting a lead is not a substitute.** Before we activate the campaign, you (or the agency we operate for you) attest a lawful TCPA consent basis for every list you will post. That certification is not collected on this API. If you send a `trustedform_cert_url` that is not a TrustedForm certificate URL, we reject the lead with `400 CONSENT_INVALID` and create no row. Today that is a format check only. Certificates are not yet verified with ActiveProspect, and no campaign-level consent-evidence requirement is enforced yet, so the validity of what you send stays your responsibility. `jornaya_leadid` is stored and not validated. On the MediaAlpha native route, an explicit "no" in `tcpa_call_consent` is also `400 CONSENT_INVALID`. See [MediaAlpha native post](/developers/mediaalpha-native-post#consent-optional). ## How a rejection reaches you A lead we will never call comes back as a `4xx` with no row created: `DNC_BLOCKED`, `CONSENT_INVALID`, `VALIDATION_ERROR`, `SOURCE_PAUSED` or `SOURCE_INACTIVE`. Resell the lead and do not retry. In a batch, the same codes come back per row. See [Safe retries and idempotency](/developers/retries-and-idempotency). ## Next steps Run the [go-live checklist](/developers/go-live-checklist). --- # Go-live checklist What to confirm before the first live post, before volume, and once leads are flowing. Work through these before Entrovox activates your campaign and you send live leads. Each item links to the page that explains it. > **Warning** > > **A live post to an active campaign dials.** Until activation, test with `is_test: true` or with phones you control, and tell your Entrovox contact before you send a live connectivity test. ## Before the first live post - Run the [quickstart](/developers/quickstart): post an `is_test` lead and read it back from its `status_url`. - Confirm your key is bound to the right campaign. You can omit `lead_source_id`; naming another campaign is `403 LEAD_SOURCE_NOT_ALLOWED`. See [Authentication and keys](/developers/authentication). - Send your own `external_id` on every lead, unique per campaign. - Send an `Idempotency-Key` with every post and reuse it on retries. See [Safe retries and idempotency](/developers/retries-and-idempotency). - Keep the key on a server. Never ship it to a browser or a mobile app. - Make sure the consent certification for each list is in place with your Entrovox contact. It is not collected on this API. See [Compliance: what we enforce](/developers/compliance). ## Before you turn volume on - Branch on the error `code`. Resell every definitive rejection, and retry only the transient codes. - For batches, read every item's `status` and persist every `status_url`. HTTP `200` does not mean every row landed. See [Batch post](/developers/batch-post). - Stay inside your [rate limits](/developers/rate-limits), honor `Retry-After`, and ask for a higher ceiling before a big send. - Count a lead once per `external_id`, not once per `201`. - If your floor can sell a lead elsewhere, wire up [pause](/developers/pause-a-lead). ## Once leads are flowing - Read outcomes from the [status URL](/developers/status-url) on a schedule. [Webhooks](/developers/webhook-delivery) are a preview and nothing is delivered yet. - Fetch a fresh signed recording URL when you need audio. Never store the signed URL. See [Recordings and transcripts](/developers/recordings-and-transcripts). - Quote the `X-Request-ID` when you contact us about a request. ## Next steps Questions while you integrate: reply to the thread that included your key, or email the Entrovox contact who provisioned you. --- # API reference Post leads, then read back what the AI voice agent did with them. Each page below is generated from the spec the API publishes, so it matches what the API accepts and returns. Base URL: `https://api.entrovox.com/v1` ## Your first request cURL: ```bash curl -X GET "https://api.entrovox.com/v1/leads?limit=25" \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` Python: ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/leads", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", }, params={ "limit": 25, }, ) print(r.status_code, r.json()) ``` Node.js: ```javascript const res = await fetch("https://api.entrovox.com/v1/leads?limit=25", { method: "GET", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, }, }); console.log(res.status, await res.json()); ``` ## An error body ```json { "error": { "code": "DNC_BLOCKED", "message": "The phone is on the Do Not Call list. No lead was created.", "param": "phone", "doc_url": "https://api.entrovox.com/developer/docs#dnc-blocked", "request_id": "REQUEST_ID" } } ``` ## Authentication Send your key in the `Authorization` header, with the scheme `ApiKey`. Keep it in an environment variable such as `ENTROVOX_KEY`, never in client-side code. A key can call only the endpoints in this reference. Any other endpoint returns `API_KEY_ENDPOINT_NOT_ALLOWED`, and an expired key returns `API_KEY_EXPIRED`. ## Idempotency Send an `Idempotency-Key` header with a UUID you generate for each new request. Resending the same key and body returns the original response, so a network retry never creates a second record. These endpoints take it: - [Create a lead](/developers/reference/create-a-lead): `POST /v1/leads` - [Create leads in a batch](/developers/reference/create-leads-in-a-batch): `POST /v1/leads/batch` - [Create a call](/developers/reference/create-a-call): `POST /v1/calls` For leads, `external_id` is the durable identity; the header covers retries of the same request. ## Pagination Lists of leads and calls take `limit` and a `cursor`. Pass `meta.next_cursor` from one page as the next request's cursor, and stop when `meta.has_more` is false. Lists of phone numbers and AI voice agents take `page` and a page size instead. ## Errors A failed request returns an `error` object. Branch on `code`, not on the message. `param` names the field that failed when there is one, and `request_id` is what to quote when you contact us. Each endpoint page lists the codes it can return, with what to do next: - Retrying will fail the same way. Fix the request, or contact us. - The lead or request already exists. Fetch it instead of sending it again. - Retry after the time in details.next_attempt_local when present. Otherwise retry when the blocking condition ends, as the meaning says. - Safe to retry after Retry-After when present, otherwise back off. On a POST, resend the same Idempotency-Key and body. ## Resources ### Leads - [The lead object](/developers/reference/lead-object) - [Create a lead](/developers/reference/create-a-lead): `POST /v1/leads` - [Create leads in a batch](/developers/reference/create-leads-in-a-batch): `POST /v1/leads/batch` - [Ping a lead](/developers/reference/ping-a-lead): `POST /v1/leads/ping` - [Retrieve a lead](/developers/reference/retrieve-a-lead): `GET /v1/leads/{lead_id}` - [List leads](/developers/reference/list-leads): `GET /v1/leads` - [List calls for a lead](/developers/reference/list-calls-for-a-lead): `GET /v1/leads/{lead_id}/calls` - [Pause a lead](/developers/reference/pause-a-lead): `POST /v1/leads/{lead_id}/pause` - [Resume a lead](/developers/reference/resume-a-lead): `POST /v1/leads/{lead_id}/resume` ### Calls - [The call object](/developers/reference/call-object) - [Create a call](/developers/reference/create-a-call): `POST /v1/calls` - [Retrieve a call](/developers/reference/retrieve-a-call): `GET /v1/calls/{call_id}` - [List calls](/developers/reference/list-calls): `GET /v1/calls` - [Retrieve call statistics](/developers/reference/retrieve-call-statistics): `GET /v1/calls/stats` - [Retrieve a call analysis](/developers/reference/retrieve-a-call-analysis): `GET /v1/calls/{call_id}/analysis` - [Retrieve a call transcript](/developers/reference/retrieve-a-call-transcript): `GET /v1/calls/{call_id}/transcript` - [Retrieve a call recording URL](/developers/reference/retrieve-a-call-recording-url): `GET /v1/calls/{call_id}/recording-url` ### Phone numbers - [List phone numbers](/developers/reference/list-phone-numbers): `GET /v1/phone-numbers` - [Retrieve a phone number](/developers/reference/retrieve-a-phone-number): `GET /v1/phone-numbers/{phone_number_id}` ### AI voice agents - [List AI voice agents](/developers/reference/list-ai-voice-agents): `GET /v1/voice-agents` - [Retrieve an AI voice agent](/developers/reference/retrieve-an-ai-voice-agent): `GET /v1/voice-agents/{agent_id}` --- # The lead object Fields of the lead object, as returned by the Leads endpoints. ## Attributes - `attempt_count` (integer, May be absent, default 0) - `calls` (array of object or null, May be absent): Every attempt, newest last. On GET /leads/{id} and POST responses. - `analysis_url` (string, Always present) - `attempt_number` (integer or null, May be absent) - `call_outcome` (string or null, May be absent) - `disposition` (string or null, May be absent) - `duration_seconds` (integer or null, May be absent) - `ended_at` (string (date-time) or null, May be absent) - `id` (string, Always present) - `recording_url` (string, Always present) - `started_at` (string (date-time) or null, May be absent) - `status` (string or null, May be absent) - `transcript_url` (string, Always present) - `calls_url` (string, Always present) - `created_at` (string (date-time), Always present) - `current_disposition` (string, Always present) - `dedup_status` (string or null, May be absent) - `dial_blocker` (string or null, May be absent) - `disposition_at` (string (date-time) or null, May be absent) - `email` (string or null, May be absent) - `external_id` (string or null, May be absent) - `first_name` (string or null, May be absent) - `id` (string, Always present) - `is_dnc` (boolean, May be absent, default false) - `is_test` (boolean, May be absent, default false) - `jornaya_leadid` (string or null, May be absent) - `last_attempted_at` (string (date-time) or null, May be absent) - `last_name` (string or null, May be absent) - `metadata` (object, May be absent): Free-form key and value pairs. - `national_dnc_status` (string or null, May be absent) - `next_attempt_at` (string (date-time) or null, May be absent) - `organization_id` (string, Always present) - `pause_is_queued` (boolean, May be absent, default false) - `paused` (boolean, May be absent, default false) - `paused_at` (string (date-time) or null, May be absent) - `paused_reason` (string or null, May be absent) - `phone` (string, Always present) - `phone_alt` (string or null, May be absent) - `preferred_language` (string or null, May be absent) - `replayed` (boolean or null, May be absent): On POST responses: true on a 200 replay. - `sequence_status` (string or null, May be absent) - `sequence_step` (integer, May be absent, default 0) - `state` (string or null, May be absent) - `status_url` (string, Always present) - `timezone` (string or null, May be absent) - `transfer_phone` (string or null, May be absent): Always null for now. - `trustedform_cert_url` (string or null, May be absent) - `updated_at` (string (date-time), Always present) - `zip_code` (string or null, May be absent) ## Returned by - **POST** [Create a lead](/developers/reference/create-a-lead) `/v1/leads` - **GET** [Retrieve a lead](/developers/reference/retrieve-a-lead) `/v1/leads/{lead_id}` - **GET** [List leads](/developers/reference/list-leads) `/v1/leads` ## Example ```json { "attempt_count": 0, "calls": null, "calls_url": "https://api.entrovox.com/v1/leads/LEAD_ID/calls", "created_at": "2026-01-15T17:30:00Z", "current_disposition": "string", "dedup_status": null, "dial_blocker": null, "disposition_at": null, "email": "jordan.lee@example.com", "external_id": "crm-88421", "first_name": "Jordan", "id": "LEAD_ID", "is_dnc": false, "is_test": false, "jornaya_leadid": null, "last_attempted_at": null, "last_name": "Lee", "metadata": {}, "national_dnc_status": null, "next_attempt_at": null, "organization_id": "ORGANIZATION_ID", "pause_is_queued": false, "paused": false, "paused_at": null, "paused_reason": null, "phone": "+15555550100", "phone_alt": "+15555550101", "preferred_language": null, "replayed": null, "sequence_status": null, "sequence_step": 0, "state": "WA", "status_url": "https://api.entrovox.com/v1/leads/LEAD_ID", "timezone": "America/Los_Angeles", "transfer_phone": null, "trustedform_cert_url": null, "updated_at": "2026-01-15T17:30:00Z", "zip_code": "98101" } ``` --- # The call object Fields of the call object, as returned by the Calls endpoints. ## Attributes - `agent_id` (string or null, May be absent) - `agent_overrides` (object or null, May be absent): Free-form key and value pairs. - `ai_disclosure_delivered` (boolean or null, May be absent, default false) - `ai_latency_p50_ms` (integer or null, May be absent) - `ai_latency_p95_ms` (integer or null, May be absent) - `ai_talk_seconds` (integer or null, May be absent) - `analysis_status` (string or null, May be absent) - `answered_at` (string (date-time) or null, May be absent) - `attempt_number` (integer, May be absent, default 1) - `call_outcome` (string or null, May be absent) - `call_summary` (string or null, May be absent) - `created_at` (string (date-time) or null, May be absent) - `direction` (string, Always present) - `disconnect_reason` (string or null, May be absent) - `disposition` (string or null, May be absent) - `duration_seconds` (integer or null, May be absent) - `ended_at` (string (date-time) or null, May be absent) - `forward_answered` (boolean or null, May be absent) - `forwarded_to_number` (string or null, May be absent) - `from_number` (string, Always present) - `had_dead_air` (boolean or null, May be absent, default false) - `human_recording_suppressed` (boolean, May be absent, default false) - `human_talk_seconds` (integer or null, May be absent) - `id` (string, Always present) - `initiated_at` (string (date-time) or null, May be absent) - `is_short_drop` (boolean or null, May be absent, default false) - `is_test` (boolean, May be absent, default false) - `language` (string, May be absent, default en) - `lead_id` (string or null, May be absent) - `lead_name` (string or null, May be absent) - `lead_source_id` (string or null, May be absent) - `lead_source_lead_id` (string or null, May be absent) - `lead_source_name` (string or null, May be absent) - `lead_source_type` (string or null, May be absent) - `metadata` (object or null, May be absent): Free-form key and value pairs. - `organization_id` (string, Always present) - `origin` (object or null, May be absent): Free-form key and value pairs. - `qualification_data` (object or null, May be absent): Free-form key and value pairs. - `qualification_score` (number or null, May be absent) - `recording_disclosed` (boolean or null, May be absent, default false) - `recording_duration_seconds` (integer or null, May be absent) - `retry_config` (object or null, May be absent): Free-form key and value pairs. - `routing_mode` (string or null, May be absent) - `scheduled_at` (string (date-time) or null, May be absent) - `scheduling` (object or null, May be absent): Free-form key and value pairs. - `screener_detected` (boolean or null, May be absent, default false) - `screener_result` (string or null, May be absent) - `sequence_step` (integer or null, May be absent) - `started_at` (string (date-time) or null, May be absent) - `status` (string, Always present) - `talk_time_seconds` (integer or null, May be absent) - `to_number` (string, Always present) - `transcript` (string or null, May be absent) - `transcript_json` (array, object or null, May be absent) - `transfer_context` (object or null, May be absent): Free-form key and value pairs. - `updated_at` (string (date-time) or null, May be absent) - `variables` (object or null, May be absent): Free-form key and value pairs. - `voicemail_clip_used` (boolean or null, May be absent) - `wait_hold_seconds` (integer or null, May be absent) - `wait_ring_seconds` (integer or null, May be absent) - `wait_seconds` (integer or null, May be absent) - `webhook_events` (array of string or null, May be absent) - `webhook_url` (string or null, May be absent) - `why_detail` (string or null, May be absent) - `why_short` (string or null, May be absent) ## Returned by - **GET** [Retrieve a call](/developers/reference/retrieve-a-call) `/v1/calls/{call_id}` ## Example ```json { "agent_id": null, "agent_overrides": {}, "ai_disclosure_delivered": false, "ai_latency_p50_ms": null, "ai_latency_p95_ms": null, "ai_talk_seconds": null, "analysis_status": null, "answered_at": null, "attempt_number": 1, "call_outcome": null, "call_summary": null, "created_at": null, "direction": "string", "disconnect_reason": null, "disposition": null, "duration_seconds": null, "ended_at": null, "forward_answered": null, "forwarded_to_number": null, "from_number": "+15555550142", "had_dead_air": false, "human_recording_suppressed": false, "human_talk_seconds": null, "id": "CALL_ID", "initiated_at": null, "is_short_drop": false, "is_test": false, "language": "en", "lead_id": null, "lead_name": null, "lead_source_id": null, "lead_source_lead_id": null, "lead_source_name": null, "lead_source_type": null, "metadata": {}, "organization_id": "ORGANIZATION_ID", "origin": {}, "qualification_data": {}, "qualification_score": null, "recording_disclosed": false, "recording_duration_seconds": null, "retry_config": {}, "routing_mode": null, "scheduled_at": null, "scheduling": {}, "screener_detected": false, "screener_result": null, "sequence_step": null, "started_at": null, "status": "active", "talk_time_seconds": null, "to_number": "+15555550100", "transcript": null, "transcript_json": null, "transfer_context": {}, "updated_at": null, "variables": {}, "voicemail_clip_used": null, "wait_hold_seconds": null, "wait_ring_seconds": null, "wait_seconds": null, "webhook_events": null, "webhook_url": null, "why_detail": null, "why_short": null } ``` --- # Create a lead `POST /v1/leads` Post one lead into a campaign. API keys: `external_id` is required; `201` enrolls the lead, a retry with the same `external_id` (same phone, campaign and `is_test`) replays it with `200` and `X-Duplicate: external_id`. DNC, invalid phone, a paused or inactive campaign and invalid consent are `4xx` with no row. Send an `Idempotency-Key` (UUID) to make transport retries safe. ## Headers - `Authorization` (string, required): `ApiKey $ENTROVOX_KEY`. Keys are issued per organization. - `Idempotency-Key` (string or null, optional): A UUID you generate for each new request. Resending the same key and body returns the original response. ## Body - `email` (string or null, max 320, optional) - `external_id` (string or null, 1–128, required): Your lead id. Unique per organization; a retry with it replays the lead. - `first_name` (string, 1–200, required) - `is_test` (boolean, optional, default false): true stores a test lead (a safe hello-world): it is never enrolled, dialed or texted, never blocks a live phone, and is not listed. Read it back by id. - `jornaya_leadid` (string or null, max 256, optional) - `last_name` (string, 1–200, required) - `lead_generated_at` (string or null, optional) - `lead_source_id` (string or null, optional) - `metadata` (object or null, optional): Free-form key and value pairs. - `owned_line_of_business` (string or null, max 64, optional) - `phone` (string, 1–32, required) - `phone_alt` (string or null, optional) - `preferred_language` (string or null, optional, one of en, es) - `state` (string or null, max 64, optional) - `target_line_of_business` (string or null, max 64, optional) - `timezone` (string or null, max 64, optional) - `transfer_phone` (string or null, optional): Not supported yet: any value is rejected with 400 VALIDATION_ERROR (param transfer_phone). Qualified leads transfer to the campaign number. - `trustedform_cert_url` (string or null, max 512, optional) - `zip_code` (string or null, max 10, optional) ## Returns **200 OK**: Replay: same external_id, phone, campaign and is_test (data.replayed true, X-Duplicate: external_id). A lead that never enrolled, or that a duplicate check parked, is refused instead (400 DNC_BLOCKED / 409 LEAD_PHONE_CONFLICT). - `attempt_count` (integer, May be absent, default 0) - `calls` (array of object or null, May be absent): Every attempt, newest last. On GET /leads/{id} and POST responses. - `analysis_url` (string, Always present) - `attempt_number` (integer or null, May be absent) - `call_outcome` (string or null, May be absent) - `disposition` (string or null, May be absent) - `duration_seconds` (integer or null, May be absent) - `ended_at` (string (date-time) or null, May be absent) - `id` (string, Always present) - `recording_url` (string, Always present) - `started_at` (string (date-time) or null, May be absent) - `status` (string or null, May be absent) - `transcript_url` (string, Always present) - `calls_url` (string, Always present) - `created_at` (string (date-time), Always present) - `current_disposition` (string, Always present) - `dedup_status` (string or null, May be absent) - `dial_blocker` (string or null, May be absent) - `disposition_at` (string (date-time) or null, May be absent) - `email` (string or null, May be absent) - `external_id` (string or null, May be absent) - `first_name` (string or null, May be absent) - `id` (string, Always present) - `is_dnc` (boolean, May be absent, default false) - `is_test` (boolean, May be absent, default false) - `jornaya_leadid` (string or null, May be absent) - `last_attempted_at` (string (date-time) or null, May be absent) - `last_name` (string or null, May be absent) - `metadata` (object, May be absent): Free-form key and value pairs. - `national_dnc_status` (string or null, May be absent) - `next_attempt_at` (string (date-time) or null, May be absent) - `organization_id` (string, Always present) - `pause_is_queued` (boolean, May be absent, default false) - `paused` (boolean, May be absent, default false) - `paused_at` (string (date-time) or null, May be absent) - `paused_reason` (string or null, May be absent) - `phone` (string, Always present) - `phone_alt` (string or null, May be absent) - `preferred_language` (string or null, May be absent) - `replayed` (boolean or null, May be absent): On POST responses: true on a 200 replay. - `sequence_status` (string or null, May be absent) - `sequence_step` (integer, May be absent, default 0) - `state` (string or null, May be absent) - `status_url` (string, Always present) - `timezone` (string or null, May be absent) - `transfer_phone` (string or null, May be absent): Always null for now. - `trustedform_cert_url` (string or null, May be absent) - `updated_at` (string (date-time), Always present) - `zip_code` (string or null, May be absent) **201 Created**: Created and enrolled. A draft campaign is accepted and paused (not dialed). A retry with the same Idempotency-Key and body returns this response unchanged (X-Idempotency-Replayed: true). Same body as above. ## Errors - 400 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. - 400 `DNC_BLOCKED`: The phone is on the Do Not Call list. No lead was created. Next step: Retrying will fail the same way. Fix the request, or contact us. - 400 `SOURCE_PAUSED`: The campaign is paused. No lead was created. Retry only after we tell you the campaign is live. Next step: Retrying will fail the same way. Fix the request, or contact us. - 400 `SOURCE_INACTIVE`: The campaign is completed or not taking leads. A draft campaign accepts the lead and pauses it instead. Next step: Retrying will fail the same way. Fix the request, or contact us. - 400 `CONSENT_INVALID`: trustedform_cert_url is not a TrustedForm certificate URL. Entrovox checks the format only. Next step: Retrying will fail the same way. Fix the request, or contact us. - 400 `CROSS_SELL_PAIR_INVALID`: The owned and target lines of business are not a pair this cross-sell campaign quotes. No lead was created. Next step: Retrying will fail the same way. Fix the request, or contact us. - 403 `INSUFFICIENT_SCOPE`: A read key tried to write. Use a key with write scope. Next step: Retrying will fail the same way. Fix the request, or contact us. - 403 `API_KEY_ENDPOINT_NOT_ALLOWED`: The endpoint is outside the partner surface, or the key's campaign binding is invalid. Ask for a new key. Next step: Retrying will fail the same way. Fix the request, or contact us. - 403 `LEAD_SOURCE_NOT_ALLOWED`: The body names a campaign other than the one this key is bound to. Next step: Retrying will fail the same way. Fix the request, or contact us. - 404 `LEAD_SOURCE_NOT_FOUND`: lead_source_id is not a campaign in your organization. Next step: Retrying will fail the same way. Fix the request, or contact us. - 404 `LEAD_NOT_FOUND`: No lead with that id in your organization. Next step: Retrying will fail the same way. Fix the request, or contact us. - 409 `EXTERNAL_ID_CONFLICT`: The same external_id exists in the campaign with a different phone or is_test. Next step: The lead or request already exists. Fetch it instead of sending it again. - 409 `LEAD_PHONE_CONFLICT`: A live lead with this phone is already enrolled under another external_id. Next step: The lead or request already exists. Fetch it instead of sending it again. - 409 `IDEMPOTENCY_KEY_REUSED`: The same Idempotency-Key and path came with a different body. Next step: Retrying will fail the same way. Fix the request, or contact us. - 409 `IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still being processed. Next step: Safe to retry after Retry-After when present, otherwise back off. On a POST, resend the same Idempotency-Key and body. - 422 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. - 503 `PROVIDER_UNAVAILABLE`: Our DNC check could not run, or other posts for the same phone were being written at that moment. No lead was created. On a batch result row, resend only the failed rows in a new batch with a fresh Idempotency-Key; the external_id keeps it idempotent. Next step: Safe to retry after Retry-After when present, otherwise back off. On a POST, resend the same Idempotency-Key and body. Any request can also return `AUTHENTICATION_REQUIRED`, `TOKEN_INVALID`, `API_KEY_EXPIRED`, `RATE_LIMIT_EXCEEDED` or `INTERNAL_ERROR`. ## Request samples cURL: ```bash curl -X POST "https://api.entrovox.com/v1/leads" \ -H "Authorization: ApiKey $ENTROVOX_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "first_name": "Jordan", "last_name": "Lee", "phone": "+15555550100", "external_id": "crm-88421", "is_test": true, "email": "jordan.lee@example.com", "zip_code": "98101", "preferred_language": "en", "metadata": { "campaign": "spring-auto" } }' ``` Python: ```python import os, uuid, requests r = requests.post( "https://api.entrovox.com/v1/leads", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "first_name": "Jordan", "last_name": "Lee", "phone": "+15555550100", "external_id": "crm-88421", "is_test": True, "email": "jordan.lee@example.com", "zip_code": "98101", "preferred_language": "en", "metadata": { "campaign": "spring-auto", }, }, ) print(r.status_code, r.json()) ``` Node.js: ```javascript import { randomUUID } from "node:crypto"; const res = await fetch("https://api.entrovox.com/v1/leads", { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, "Idempotency-Key": randomUUID(), "Content-Type": "application/json", }, body: JSON.stringify({ "first_name": "Jordan", "last_name": "Lee", "phone": "+15555550100", "external_id": "crm-88421", "is_test": true, "email": "jordan.lee@example.com", "zip_code": "98101", "preferred_language": "en", "metadata": { "campaign": "spring-auto" } }), }); console.log(res.status, await res.json()); ``` ## Response examples 200 OK: ```json { "data": { "attempt_count": 0, "calls": null, "calls_url": "https://api.entrovox.com/v1/leads/LEAD_ID/calls", "created_at": "2026-01-15T17:30:00Z", "current_disposition": "string", "dedup_status": null, "dial_blocker": null, "disposition_at": null, "email": "jordan.lee@example.com", "external_id": "crm-88421", "first_name": "Jordan", "id": "LEAD_ID", "is_dnc": false, "is_test": false, "jornaya_leadid": null, "last_attempted_at": null, "last_name": "Lee", "metadata": {}, "national_dnc_status": null, "next_attempt_at": null, "organization_id": "ORGANIZATION_ID", "pause_is_queued": false, "paused": false, "paused_at": null, "paused_reason": null, "phone": "+15555550100", "phone_alt": "+15555550101", "preferred_language": null, "replayed": null, "sequence_status": null, "sequence_step": 0, "state": "WA", "status_url": "https://api.entrovox.com/v1/leads/LEAD_ID", "timezone": "America/Los_Angeles", "transfer_phone": null, "trustedform_cert_url": null, "updated_at": "2026-01-15T17:30:00Z", "zip_code": "98101" } } ``` 201 Created: ```json { "data": { "attempt_count": 0, "calls": null, "calls_url": "https://api.entrovox.com/v1/leads/LEAD_ID/calls", "created_at": "2026-01-15T17:30:00Z", "current_disposition": "string", "dedup_status": null, "dial_blocker": null, "disposition_at": null, "email": "jordan.lee@example.com", "external_id": "crm-88421", "first_name": "Jordan", "id": "LEAD_ID", "is_dnc": false, "is_test": false, "jornaya_leadid": null, "last_attempted_at": null, "last_name": "Lee", "metadata": {}, "national_dnc_status": null, "next_attempt_at": null, "organization_id": "ORGANIZATION_ID", "pause_is_queued": false, "paused": false, "paused_at": null, "paused_reason": null, "phone": "+15555550100", "phone_alt": "+15555550101", "preferred_language": null, "replayed": null, "sequence_status": null, "sequence_step": 0, "state": "WA", "status_url": "https://api.entrovox.com/v1/leads/LEAD_ID", "timezone": "America/Los_Angeles", "transfer_phone": null, "trustedform_cert_url": null, "updated_at": "2026-01-15T17:30:00Z", "zip_code": "98101" } } ``` 400 Bad Request: ```json { "error": { "code": "VALIDATION_ERROR", "message": "A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field.", "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` 403 Forbidden: ```json { "error": { "code": "INSUFFICIENT_SCOPE", "message": "A read key tried to write. Use a key with write scope.", "doc_url": "https://api.entrovox.com/developer/docs#insufficient-scope", "request_id": "REQUEST_ID" } } ``` 404 Not Found: ```json { "error": { "code": "LEAD_SOURCE_NOT_FOUND", "message": "lead_source_id is not a campaign in your organization.", "doc_url": "https://api.entrovox.com/developer/docs#lead-source-not-found", "request_id": "REQUEST_ID" } } ``` 409 Conflict: ```json { "error": { "code": "EXTERNAL_ID_CONFLICT", "message": "The same external_id exists in the campaign with a different phone or is_test.", "doc_url": "https://api.entrovox.com/developer/docs#external-id-conflict", "request_id": "REQUEST_ID" } } ``` 422 Unprocessable Entity: ```json { "error": { "code": "VALIDATION_ERROR", "message": "external_id is required on API-key posts so a retry cannot start a second sequence, and it was missing, so we did not create a lead. Send your lead id as external_id and retry.", "param": "external_id", "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` 503 Service Unavailable: ```json { "error": { "code": "PROVIDER_UNAVAILABLE", "message": "Our DNC check could not run, or other posts for the same phone were being written at that moment. No lead was created. On a batch result row, resend only the failed rows in a new batch with a fresh Idempotency-Key; the external_id keeps it idempotent.", "doc_url": "https://api.entrovox.com/developer/docs#provider-unavailable", "request_id": "REQUEST_ID" } } ``` --- # Create leads in a batch `POST /v1/leads/batch` Post up to 500 leads. API keys: `200` with `items`, one per input row in order, whatever the mix of `created` / `replayed` / `conflict` / `rejected`. A row with code `PROVIDER_UNAVAILABLE` created nothing and is safe to resend in a new batch. Send an `Idempotency-Key` (UUID) to replay the whole response on a retry. ## Headers - `Authorization` (string, required): `ApiKey $ENTROVOX_KEY`. Keys are issued per organization. - `Idempotency-Key` (string or null, optional): A UUID you generate for each new request. Resending the same key and body returns the original response. ## Body - `lead_source_id` (string or null, optional): Campaign id. Optional when the key is bound to a campaign. - `leads` (array of object, required) - `email` (string or null, max 320, optional) - `external_id` (string or null, 1–128, required): Your lead id. Unique per organization; a retry with it replays the lead. - `first_name` (string, 1–200, required): Not blank. A blank value is 400 VALIDATION_ERROR. - `is_test` (boolean, optional, default false): true stores a test lead (a safe hello-world): it is never enrolled, dialed or texted, never blocks a live phone, and is not listed. Read it back by id. - `jornaya_leadid` (string or null, max 256, optional) - `last_name` (string, 1–200, required): Not blank. A blank value is 400 VALIDATION_ERROR. - `lead_generated_at` (string or null, optional) - `lead_source_id` (string or null, optional) - `metadata` (object or null, optional): Your own key and value pairs, stored and echoed unchanged. At most 64 KB and 32 levels deep, with finite numbers and UTF-8 text without NUL characters. Otherwise 400 VALIDATION_ERROR. - `owned_line_of_business` (string or null, max 64, optional) - `phone` (string, 1–32, required): E.164 for a US or Canadian number: +1 then 10 digits, like +14255551234. Anything else is 400 VALIDATION_ERROR. - `phone_alt` (string or null, optional): A second number, in the same form as phone: +1 then 10 digits. Anything else is 400 VALIDATION_ERROR. - `preferred_language` (string or null, optional, one of en, es) - `state` (string or null, max 64, optional) - `target_line_of_business` (string or null, max 64, optional) - `timezone` (string or null, max 64, optional): An IANA time zone such as America/Los_Angeles, and one that state uses. Omit it and we derive it from zip_code or state. Anything else is 400 VALIDATION_ERROR. - `transfer_phone` (string or null, optional): Not supported yet: any value is rejected with 400 VALIDATION_ERROR (param transfer_phone). Qualified leads transfer to the campaign number. - `trustedform_cert_url` (string or null, max 512, optional): The https://cert.trustedform.com/ URL from your form (40 hex characters). Anything else is 400 CONSENT_INVALID. - `zip_code` (string or null, max 10, optional) ## Returns **200 OK**: Always, when the request itself is well-formed: partial success is in items, one per input row in input order (a batch where every row failed is still 200). A row with code PROVIDER_UNAVAILABLE created nothing and is safe to resend in a new batch; its external_id makes that idempotent. A retry with the same Idempotency-Key and body returns this response unchanged (X-Idempotency-Replayed: true). - `created` (integer, Always present) - `items` (array of object, Always present) - `code` (string or null, May be absent): Set on conflict and rejected rows. - `external_id` (string or null, May be absent) - `index` (integer, Always present): Position of the row in the request's leads array. - `lead_id` (string or null, May be absent): Set on created and replayed rows. - `message` (string or null, May be absent): Set on conflict and rejected rows. - `status` (string, Always present, one of created, replayed, conflict, rejected) - `status_url` (string or null, May be absent): Set on created and replayed rows. - `lead_source_id` (string, Always present) - `rejected` (integer, Always present): Rows with status rejected or conflict. - `replayed` (integer, Always present) **201 Created**: Successful Response - `created` (integer, Always present) - `deduplicated` (integer, Always present) - `errors` (array of object, May be absent) - `lead_source_id` (string, Always present) ## Errors - 400 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. - 403 `INSUFFICIENT_SCOPE`: A read key tried to write. Use a key with write scope. Next step: Retrying will fail the same way. Fix the request, or contact us. - 403 `API_KEY_ENDPOINT_NOT_ALLOWED`: The endpoint is outside the partner surface, or the key's campaign binding is invalid. Ask for a new key. Next step: Retrying will fail the same way. Fix the request, or contact us. - 403 `LEAD_SOURCE_NOT_ALLOWED`: The body names a campaign other than the one this key is bound to. Next step: Retrying will fail the same way. Fix the request, or contact us. - 404 `LEAD_SOURCE_NOT_FOUND`: lead_source_id is not a campaign in your organization. Next step: Retrying will fail the same way. Fix the request, or contact us. - 409 `IDEMPOTENCY_KEY_REUSED`: The same Idempotency-Key and path came with a different body. Next step: Retrying will fail the same way. Fix the request, or contact us. - 409 `IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still being processed. Next step: Safe to retry after Retry-After when present, otherwise back off. On a POST, resend the same Idempotency-Key and body. - 422 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. Any request can also return `AUTHENTICATION_REQUIRED`, `TOKEN_INVALID`, `API_KEY_EXPIRED`, `RATE_LIMIT_EXCEEDED` or `INTERNAL_ERROR`. ## Request samples cURL: ```bash curl -X POST "https://api.entrovox.com/v1/leads/batch" \ -H "Authorization: ApiKey $ENTROVOX_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "leads": [ { "first_name": "Jordan", "last_name": "Lee", "phone": "+15555550100", "external_id": "crm-88421", "is_test": true, "email": "jordan.lee@example.com", "zip_code": "98101", "preferred_language": "en", "metadata": { "campaign": "spring-auto" } }, { "first_name": "Jordan", "last_name": "Lee", "phone": "+15555550101", "external_id": "crm-88422", "is_test": true, "email": "jordan.lee@example.com", "zip_code": "98101", "preferred_language": "en", "metadata": { "campaign": "spring-auto" } } ] }' ``` Python: ```python import os, uuid, requests r = requests.post( "https://api.entrovox.com/v1/leads/batch", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "leads": [ { "first_name": "Jordan", "last_name": "Lee", "phone": "+15555550100", "external_id": "crm-88421", "is_test": True, "email": "jordan.lee@example.com", "zip_code": "98101", "preferred_language": "en", "metadata": { "campaign": "spring-auto", }, }, { "first_name": "Jordan", "last_name": "Lee", "phone": "+15555550101", "external_id": "crm-88422", "is_test": True, "email": "jordan.lee@example.com", "zip_code": "98101", "preferred_language": "en", "metadata": { "campaign": "spring-auto", }, }, ], }, ) print(r.status_code, r.json()) ``` Node.js: ```javascript import { randomUUID } from "node:crypto"; const res = await fetch("https://api.entrovox.com/v1/leads/batch", { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, "Idempotency-Key": randomUUID(), "Content-Type": "application/json", }, body: JSON.stringify({ "leads": [ { "first_name": "Jordan", "last_name": "Lee", "phone": "+15555550100", "external_id": "crm-88421", "is_test": true, "email": "jordan.lee@example.com", "zip_code": "98101", "preferred_language": "en", "metadata": { "campaign": "spring-auto" } }, { "first_name": "Jordan", "last_name": "Lee", "phone": "+15555550101", "external_id": "crm-88422", "is_test": true, "email": "jordan.lee@example.com", "zip_code": "98101", "preferred_language": "en", "metadata": { "campaign": "spring-auto" } } ] }), }); console.log(res.status, await res.json()); ``` ## Response examples 200 OK: ```json { "created": 0, "items": [ { "code": null, "external_id": "crm-88421", "index": 0, "lead_id": null, "message": null, "status": "created", "status_url": null } ], "lead_source_id": "LEAD_SOURCE_ID", "rejected": 0, "replayed": 0 } ``` 201 Created: ```json { "data": { "created": 0, "deduplicated": 0, "errors": [ {} ], "lead_source_id": "LEAD_SOURCE_ID" } } ``` 400 Bad Request: ```json { "error": { "code": "VALIDATION_ERROR", "message": "A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field.", "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` 403 Forbidden: ```json { "error": { "code": "INSUFFICIENT_SCOPE", "message": "A read key tried to write. Use a key with write scope.", "doc_url": "https://api.entrovox.com/developer/docs#insufficient-scope", "request_id": "REQUEST_ID" } } ``` 404 Not Found: ```json { "error": { "code": "LEAD_SOURCE_NOT_FOUND", "message": "lead_source_id is not a campaign in your organization.", "doc_url": "https://api.entrovox.com/developer/docs#lead-source-not-found", "request_id": "REQUEST_ID" } } ``` 409 Conflict: ```json { "error": { "code": "IDEMPOTENCY_KEY_REUSED", "message": "The same Idempotency-Key and path came with a different body.", "doc_url": "https://api.entrovox.com/developer/docs#idempotency-key-reused", "request_id": "REQUEST_ID" } } ``` 422 Unprocessable Entity: ```json { "error": { "code": "VALIDATION_ERROR", "message": "leads must be an array of 1 to 500 lead objects, so we did not process the request. Send between 1 and 500 leads per batch.", "param": "leads", "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` --- # Ping a lead `POST /v1/leads/ping` Would this lead be taken right now? Creates nothing. API keys only. `200` `{accepted, reason, queued_reason, lead_source_id}`; `accepted: false` is the never-accepted class. An unknown campaign is the post's `404`; a DNC check that could not run is `503 PROVIDER_UNAVAILABLE`. Takes no idempotency reservation; an `Idempotency-Key` header is ignored. ## Headers - `Authorization` (string, required): `ApiKey $ENTROVOX_KEY`. Keys are issued per organization. ## Body - `external_id` (string or null, 1–128, optional): Correlation only. A lead in this campaign with the same external_id holding the phone counts as a replay, so it is accepted. Not stored or echoed. - `lead_source_id` (string or null, optional) - `phone` (string or null, max 32, optional) - `state` (string or null, max 64, optional) - `target_line_of_business` (string or null, max 64, optional) - `zip_code` (string or null, max 10, optional) ## Returns **200 OK**: Always, when the request is well-formed: accepted false with a reason is the never-accepted class (dnc, already_enrolled, source_inactive, source_paused, invalid_phone; consent_invalid is reserved). accepted true may carry a queued_reason (outside_hours, missing_geography; capacity is reserved). Nothing is created or reserved. - `accepted` (boolean, Always present): False only for the never-accepted class. - `lead_source_id` (string, Always present): The campaign evaluated. - `queued_reason` (string or null, May be absent, one of outside_hours, capacity, missing_geography): Set only when accepted is true but the first dial will wait. capacity is reserved and not returned yet. - `reason` (string or null, May be absent, one of dnc, already_enrolled, source_inactive, source_paused, invalid_phone, consent_invalid): Why it would not be accepted. consent_invalid is reserved: ping carries no consent certificate, so it is not returned yet. ## Errors - 400 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. - 403 `INSUFFICIENT_SCOPE`: A read key tried to write. Use a key with write scope. Next step: Retrying will fail the same way. Fix the request, or contact us. - 403 `API_KEY_ENDPOINT_NOT_ALLOWED`: The endpoint is outside the partner surface, or the key's campaign binding is invalid. Ask for a new key. Next step: Retrying will fail the same way. Fix the request, or contact us. - 403 `LEAD_SOURCE_NOT_ALLOWED`: The body names a campaign other than the one this key is bound to. Next step: Retrying will fail the same way. Fix the request, or contact us. - 404 `LEAD_SOURCE_NOT_FOUND`: lead_source_id is not a campaign in your organization. Next step: Retrying will fail the same way. Fix the request, or contact us. - 422 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. - 503 `PROVIDER_UNAVAILABLE`: Our DNC check could not run, or other posts for the same phone were being written at that moment. No lead was created. On a batch result row, resend only the failed rows in a new batch with a fresh Idempotency-Key; the external_id keeps it idempotent. Next step: Safe to retry after Retry-After when present, otherwise back off. On a POST, resend the same Idempotency-Key and body. Any request can also return `AUTHENTICATION_REQUIRED`, `TOKEN_INVALID`, `API_KEY_EXPIRED`, `RATE_LIMIT_EXCEEDED` or `INTERNAL_ERROR`. ## Request samples cURL: ```bash curl -X POST "https://api.entrovox.com/v1/leads/ping" \ -H "Authorization: ApiKey $ENTROVOX_KEY" \ -H "Content-Type: application/json" \ -d '{ "phone": "+15555550100" }' ``` Python: ```python import os, requests r = requests.post( "https://api.entrovox.com/v1/leads/ping", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", }, json={ "phone": "+15555550100", }, ) print(r.status_code, r.json()) ``` Node.js: ```javascript const res = await fetch("https://api.entrovox.com/v1/leads/ping", { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "phone": "+15555550100" }), }); console.log(res.status, await res.json()); ``` ## Response examples 200 OK: ```json { "accepted": false, "lead_source_id": "LEAD_SOURCE_ID", "queued_reason": "outside_hours", "reason": "dnc" } ``` 400 Bad Request: ```json { "error": { "code": "VALIDATION_ERROR", "message": "A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field.", "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` 403 Forbidden: ```json { "error": { "code": "INSUFFICIENT_SCOPE", "message": "A read key tried to write. Use a key with write scope.", "doc_url": "https://api.entrovox.com/developer/docs#insufficient-scope", "request_id": "REQUEST_ID" } } ``` 404 Not Found: ```json { "error": { "code": "LEAD_SOURCE_NOT_FOUND", "message": "lead_source_id is not a campaign in your organization.", "doc_url": "https://api.entrovox.com/developer/docs#lead-source-not-found", "request_id": "REQUEST_ID" } } ``` 422 Unprocessable Entity: ```json { "error": { "code": "VALIDATION_ERROR", "message": "The request body must be a JSON object (or omitted), so we did not run the check. Send the lead's fields as an object and retry.", "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` 503 Service Unavailable: ```json { "error": { "code": "PROVIDER_UNAVAILABLE", "message": "Our DNC check could not run, or other posts for the same phone were being written at that moment. No lead was created. On a batch result row, resend only the failed rows in a new batch with a fresh Idempotency-Key; the external_id keeps it idempotent.", "doc_url": "https://api.entrovox.com/developer/docs#provider-unavailable", "request_id": "REQUEST_ID" } } ``` --- # Retrieve a lead `GET /v1/leads/{lead_id}` The lead's status URL: current disposition, schedule, and call attempts. API keys get the partner shape with `calls[]` (transcript, recording and analysis links per attempt). A campaign-bound key gets `404` for a lead outside its campaign. ## Headers - `Authorization` (string, required): `ApiKey $ENTROVOX_KEY`. Keys are issued per organization. ## Path parameters - `lead_id` (string, required) ## Returns **200 OK**: The status URL: the lead and its call attempts. - `attempt_count` (integer, May be absent, default 0) - `calls` (array of object or null, May be absent): Every attempt, newest last. On GET /leads/{id} and POST responses. - `analysis_url` (string, Always present) - `attempt_number` (integer or null, May be absent) - `call_outcome` (string or null, May be absent) - `disposition` (string or null, May be absent) - `duration_seconds` (integer or null, May be absent) - `ended_at` (string (date-time) or null, May be absent) - `id` (string, Always present) - `recording_url` (string, Always present) - `started_at` (string (date-time) or null, May be absent) - `status` (string or null, May be absent) - `transcript_url` (string, Always present) - `calls_url` (string, Always present) - `created_at` (string (date-time), Always present) - `current_disposition` (string, Always present) - `dedup_status` (string or null, May be absent) - `dial_blocker` (string or null, May be absent) - `disposition_at` (string (date-time) or null, May be absent) - `email` (string or null, May be absent) - `external_id` (string or null, May be absent) - `first_name` (string or null, May be absent) - `id` (string, Always present) - `is_dnc` (boolean, May be absent, default false) - `is_test` (boolean, May be absent, default false) - `jornaya_leadid` (string or null, May be absent) - `last_attempted_at` (string (date-time) or null, May be absent) - `last_name` (string or null, May be absent) - `metadata` (object, May be absent): Free-form key and value pairs. - `national_dnc_status` (string or null, May be absent) - `next_attempt_at` (string (date-time) or null, May be absent) - `organization_id` (string, Always present) - `pause_is_queued` (boolean, May be absent, default false) - `paused` (boolean, May be absent, default false) - `paused_at` (string (date-time) or null, May be absent) - `paused_reason` (string or null, May be absent) - `phone` (string, Always present) - `phone_alt` (string or null, May be absent) - `preferred_language` (string or null, May be absent) - `replayed` (boolean or null, May be absent): On POST responses: true on a 200 replay. - `sequence_status` (string or null, May be absent) - `sequence_step` (integer, May be absent, default 0) - `state` (string or null, May be absent) - `status_url` (string, Always present) - `timezone` (string or null, May be absent) - `transfer_phone` (string or null, May be absent): Always null for now. - `trustedform_cert_url` (string or null, May be absent) - `updated_at` (string (date-time), Always present) - `zip_code` (string or null, May be absent) ## Errors - 403 `INSUFFICIENT_SCOPE`: A read key tried to write. Use a key with write scope. Next step: Retrying will fail the same way. Fix the request, or contact us. - 403 `API_KEY_ENDPOINT_NOT_ALLOWED`: The endpoint is outside the partner surface, or the key's campaign binding is invalid. Ask for a new key. Next step: Retrying will fail the same way. Fix the request, or contact us. - 404 `LEAD_NOT_FOUND`: No lead with that id in your organization. Next step: Retrying will fail the same way. Fix the request, or contact us. - 422 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. Any request can also return `AUTHENTICATION_REQUIRED`, `TOKEN_INVALID`, `API_KEY_EXPIRED`, `RATE_LIMIT_EXCEEDED` or `INTERNAL_ERROR`. ## Request samples cURL: ```bash curl -X GET "https://api.entrovox.com/v1/leads/LEAD_ID" \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` Python: ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/leads/LEAD_ID", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", }, ) print(r.status_code, r.json()) ``` Node.js: ```javascript const res = await fetch("https://api.entrovox.com/v1/leads/LEAD_ID", { method: "GET", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, }, }); console.log(res.status, await res.json()); ``` ## Response examples 200 OK: ```json { "data": { "attempt_count": 0, "calls": null, "calls_url": "https://api.entrovox.com/v1/leads/LEAD_ID/calls", "created_at": "2026-01-15T17:30:00Z", "current_disposition": "string", "dedup_status": null, "dial_blocker": null, "disposition_at": null, "email": "jordan.lee@example.com", "external_id": "crm-88421", "first_name": "Jordan", "id": "LEAD_ID", "is_dnc": false, "is_test": false, "jornaya_leadid": null, "last_attempted_at": null, "last_name": "Lee", "metadata": {}, "national_dnc_status": null, "next_attempt_at": null, "organization_id": "ORGANIZATION_ID", "pause_is_queued": false, "paused": false, "paused_at": null, "paused_reason": null, "phone": "+15555550100", "phone_alt": "+15555550101", "preferred_language": null, "replayed": null, "sequence_status": null, "sequence_step": 0, "state": "WA", "status_url": "https://api.entrovox.com/v1/leads/LEAD_ID", "timezone": "America/Los_Angeles", "transfer_phone": null, "trustedform_cert_url": null, "updated_at": "2026-01-15T17:30:00Z", "zip_code": "98101" } } ``` 403 Forbidden: ```json { "error": { "code": "INSUFFICIENT_SCOPE", "message": "A read key tried to write. Use a key with write scope.", "doc_url": "https://api.entrovox.com/developer/docs#insufficient-scope", "request_id": "REQUEST_ID" } } ``` 404 Not Found: ```json { "error": { "code": "LEAD_NOT_FOUND", "message": "No lead with that id in your organization.", "doc_url": "https://api.entrovox.com/developer/docs#lead-not-found", "request_id": "REQUEST_ID" } } ``` 422 Unprocessable Entity: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed.", "details": { "errors": [ { "type": "missing", "loc": [ "body" ], "msg": "Field required", "input": {} } ] }, "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` --- # List leads `GET /v1/leads` List leads, or look one up by your `external_id`. API keys get the partner lead shape with `status_url` / `calls_url` on every row; a campaign-bound key sees only its campaign. `screen_status` is not supported here: the partner list refuses it rather than ignore it. ## Headers - `Authorization` (string, required): `ApiKey $ENTROVOX_KEY`. Keys are issued per organization. ## Query parameters - `lead_source_id` (string or null, optional) - `disposition` (string or null, optional) - `search` (string or null, max 100, optional) - `external_id` (string or null, 1–128, optional) - `cursor` (string or null, optional) - `limit` (integer, 1–200, optional, default 50) - `screen_status` (string or null, optional, one of flagged, blocked) ## Returns **200 OK**: A page of leads (no calls). - `data` (array of object, Always present) - `attempt_count` (integer, May be absent, default 0) - `calls` (array of object or null, May be absent): Every attempt, newest last. On GET /leads/{id} and POST responses. - `analysis_url` (string, Always present) - `attempt_number` (integer or null, May be absent) - `call_outcome` (string or null, May be absent) - `disposition` (string or null, May be absent) - `duration_seconds` (integer or null, May be absent) - `ended_at` (string (date-time) or null, May be absent) - `id` (string, Always present) - `recording_url` (string, Always present) - `started_at` (string (date-time) or null, May be absent) - `status` (string or null, May be absent) - `transcript_url` (string, Always present) - `calls_url` (string, Always present) - `created_at` (string (date-time), Always present) - `current_disposition` (string, Always present) - `dedup_status` (string or null, May be absent) - `dial_blocker` (string or null, May be absent) - `disposition_at` (string (date-time) or null, May be absent) - `email` (string or null, May be absent) - `external_id` (string or null, May be absent) - `first_name` (string or null, May be absent) - `id` (string, Always present) - `is_dnc` (boolean, May be absent, default false) - `is_test` (boolean, May be absent, default false) - `jornaya_leadid` (string or null, May be absent) - `last_attempted_at` (string (date-time) or null, May be absent) - `last_name` (string or null, May be absent) - `metadata` (object, May be absent): Free-form key and value pairs. - `national_dnc_status` (string or null, May be absent) - `next_attempt_at` (string (date-time) or null, May be absent) - `organization_id` (string, Always present) - `pause_is_queued` (boolean, May be absent, default false) - `paused` (boolean, May be absent, default false) - `paused_at` (string (date-time) or null, May be absent) - `paused_reason` (string or null, May be absent) - `phone` (string, Always present) - `phone_alt` (string or null, May be absent) - `preferred_language` (string or null, May be absent) - `replayed` (boolean or null, May be absent): On POST responses: true on a 200 replay. - `sequence_status` (string or null, May be absent) - `sequence_step` (integer, May be absent, default 0) - `state` (string or null, May be absent) - `status_url` (string, Always present) - `timezone` (string or null, May be absent) - `transfer_phone` (string or null, May be absent): Always null for now. - `trustedform_cert_url` (string or null, May be absent) - `updated_at` (string (date-time), Always present) - `zip_code` (string or null, May be absent) - `meta` (object, Always present) - `has_more` (boolean, Always present) - `limit` (integer, Always present) - `next_cursor` (string or null, May be absent) - `total` (integer, Always present) ## Errors - 400 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. - 403 `INSUFFICIENT_SCOPE`: A read key tried to write. Use a key with write scope. Next step: Retrying will fail the same way. Fix the request, or contact us. - 403 `API_KEY_ENDPOINT_NOT_ALLOWED`: The endpoint is outside the partner surface, or the key's campaign binding is invalid. Ask for a new key. Next step: Retrying will fail the same way. Fix the request, or contact us. - 403 `LEAD_SOURCE_NOT_ALLOWED`: The body names a campaign other than the one this key is bound to. Next step: Retrying will fail the same way. Fix the request, or contact us. - 422 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. - 422 `UNSUPPORTED_FILTER`: That filter is not available to API keys. Next step: Retrying will fail the same way. Fix the request, or contact us. Any request can also return `AUTHENTICATION_REQUIRED`, `TOKEN_INVALID`, `API_KEY_EXPIRED`, `RATE_LIMIT_EXCEEDED` or `INTERNAL_ERROR`. ## Request samples cURL: ```bash curl -X GET "https://api.entrovox.com/v1/leads?limit=25" \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` Python: ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/leads", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", }, params={ "limit": 25, }, ) print(r.status_code, r.json()) ``` Node.js: ```javascript const res = await fetch("https://api.entrovox.com/v1/leads?limit=25", { method: "GET", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, }, }); console.log(res.status, await res.json()); ``` ## Response examples 200 OK: ```json { "data": [ { "attempt_count": 0, "calls": null, "calls_url": "https://api.entrovox.com/v1/leads/LEAD_ID/calls", "created_at": "2026-01-15T17:30:00Z", "current_disposition": "string", "dedup_status": null, "dial_blocker": null, "disposition_at": null, "email": "jordan.lee@example.com", "external_id": "crm-88421", "first_name": "Jordan", "id": "LEAD_ID", "is_dnc": false, "is_test": false, "jornaya_leadid": null, "last_attempted_at": null, "last_name": "Lee", "metadata": {}, "national_dnc_status": null, "next_attempt_at": null, "organization_id": "ORGANIZATION_ID", "pause_is_queued": false, "paused": false, "paused_at": null, "paused_reason": null, "phone": "+15555550100", "phone_alt": "+15555550101", "preferred_language": null, "replayed": null, "sequence_status": null, "sequence_step": 0, "state": "WA", "status_url": "https://api.entrovox.com/v1/leads/LEAD_ID", "timezone": "America/Los_Angeles", "transfer_phone": null, "trustedform_cert_url": null, "updated_at": "2026-01-15T17:30:00Z", "zip_code": "98101" } ], "meta": { "has_more": false, "limit": 25, "next_cursor": null, "total": 1 } } ``` 400 Bad Request: ```json { "error": { "code": "VALIDATION_ERROR", "message": "A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field.", "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` 403 Forbidden: ```json { "error": { "code": "INSUFFICIENT_SCOPE", "message": "A read key tried to write. Use a key with write scope.", "doc_url": "https://api.entrovox.com/developer/docs#insufficient-scope", "request_id": "REQUEST_ID" } } ``` 422 Unprocessable Entity: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed.", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "limit" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "abc" } ] }, "param": "limit", "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` --- # List calls for a lead `GET /v1/leads/{lead_id}/calls` Every call attempt for the lead, oldest first, with transcript, recording and analysis links. Cursor-paginated. ## Headers - `Authorization` (string, required): `ApiKey $ENTROVOX_KEY`. Keys are issued per organization. ## Path parameters - `lead_id` (string, required) ## Query parameters - `cursor` (string or null, optional) - `limit` (integer, 1–200, optional, default 50) ## Returns **200 OK**: A page of the lead's call attempts, oldest first. - `data` (array of object, Always present) - `analysis_url` (string, Always present) - `attempt_number` (integer or null, May be absent) - `call_outcome` (string or null, May be absent) - `disposition` (string or null, May be absent) - `duration_seconds` (integer or null, May be absent) - `ended_at` (string (date-time) or null, May be absent) - `id` (string, Always present) - `recording_url` (string, Always present) - `started_at` (string (date-time) or null, May be absent) - `status` (string or null, May be absent) - `transcript_url` (string, Always present) - `meta` (object, Always present) - `has_more` (boolean, Always present) - `limit` (integer, Always present) - `next_cursor` (string or null, May be absent) - `total` (integer, Always present) ## Errors - 400 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. - 403 `INSUFFICIENT_SCOPE`: A read key tried to write. Use a key with write scope. Next step: Retrying will fail the same way. Fix the request, or contact us. - 403 `API_KEY_ENDPOINT_NOT_ALLOWED`: The endpoint is outside the partner surface, or the key's campaign binding is invalid. Ask for a new key. Next step: Retrying will fail the same way. Fix the request, or contact us. - 404 `LEAD_NOT_FOUND`: No lead with that id in your organization. Next step: Retrying will fail the same way. Fix the request, or contact us. - 422 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. Any request can also return `AUTHENTICATION_REQUIRED`, `TOKEN_INVALID`, `API_KEY_EXPIRED`, `RATE_LIMIT_EXCEEDED` or `INTERNAL_ERROR`. ## Request samples cURL: ```bash curl -X GET "https://api.entrovox.com/v1/leads/LEAD_ID/calls" \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` Python: ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/leads/LEAD_ID/calls", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", }, ) print(r.status_code, r.json()) ``` Node.js: ```javascript const res = await fetch("https://api.entrovox.com/v1/leads/LEAD_ID/calls", { method: "GET", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, }, }); console.log(res.status, await res.json()); ``` ## Response examples 200 OK: ```json { "data": [ { "analysis_url": "https://api.entrovox.com/v1/calls/CALL_ID/analysis", "attempt_number": null, "call_outcome": null, "disposition": null, "duration_seconds": null, "ended_at": null, "id": "CALL_ID", "recording_url": "https://api.entrovox.com/v1/calls/CALL_ID/recording-url", "started_at": null, "status": "active", "transcript_url": "https://api.entrovox.com/v1/calls/CALL_ID/transcript" } ], "meta": { "has_more": false, "limit": 25, "next_cursor": null, "total": 1 } } ``` 400 Bad Request: ```json { "error": { "code": "VALIDATION_ERROR", "message": "A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field.", "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` 403 Forbidden: ```json { "error": { "code": "INSUFFICIENT_SCOPE", "message": "A read key tried to write. Use a key with write scope.", "doc_url": "https://api.entrovox.com/developer/docs#insufficient-scope", "request_id": "REQUEST_ID" } } ``` 404 Not Found: ```json { "error": { "code": "LEAD_NOT_FOUND", "message": "No lead with that id in your organization.", "doc_url": "https://api.entrovox.com/developer/docs#lead-not-found", "request_id": "REQUEST_ID" } } ``` 422 Unprocessable Entity: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed.", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "limit" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "abc" } ] }, "param": "limit", "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` --- # Pause a lead `POST /v1/leads/{lead_id}/pause` Pause the calling sequence for a single lead. Atomic across all of the lead's active lead_source_leads rows. Idempotent: re-pausing returns `already_paused=True` with `updated_count=0`. A call already ringing is not killed. Returns 404 if the lead is not in the caller's org (or, for a campaign-bound key, not in its campaign). Returns 409 if the lead has no active sequence (already terminal). ## Headers - `Authorization` (string, required): `ApiKey $ENTROVOX_KEY`. Keys are issued per organization. ## Path parameters - `lead_id` (string, required) ## Body - `reason` (string or null, max 140, optional) ## Returns **200 OK**: Paused (or already paused). - `already_paused` (boolean, Always present) - `paused_at` (string (date-time) or null, May be absent) - `paused_reason` (string or null, May be absent) - `updated_count` (integer, Always present) ## Errors - 400 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. - 403 `INSUFFICIENT_SCOPE`: A read key tried to write. Use a key with write scope. Next step: Retrying will fail the same way. Fix the request, or contact us. - 403 `API_KEY_ENDPOINT_NOT_ALLOWED`: The endpoint is outside the partner surface, or the key's campaign binding is invalid. Ask for a new key. Next step: Retrying will fail the same way. Fix the request, or contact us. - 404 `LEAD_NOT_FOUND`: No lead with that id in your organization. Next step: Retrying will fail the same way. Fix the request, or contact us. - 409 `LEAD_NOT_PAUSEABLE`: The lead's sequence already ended, so it cannot be paused. Next step: Retrying will fail the same way. Fix the request, or contact us. - 409 `LEAD_ENROLLED_ELSEWHERE`: Entrovox also runs this lead outside your campaign, so you cannot pause or resume it. Ask us. Next step: Retrying will fail the same way. Fix the request, or contact us. - 422 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. Any request can also return `AUTHENTICATION_REQUIRED`, `TOKEN_INVALID`, `API_KEY_EXPIRED`, `RATE_LIMIT_EXCEEDED` or `INTERNAL_ERROR`. ## Request samples cURL: ```bash curl -X POST "https://api.entrovox.com/v1/leads/LEAD_ID/pause" \ -H "Authorization: ApiKey $ENTROVOX_KEY" \ -H "Content-Type: application/json" \ -d '{}' ``` Python: ```python import os, requests r = requests.post( "https://api.entrovox.com/v1/leads/LEAD_ID/pause", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", }, json={}, ) print(r.status_code, r.json()) ``` Node.js: ```javascript const res = await fetch("https://api.entrovox.com/v1/leads/LEAD_ID/pause", { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({}), }); console.log(res.status, await res.json()); ``` ## Response examples 200 OK: ```json { "data": { "already_paused": false, "paused_at": null, "paused_reason": null, "updated_count": 0 } } ``` 400 Bad Request: ```json { "error": { "code": "VALIDATION_ERROR", "message": "A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field.", "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` 403 Forbidden: ```json { "error": { "code": "INSUFFICIENT_SCOPE", "message": "A read key tried to write. Use a key with write scope.", "doc_url": "https://api.entrovox.com/developer/docs#insufficient-scope", "request_id": "REQUEST_ID" } } ``` 404 Not Found: ```json { "error": { "code": "LEAD_NOT_FOUND", "message": "No lead with that id in your organization.", "doc_url": "https://api.entrovox.com/developer/docs#lead-not-found", "request_id": "REQUEST_ID" } } ``` 409 Conflict: ```json { "error": { "code": "LEAD_NOT_PAUSEABLE", "message": "The lead's sequence already ended, so it cannot be paused.", "doc_url": "https://api.entrovox.com/developer/docs#lead-not-pauseable", "request_id": "REQUEST_ID" } } ``` 422 Unprocessable Entity: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed.", "details": { "errors": [ { "type": "missing", "loc": [ "body" ], "msg": "Field required", "input": {} } ] }, "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` --- # Resume a lead `POST /v1/leads/{lead_id}/resume` Resume the calling sequence for a single lead. `next_attempt_at` respects calling-windows so resume at 11pm local time does not trigger an immediate out-of-window dial. Idempotent: re-resuming returns `already_resumed=True` with `updated_count=0`. Returns 404 if the lead is not in the caller's org (or, for a campaign-bound key, not in its campaign). ## Headers - `Authorization` (string, required): `ApiKey $ENTROVOX_KEY`. Keys are issued per organization. ## Path parameters - `lead_id` (string, required) ## Returns **200 OK**: Resumed (or already running). - `already_resumed` (boolean, Always present) - `next_attempt_at` (string (date-time) or null, May be absent) - `resumed_at` (string (date-time), Always present) - `updated_count` (integer, Always present) ## Errors - 403 `INSUFFICIENT_SCOPE`: A read key tried to write. Use a key with write scope. Next step: Retrying will fail the same way. Fix the request, or contact us. - 403 `API_KEY_ENDPOINT_NOT_ALLOWED`: The endpoint is outside the partner surface, or the key's campaign binding is invalid. Ask for a new key. Next step: Retrying will fail the same way. Fix the request, or contact us. - 404 `LEAD_NOT_FOUND`: No lead with that id in your organization. Next step: Retrying will fail the same way. Fix the request, or contact us. - 409 `LEAD_ENROLLED_ELSEWHERE`: Entrovox also runs this lead outside your campaign, so you cannot pause or resume it. Ask us. Next step: Retrying will fail the same way. Fix the request, or contact us. - 409 `LEAD_PAUSED_BY_AGENCY`: Your Entrovox contact, their integration or the system paused this lead. A campaign key cannot resume it. Ask us. Next step: Retrying will fail the same way. Fix the request, or contact us. - 409 `LEAD_NOT_PAUSEABLE`: The lead's sequence already ended, so it cannot be paused. Next step: Retrying will fail the same way. Fix the request, or contact us. - 422 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. Any request can also return `AUTHENTICATION_REQUIRED`, `TOKEN_INVALID`, `API_KEY_EXPIRED`, `RATE_LIMIT_EXCEEDED` or `INTERNAL_ERROR`. ## Request samples cURL: ```bash curl -X POST "https://api.entrovox.com/v1/leads/LEAD_ID/resume" \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` Python: ```python import os, requests r = requests.post( "https://api.entrovox.com/v1/leads/LEAD_ID/resume", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", }, ) print(r.status_code, r.json()) ``` Node.js: ```javascript const res = await fetch("https://api.entrovox.com/v1/leads/LEAD_ID/resume", { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, }, }); console.log(res.status, await res.json()); ``` ## Response examples 200 OK: ```json { "data": { "already_resumed": false, "next_attempt_at": null, "resumed_at": "2026-01-15T17:30:00Z", "updated_count": 0 } } ``` 403 Forbidden: ```json { "error": { "code": "INSUFFICIENT_SCOPE", "message": "A read key tried to write. Use a key with write scope.", "doc_url": "https://api.entrovox.com/developer/docs#insufficient-scope", "request_id": "REQUEST_ID" } } ``` 404 Not Found: ```json { "error": { "code": "LEAD_NOT_FOUND", "message": "No lead with that id in your organization.", "doc_url": "https://api.entrovox.com/developer/docs#lead-not-found", "request_id": "REQUEST_ID" } } ``` 409 Conflict: ```json { "error": { "code": "LEAD_ENROLLED_ELSEWHERE", "message": "Entrovox also runs this lead outside your campaign, so you cannot pause or resume it. Ask us.", "doc_url": "https://api.entrovox.com/developer/docs#lead-enrolled-elsewhere", "request_id": "REQUEST_ID" } } ``` 422 Unprocessable Entity: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed.", "details": { "errors": [ { "type": "missing", "loc": [ "body" ], "msg": "Field required", "input": {} } ] }, "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` --- # Create a call `POST /v1/calls` Initiate an outbound call with a specific AI voice agent. Not available to campaign-bound partner keys, which post leads instead (`POST /v1/leads`). Pass an `Idempotency-Key` header to make retries safe: a repeated key with the same body returns the original response instead of placing a second call. The same key with a different body is refused with `409 IDEMPOTENCY_KEY_REUSED`. ## Headers - `Authorization` (string, required): `ApiKey $ENTROVOX_KEY`. Keys are issued per organization. - `Idempotency-Key` (string or null, optional): A UUID you generate for each new request. Resending the same key and body returns the original response. ## Body - `agent_id` (string, required) - `agent_overrides` (object or null, optional) - `max_duration_seconds` (integer or null, 30–3600, optional): Hard cap in seconds for this call. Shortens the plugin session cap. Cannot extend a call past that cap. - `system_prompt_append` (string or null, max 4000, optional) - `temperature` (number or null, 0–2, optional) - `tools` (object or null, optional) - `disable` (array of string, optional) - `enable` (array of string, optional) - `voice_id` (string or null, optional) - `from_number` (string or null, 2–20, optional): The caller ID to dial from, in E.164. One of from_number or from_number_id is required; send either one. - `from_number_id` (string or null, optional): The id of one of your phone numbers, used as the caller ID. One of from_number_id or from_number is required; send either one. - `is_test` (boolean, optional, default false) - `lead_id` (string or null, optional) - `lead_source_id` (string or null, optional) - `lead_source_lead_id` (string or null, optional) - `metadata` (object, optional): Free-form key and value pairs. - `owned_line_of_business` (string or null, max 32, optional) - `retry_config` (object or null, optional) - `delay_minutes` (integer, 1–1440, optional, default 30) - `max_attempts` (integer, 1–10, optional, default 3) - `retry_on` (array of string, optional) - `scheduling` (object or null, optional) - `respect_tcpa_windows` (boolean, optional, default true) - `scheduled_at` (string (date-time) or null, optional) - `timezone` (string or null, max 64, optional) - `target_line_of_business` (string or null, max 32, optional) - `to_number` (string, 2–20, required) - `variables` (object, optional) - `webhook_events` (array of string, optional) - `webhook_url` (string or null, max 2048, optional) ## Returns **201 Created**: Successful Response - `agent_id` (string, Always present) - `created_at` (string (date-time), Always present) - `from_number` (string, Always present) - `id` (string, Always present) - `scheduled_at` (string (date-time) or null, May be absent) - `status` (string, Always present) - `to_number` (string, Always present) ## Errors - 400 `AGENT_NOT_ACTIVE`: The AI voice agent is not active. Next step: Retrying will fail the same way. Fix the request, or contact us. - 400 `DIAL_BLOCKED`: The call cannot be placed now. details.reason says why. Retry later for outside_calling_hours, outside_transfer_hours_flag_off, org_holiday, the tcpa_* window reasons and same_phone_inflight: at details.next_attempt_local when present, otherwise when your agency's calling hours reopen, or after the current call to that number ends. Do not retry for org_calling_hours_invalid, org_invalid_timezone, tcpa_missing_timezone, tcpa_invalid_timezone or a cross-sell reason: fix your agency settings or the lead first. Next step: Retry after the time in details.next_attempt_local when present. Otherwise retry when the blocking condition ends, as the meaning says. - 400 `DNC_BLOCKED`: The phone is on the Do Not Call list. No lead was created. Next step: Retrying will fail the same way. Fix the request, or contact us. - 400 `FROM_NUMBER_NOT_ACTIVE`: The from number is not active, so it cannot place a call. Next step: Retrying will fail the same way. Fix the request, or contact us. - 400 `FROM_NUMBER_NOT_FOUND`: from_number is not a phone number in your organization. Next step: Retrying will fail the same way. Fix the request, or contact us. - 400 `FROM_NUMBER_QUARANTINED`: The from number is quarantined. Use another number. Next step: Retrying will fail the same way. Fix the request, or contact us. - 400 `LEAD_REFERENCE_MISMATCH`: lead_id or lead_source_id does not belong to the enrollment named in the request. Next step: Retrying will fail the same way. Fix the request, or contact us. - 400 `MUTED_TURN_HOLD`: A recent call to this number has an unreviewed muted turn pending compliance review. Retry after the hold resolves. Next step: Retry after the time in details.next_attempt_local when present. Otherwise retry when the blocking condition ends, as the meaning says. - 402 `CALL_QUOTA_EXCEEDED`: Your plan's included calls are used up. Enable extra calls in Billing. Next step: Retrying will fail the same way. Fix the request, or contact us. - 403 `CALLS_NOT_ALLOWED_ON_BOUND_KEY`: A partner key called POST /calls. Next step: Retrying will fail the same way. Fix the request, or contact us. - 404 `LEAD_NOT_FOUND`: No lead with that id in your organization. Next step: Retrying will fail the same way. Fix the request, or contact us. - 404 `LEAD_SOURCE_LEAD_NOT_FOUND`: lead_source_lead_id is not a lead in one of your campaigns. Next step: Retrying will fail the same way. Fix the request, or contact us. - 404 `LEAD_SOURCE_NOT_FOUND`: lead_source_id is not a campaign in your organization. Next step: Retrying will fail the same way. Fix the request, or contact us. - 404 `ORGANIZATION_NOT_FOUND`: The organization on this account was not found. Contact us. Next step: Retrying will fail the same way. Fix the request, or contact us. - 404 `PHONE_NUMBER_NOT_FOUND`: No phone number with that id in your organization. Next step: Retrying will fail the same way. Fix the request, or contact us. - 404 `VOICE_AGENT_NOT_FOUND`: No AI voice agent with that id in your organization. Next step: Retrying will fail the same way. Fix the request, or contact us. - 409 `IDEMPOTENCY_IN_PROGRESS`: A request with this Idempotency-Key is still being processed. Next step: Safe to retry after Retry-After when present, otherwise back off. On a POST, resend the same Idempotency-Key and body. - 409 `IDEMPOTENCY_KEY_REUSED`: The same Idempotency-Key and path came with a different body. Next step: Retrying will fail the same way. Fix the request, or contact us. - 422 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. - 422 `LEAD_IS_TEST`: The lead is a test lead, so it cannot be called. Next step: Retrying will fail the same way. Fix the request, or contact us. - 422 `LEAD_SCREENED_OUT`: The lead check blocked this lead, so no call was placed. Next step: Retrying will fail the same way. Fix the request, or contact us. - 429 `AI_MINUTES_EXHAUSTED`: The monthly AI minutes limit is reached. Unlike RATE_LIMIT_EXCEEDED, this 429 has no Retry-After and will not clear until the plan's minutes reset. Upgrade the plan or wait. Next step: Retrying will fail the same way. Fix the request, or contact us. - 502 `UPSTREAM_ERROR`: Billing is not set up for your account, so the call was not placed. Contact us. Next step: Retrying will fail the same way. Fix the request, or contact us. Any request can also return `AUTHENTICATION_REQUIRED`, `TOKEN_INVALID`, `API_KEY_EXPIRED`, `RATE_LIMIT_EXCEEDED` or `INTERNAL_ERROR`. ## Request samples cURL: ```bash curl -X POST "https://api.entrovox.com/v1/calls" \ -H "Authorization: ApiKey $ENTROVOX_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "to_number": "+15555550100", "agent_id": "AGENT_ID", "from_number": "+15555550142" }' ``` Python: ```python import os, uuid, requests r = requests.post( "https://api.entrovox.com/v1/calls", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "to_number": "+15555550100", "agent_id": "AGENT_ID", "from_number": "+15555550142", }, ) print(r.status_code, r.json()) ``` Node.js: ```javascript import { randomUUID } from "node:crypto"; const res = await fetch("https://api.entrovox.com/v1/calls", { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, "Idempotency-Key": randomUUID(), "Content-Type": "application/json", }, body: JSON.stringify({ "to_number": "+15555550100", "agent_id": "AGENT_ID", "from_number": "+15555550142" }), }); console.log(res.status, await res.json()); ``` ## Response examples 201 Created: ```json { "data": { "agent_id": "AGENT_ID", "created_at": "2026-01-15T17:30:00Z", "from_number": "+15555550142", "id": "CALL_ID", "scheduled_at": null, "status": "active", "to_number": "+15555550100" } } ``` 422 Unprocessable Entity: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed.", "details": { "errors": [ { "type": "missing", "loc": [ "body", "to_number" ], "msg": "Field required", "input": {} } ] }, "param": "to_number", "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` --- # Retrieve a call `GET /v1/calls/{call_id}` Get a single call's status, disposition, and details. ## Headers - `Authorization` (string, required): `ApiKey $ENTROVOX_KEY`. Keys are issued per organization. ## Path parameters - `call_id` (string, required) ## Returns **200 OK**: Successful Response - `agent_id` (string or null, May be absent) - `agent_overrides` (object or null, May be absent): Free-form key and value pairs. - `ai_disclosure_delivered` (boolean or null, May be absent, default false) - `ai_latency_p50_ms` (integer or null, May be absent) - `ai_latency_p95_ms` (integer or null, May be absent) - `ai_talk_seconds` (integer or null, May be absent) - `analysis_status` (string or null, May be absent) - `answered_at` (string (date-time) or null, May be absent) - `attempt_number` (integer, May be absent, default 1) - `call_outcome` (string or null, May be absent) - `call_summary` (string or null, May be absent) - `created_at` (string (date-time) or null, May be absent) - `direction` (string, Always present) - `disconnect_reason` (string or null, May be absent) - `disposition` (string or null, May be absent) - `duration_seconds` (integer or null, May be absent) - `ended_at` (string (date-time) or null, May be absent) - `forward_answered` (boolean or null, May be absent) - `forwarded_to_number` (string or null, May be absent) - `from_number` (string, Always present) - `had_dead_air` (boolean or null, May be absent, default false) - `human_recording_suppressed` (boolean, May be absent, default false) - `human_talk_seconds` (integer or null, May be absent) - `id` (string, Always present) - `initiated_at` (string (date-time) or null, May be absent) - `is_short_drop` (boolean or null, May be absent, default false) - `is_test` (boolean, May be absent, default false) - `language` (string, May be absent, default en) - `lead_id` (string or null, May be absent) - `lead_name` (string or null, May be absent) - `lead_source_id` (string or null, May be absent) - `lead_source_lead_id` (string or null, May be absent) - `lead_source_name` (string or null, May be absent) - `lead_source_type` (string or null, May be absent) - `metadata` (object or null, May be absent): Free-form key and value pairs. - `organization_id` (string, Always present) - `origin` (object or null, May be absent): Free-form key and value pairs. - `qualification_data` (object or null, May be absent): Free-form key and value pairs. - `qualification_score` (number or null, May be absent) - `recording_disclosed` (boolean or null, May be absent, default false) - `recording_duration_seconds` (integer or null, May be absent) - `retry_config` (object or null, May be absent): Free-form key and value pairs. - `routing_mode` (string or null, May be absent) - `scheduled_at` (string (date-time) or null, May be absent) - `scheduling` (object or null, May be absent): Free-form key and value pairs. - `screener_detected` (boolean or null, May be absent, default false) - `screener_result` (string or null, May be absent) - `sequence_step` (integer or null, May be absent) - `started_at` (string (date-time) or null, May be absent) - `status` (string, Always present) - `talk_time_seconds` (integer or null, May be absent) - `to_number` (string, Always present) - `transcript` (string or null, May be absent) - `transcript_json` (array, object or null, May be absent) - `transfer_context` (object or null, May be absent): Free-form key and value pairs. - `updated_at` (string (date-time) or null, May be absent) - `variables` (object or null, May be absent): Free-form key and value pairs. - `voicemail_clip_used` (boolean or null, May be absent) - `wait_hold_seconds` (integer or null, May be absent) - `wait_ring_seconds` (integer or null, May be absent) - `wait_seconds` (integer or null, May be absent) - `webhook_events` (array of string or null, May be absent) - `webhook_url` (string or null, May be absent) - `why_detail` (string or null, May be absent) - `why_short` (string or null, May be absent) ## Errors - 404 `CALL_NOT_FOUND`: No call with that id in your organization. Next step: Retrying will fail the same way. Fix the request, or contact us. - 422 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. Any request can also return `AUTHENTICATION_REQUIRED`, `TOKEN_INVALID`, `API_KEY_EXPIRED`, `RATE_LIMIT_EXCEEDED` or `INTERNAL_ERROR`. ## Request samples cURL: ```bash curl -X GET "https://api.entrovox.com/v1/calls/CALL_ID" \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` Python: ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/calls/CALL_ID", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", }, ) print(r.status_code, r.json()) ``` Node.js: ```javascript const res = await fetch("https://api.entrovox.com/v1/calls/CALL_ID", { method: "GET", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, }, }); console.log(res.status, await res.json()); ``` ## Response examples 200 OK: ```json { "data": { "agent_id": null, "agent_overrides": {}, "ai_disclosure_delivered": false, "ai_latency_p50_ms": null, "ai_latency_p95_ms": null, "ai_talk_seconds": null, "analysis_status": null, "answered_at": null, "attempt_number": 1, "call_outcome": null, "call_summary": null, "created_at": null, "direction": "string", "disconnect_reason": null, "disposition": null, "duration_seconds": null, "ended_at": null, "forward_answered": null, "forwarded_to_number": null, "from_number": "+15555550142", "had_dead_air": false, "human_recording_suppressed": false, "human_talk_seconds": null, "id": "CALL_ID", "initiated_at": null, "is_short_drop": false, "is_test": false, "language": "en", "lead_id": null, "lead_name": null, "lead_source_id": null, "lead_source_lead_id": null, "lead_source_name": null, "lead_source_type": null, "metadata": {}, "organization_id": "ORGANIZATION_ID", "origin": {}, "qualification_data": {}, "qualification_score": null, "recording_disclosed": false, "recording_duration_seconds": null, "retry_config": {}, "routing_mode": null, "scheduled_at": null, "scheduling": {}, "screener_detected": false, "screener_result": null, "sequence_step": null, "started_at": null, "status": "active", "talk_time_seconds": null, "to_number": "+15555550100", "transcript": null, "transcript_json": null, "transfer_context": {}, "updated_at": null, "variables": {}, "voicemail_clip_used": null, "wait_hold_seconds": null, "wait_ring_seconds": null, "wait_seconds": null, "webhook_events": null, "webhook_url": null, "why_detail": null, "why_short": null } } ``` 422 Unprocessable Entity: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed.", "details": { "errors": [ { "type": "missing", "loc": [ "body" ], "msg": "Field required", "input": {} } ] }, "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` --- # List calls `GET /v1/calls` List calls, newest first. Filter by lead source, status, disposition, outcome, direction, date range, and duration. ## Headers - `Authorization` (string, required): `ApiKey $ENTROVOX_KEY`. Keys are issued per organization. ## Query parameters - `lead_source_id` (string or null, optional) - `lead_id` (string or null, optional) - `direction` (string or null, optional) - `disposition` (string or null, optional) - `call_outcome` (string or null, optional) - `routing_mode` (string or null, optional, one of agent, forward): Filter by inbound call routing mode: 'agent' or 'forward'. - `date_from` (string or null, optional) - `date_to` (string or null, optional) - `min_duration` (integer or null, min 0, optional) - `max_duration` (integer or null, min 0, optional) - `outcome_group` (string or null, optional): Filter by call group: conversations | transferred | callbacks_in | voicemails | all. Expands to a set of call_outcome values; 'all'/unknown applies no outcome filter. Omit for the classic single-outcome behavior. - `q` (string or null, max 256, optional): Search across calls: matches the lead's name, the call id, and — when the term contains digits — the digit-stripped from/to numbers, over the full filtered set. Selects the offset-paged path. - `sort_by` (string or null, optional, one of when, duration, lead): Sort column: when=initiated_at, duration=duration_seconds, lead=the displayed lead-name-else-number. Selects the offset-paged path; default 'when'. - `sort_dir` (string or null, optional, one of asc, desc): Sort direction for sort_by (default desc). Selects the offset-paged path. - `offset` (integer or null, 0–1000000, optional): Offset paging. Any of q/sort_by/sort_dir/offset selects the offset-paged path: meta.next_cursor is null and paging is offset+limit against meta.total. Omit all four for the classic cursor path. - `cursor` (string or null, optional): Classic cursor paging. Ignored whenever any of q/sort_by/sort_dir/offset is present (the offset-paged path takes precedence). - `limit` (integer, 1–200, optional, default 50) ## Returns **200 OK**: Successful Response - `data` (array of object, Always present) - `ai_talk_seconds` (integer or null, May be absent) - `answered_at` (string (date-time) or null, May be absent) - `attempt_number` (integer or null, May be absent) - `call_outcome` (string or null, May be absent) - `direction` (string, Always present) - `disconnect_reason` (string or null, May be absent) - `disposition` (string or null, May be absent) - `duration_seconds` (integer or null, May be absent) - `ended_at` (string (date-time) or null, May be absent) - `forwarded_to_number` (string or null, May be absent) - `from_number` (string, Always present) - `human_talk_seconds` (integer or null, May be absent) - `id` (string, Always present) - `initiated_at` (string (date-time) or null, May be absent) - `is_gtm_demo` (boolean, May be absent, default false) - `is_test` (boolean, May be absent, default false) - `language` (string, May be absent, default en) - `lead_id` (string or null, May be absent) - `lead_name` (string or null, May be absent) - `lead_source_id` (string or null, May be absent) - `lead_source_name` (string or null, May be absent) - `lead_source_type` (string or null, May be absent) - `routing_mode` (string or null, May be absent) - `screener_detected` (boolean, May be absent, default false) - `screener_result` (string or null, May be absent) - `sequence_step` (integer or null, May be absent) - `status` (string, Always present) - `summary_short` (string or null, May be absent) - `to_number` (string, Always present) - `wait_hold_seconds` (integer or null, May be absent) - `wait_ring_seconds` (integer or null, May be absent) - `wait_seconds` (integer or null, May be absent) - `why_short` (string or null, May be absent) - `meta` (object, Always present) - `has_more` (boolean, Always present) - `limit` (integer, Always present) - `next_cursor` (string or null, May be absent) - `total` (integer, Always present) ## Errors - 403 `LEAD_SOURCE_NOT_ALLOWED`: The body names a campaign other than the one this key is bound to. Next step: Retrying will fail the same way. Fix the request, or contact us. - 422 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. Any request can also return `AUTHENTICATION_REQUIRED`, `TOKEN_INVALID`, `API_KEY_EXPIRED`, `RATE_LIMIT_EXCEEDED` or `INTERNAL_ERROR`. ## Request samples cURL: ```bash curl -X GET "https://api.entrovox.com/v1/calls?limit=25" \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` Python: ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/calls", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", }, params={ "limit": 25, }, ) print(r.status_code, r.json()) ``` Node.js: ```javascript const res = await fetch("https://api.entrovox.com/v1/calls?limit=25", { method: "GET", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, }, }); console.log(res.status, await res.json()); ``` ## Response examples 200 OK: ```json { "data": [ { "ai_talk_seconds": null, "answered_at": null, "attempt_number": null, "call_outcome": null, "direction": "string", "disconnect_reason": null, "disposition": null, "duration_seconds": null, "ended_at": null, "forwarded_to_number": null, "from_number": "+15555550142", "human_talk_seconds": null, "id": "CALL_ID", "initiated_at": null, "is_gtm_demo": false, "is_test": false, "language": "en", "lead_id": null, "lead_name": null, "lead_source_id": null, "lead_source_name": null, "lead_source_type": null, "routing_mode": null, "screener_detected": false, "screener_result": null, "sequence_step": null, "status": "active", "summary_short": null, "to_number": "+15555550100", "wait_hold_seconds": null, "wait_ring_seconds": null, "wait_seconds": null, "why_short": null } ], "meta": { "has_more": false, "limit": 25, "next_cursor": null, "total": 1 } } ``` 422 Unprocessable Entity: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed.", "details": { "errors": [ { "type": "string_pattern_mismatch", "loc": [ "query", "routing_mode" ], "msg": "String should match pattern '^(agent|forward)$'", "input": "bad", "ctx": { "pattern": "^(agent|forward)$" } } ] }, "param": "routing_mode", "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` --- # Retrieve call statistics `GET /v1/calls/stats` Aggregate call statistics (total, connected, transfers, average durations, screener), computed over the full filtered set. Accepts the same filters as `GET /v1/calls`, so the figures agree with the list. ## Headers - `Authorization` (string, required): `ApiKey $ENTROVOX_KEY`. Keys are issued per organization. ## Query parameters - `lead_source_id` (string or null, optional) - `lead_id` (string or null, optional) - `direction` (string or null, optional) - `disposition` (string or null, optional) - `call_outcome` (string or null, optional) - `routing_mode` (string or null, optional, one of agent, forward): Filter by inbound call routing mode: 'agent' or 'forward'. - `date_from` (string or null, optional) - `date_to` (string or null, optional) - `min_duration` (integer or null, min 0, optional) - `max_duration` (integer or null, min 0, optional) ## Returns **200 OK**: Successful Response - `avg_duration_seconds` (number, May be absent, default 0) - `avg_transfer_duration_seconds` (number, May be absent, default 0) - `connected` (integer, May be absent, default 0) - `screener_blocked` (integer, May be absent, default 0) - `screener_passed` (integer, May be absent, default 0) - `total` (integer, May be absent, default 0) - `transfers` (integer, May be absent, default 0) ## Errors - 422 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. Any request can also return `AUTHENTICATION_REQUIRED`, `TOKEN_INVALID`, `API_KEY_EXPIRED`, `RATE_LIMIT_EXCEEDED` or `INTERNAL_ERROR`. ## Request samples cURL: ```bash curl -X GET "https://api.entrovox.com/v1/calls/stats" \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` Python: ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/calls/stats", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", }, ) print(r.status_code, r.json()) ``` Node.js: ```javascript const res = await fetch("https://api.entrovox.com/v1/calls/stats", { method: "GET", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, }, }); console.log(res.status, await res.json()); ``` ## Response examples 200 OK: ```json { "data": { "avg_duration_seconds": 0, "avg_transfer_duration_seconds": 0, "connected": 0, "screener_blocked": 0, "screener_passed": 0, "total": 0, "transfers": 0 } } ``` 422 Unprocessable Entity: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed.", "details": { "errors": [ { "type": "string_pattern_mismatch", "loc": [ "query", "routing_mode" ], "msg": "String should match pattern '^(agent|forward)$'", "input": "bad", "ctx": { "pattern": "^(agent|forward)$" } } ] }, "param": "routing_mode", "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` --- # Retrieve a call analysis `GET /v1/calls/{call_id}/analysis` Get the post-call AI analysis (summary and outcome) for a call. ## Headers - `Authorization` (string, required): `ApiKey $ENTROVOX_KEY`. Keys are issued per organization. ## Path parameters - `call_id` (string, required) ## Returns **200 OK**: Successful Response - `analysis_duration_ms` (integer or null, May be absent) - `call_id` (string, Always present) - `call_outcome` (string, Always present) - `call_summary` (string or null, May be absent) - `callback_action_taken` (boolean, May be absent, default false) - `callback_datetime` (string (date-time) or null, May be absent) - `callback_detected` (boolean, May be absent, default false) - `callback_notes` (string or null, May be absent) - `competitors_mentioned` (array of string, May be absent) - `created_at` (string (date-time), Always present) - `dnc_action_taken` (boolean, May be absent, default false) - `dnc_detected` (boolean, May be absent, default false) - `dnc_phrases` (array of string, May be absent) - `error_message` (string or null, May be absent) - `extracted_data` (object, May be absent): Free-form key and value pairs. - `follow_up_actions` (array of string, May be absent) - `id` (string, Always present) - `model_used` (string or null, May be absent) - `not_available_detected` (boolean, May be absent, default false) - `not_available_who` (string or null, May be absent) - `objections` (array of object, May be absent) - `agent_response` (string or null, May be absent) - `phrase` (string, Always present) - `type` (string, Always present) - `organization_id` (string, Always present) - `outcome_confidence` (number or null, May be absent) - `outcome_reasoning` (string or null, May be absent) - `overall_sentiment` (string or null, May be absent) - `prompt_version` (string or null, May be absent) - `sentiment_score` (number or null, May be absent) - `token_count` (integer or null, May be absent) - `updated_at` (string (date-time), Always present) - `wrong_number_action_taken` (boolean, May be absent, default false) - `wrong_number_detected` (boolean, May be absent, default false) ## Errors - 404 `CALL_ANALYSIS_NOT_FOUND`: The call exists but its analysis is not written yet. It is pending until call.analysis.completed, or until analysis_status is completed. Next step: Retry after the time in details.next_attempt_local when present. Otherwise retry when the blocking condition ends, as the meaning says. - 404 `CALL_NOT_FOUND`: No call with that id in your organization. Next step: Retrying will fail the same way. Fix the request, or contact us. - 422 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. Any request can also return `AUTHENTICATION_REQUIRED`, `TOKEN_INVALID`, `API_KEY_EXPIRED`, `RATE_LIMIT_EXCEEDED` or `INTERNAL_ERROR`. ## Request samples cURL: ```bash curl -X GET "https://api.entrovox.com/v1/calls/CALL_ID/analysis" \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` Python: ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/calls/CALL_ID/analysis", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", }, ) print(r.status_code, r.json()) ``` Node.js: ```javascript const res = await fetch("https://api.entrovox.com/v1/calls/CALL_ID/analysis", { method: "GET", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, }, }); console.log(res.status, await res.json()); ``` ## Response examples 200 OK: ```json { "data": { "analysis_duration_ms": null, "call_id": "CALL_ID", "call_outcome": "string", "call_summary": null, "callback_action_taken": false, "callback_datetime": null, "callback_detected": false, "callback_notes": null, "competitors_mentioned": [ "string" ], "created_at": "2026-01-15T17:30:00Z", "dnc_action_taken": false, "dnc_detected": false, "dnc_phrases": [ "string" ], "error_message": null, "extracted_data": {}, "follow_up_actions": [ "string" ], "id": "CALL_ID", "model_used": null, "not_available_detected": false, "not_available_who": null, "objections": [ { "agent_response": null, "phrase": "string", "type": "string" } ], "organization_id": "ORGANIZATION_ID", "outcome_confidence": null, "outcome_reasoning": null, "overall_sentiment": null, "prompt_version": null, "sentiment_score": null, "token_count": null, "updated_at": "2026-01-15T17:30:00Z", "wrong_number_action_taken": false, "wrong_number_detected": false } } ``` 422 Unprocessable Entity: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed.", "details": { "errors": [ { "type": "missing", "loc": [ "body" ], "msg": "Field required", "input": {} } ] }, "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` --- # Retrieve a call transcript `GET /v1/calls/{call_id}/transcript` Get the full transcript for a call. ## Headers - `Authorization` (string, required): `ApiKey $ENTROVOX_KEY`. Keys are issued per organization. ## Path parameters - `call_id` (string, required) ## Returns **200 OK**: Successful Response - `call_id` (string, Always present) - `transcript` (array of object, Always present) - `duration_ms` (integer or null, May be absent) - `speaker` (string, Always present) - `started_at` (string (date-time) or null, May be absent) - `text` (string, Always present) - `word_count` (integer or null, May be absent) ## Errors - 404 `CALL_NOT_FOUND`: No call with that id in your organization. Next step: Retrying will fail the same way. Fix the request, or contact us. - 422 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. Any request can also return `AUTHENTICATION_REQUIRED`, `TOKEN_INVALID`, `API_KEY_EXPIRED`, `RATE_LIMIT_EXCEEDED` or `INTERNAL_ERROR`. ## Request samples cURL: ```bash curl -X GET "https://api.entrovox.com/v1/calls/CALL_ID/transcript" \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` Python: ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/calls/CALL_ID/transcript", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", }, ) print(r.status_code, r.json()) ``` Node.js: ```javascript const res = await fetch("https://api.entrovox.com/v1/calls/CALL_ID/transcript", { method: "GET", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, }, }); console.log(res.status, await res.json()); ``` ## Response examples 200 OK: ```json { "data": { "call_id": "CALL_ID", "transcript": [ { "duration_ms": null, "speaker": "string", "started_at": null, "text": "string" } ], "word_count": null } } ``` 422 Unprocessable Entity: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed.", "details": { "errors": [ { "type": "missing", "loc": [ "body" ], "msg": "Field required", "input": {} } ] }, "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` --- # Retrieve a call recording URL `GET /v1/calls/{call_id}/recording-url` Generate a signed URL for the call recording. Returns a short-lived (1 hour) signed URL for the recording's audio file. With no `format` the response is exactly `{"url": ...}`. `format=m4a` serves an AAC copy that Apple devices can play, made on demand; the response then also carries `format`. `503 RECORDING_TRANSCODE_FAILED` (retryable, the original recording is still available) means the copy could not be made. If there is no file to serve, `404 RECORDING_NOT_FOUND` means the call has no recording and retrying will not help. `404 RECORDING_NOT_READY` means a recording is still being processed: retry after `Retry-After`; partner subscriptions can also wait for `call.recording.ready` once webhook delivery is live. `503 RECORDING_UNAVAILABLE` is a temporary failure: retry after `Retry-After`. ## Headers - `Authorization` (string, required): `ApiKey $ENTROVOX_KEY`. Keys are issued per organization. ## Path parameters - `call_id` (string, required) ## Query parameters - `format` (string or null, optional, one of ogg, m4a): `ogg` (the default, and what every client that omits this gets) or `m4a` (AAC in MP4, for iOS). The response names the format actually served; an `m4a` request is answered with `ogg` for a recording over the size cap. ## Returns **200 OK**: Successful Response - `format` (string, May be absent, one of ogg, m4a): The format actually served. Present only when the request named a format; an m4a request for a recording over the size cap is answered with ogg. - `url` (string, Always present): Signed URL for the audio file. It expires after 1 hour. ## Errors - 404 `CALL_NOT_FOUND`: No call with that id in your organization. Next step: Retrying will fail the same way. Fix the request, or contact us. - 404 `RECORDING_NOT_FOUND`: The call has no recording, or its file is missing. Next step: Retrying will fail the same way. Fix the request, or contact us. - 404 `RECORDING_NOT_READY`: The call has a recording that is still being processed. Retry after Retry-After, or wait for call.recording.ready (partner subscriptions, once webhook delivery is live). Next step: Retry after the time in details.next_attempt_local when present. Otherwise retry when the blocking condition ends, as the meaning says. - 422 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. - 503 `RECORDING_TRANSCODE_FAILED`: The recording could not be prepared as m4a. Retry after Retry-After, or use the Ogg recording. Next step: Safe to retry after Retry-After when present, otherwise back off. On a POST, resend the same Idempotency-Key and body. - 503 `RECORDING_UNAVAILABLE`: The recording exists but a signed link could not be made right now. Retry after Retry-After. Next step: Safe to retry after Retry-After when present, otherwise back off. On a POST, resend the same Idempotency-Key and body. Any request can also return `AUTHENTICATION_REQUIRED`, `TOKEN_INVALID`, `API_KEY_EXPIRED`, `RATE_LIMIT_EXCEEDED` or `INTERNAL_ERROR`. ## Request samples cURL: ```bash curl -X GET "https://api.entrovox.com/v1/calls/CALL_ID/recording-url" \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` Python: ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/calls/CALL_ID/recording-url", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", }, ) print(r.status_code, r.json()) ``` Node.js: ```javascript const res = await fetch("https://api.entrovox.com/v1/calls/CALL_ID/recording-url", { method: "GET", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, }, }); console.log(res.status, await res.json()); ``` ## Response examples 200 OK: ```json { "data": { "format": "ogg", "url": "string" } } ``` 422 Unprocessable Entity: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed.", "details": { "errors": [ { "type": "literal_error", "loc": [ "query", "format" ], "msg": "Input should be 'ogg' or 'm4a'", "input": "bad", "ctx": { "expected": "'ogg' or 'm4a'" } } ] }, "param": "format", "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` --- # List phone numbers `GET /v1/phone-numbers` List your phone numbers. Use a number's `id` as the `from_number_id` (the caller ID) when initiating a call. ## Headers - `Authorization` (string, required): `ApiKey $ENTROVOX_KEY`. Keys are issued per organization. ## Query parameters - `status` (string or null, optional) - `page` (integer, min 1, optional, default 1) - `page_size` (integer, 1–100, optional, default 25) ## Returns **200 OK**: Successful Response - `data` (array of object, Always present) - `caller_id_name` (string or null, Always present) - `capabilities` (array of string, Always present) - `cooldown_entered_at` (string or null, May be absent) - `cooldown_source` (string or null, May be absent, one of hiya, behavioral) - `country_code` (string, Always present) - `created_at` (string, Always present) - `forwarding_announcement` (string or null, Always present) - `forwarding_phone` (string or null, Always present) - `forwarding_use_org_default` (boolean, May be absent, default false) - `friendly_name` (string or null, Always present) - `hiya_reputation` (object or null, May be absent) - `checked_at` (string or null, May be absent) - `last_attempt_at` (string or null, May be absent) - `last_error` (string or null, May be absent): The provider's last error message, if any. - `registration` (object, May be absent) - `error` (string or null, May be absent): The provider's last error message, if any. - `queued_at` (string or null, May be absent) - `state` (string, May be absent, one of queued, verified, failed, default queued) - `verified_at` (string or null, May be absent) - `reputation` (object, May be absent) - `category` (string or null, May be absent, one of spam, fraud) - `metrics` (object, May be absent) - `desirability` (string or null, May be absent, one of good, normal, poor, very_poor) - `engagement` (string or null, May be absent, one of good, normal, poor, very_poor) - `maturity` (string or null, May be absent, one of good, normal, poor, very_poor) - `reaction` (string or null, May be absent, one of good, normal, poor, very_poor) - `spam_status` (string or null, May be absent, one of unflagged, mixed_low, mixed_high, flagged) - `source` (string, May be absent, default hiya) - `id` (string, Always present) - `inbound_after_hours_ai_enabled` (boolean, May be absent, default false) - `inbound_agent_id` (string or null, Always present) - `inbound_routing_mode` (string, Always present, one of agent, forward) - `inbound_transfer_phone` (string or null, Always present) - `inbound_transfer_use_org_default` (boolean, May be absent, default false) - `monthly_cost_cents` (integer or null, Always present) - `number_type` (string or null, Always present) - `organization_id` (string, Always present) - `outbound_agent_id` (string or null, Always present) - `outbound_quarantined` (boolean, May be absent, default false) - `phone_number` (string, Always present) - `pool_id` (string or null, May be absent) - `pool_name` (string or null, May be absent) - `pool_stage` (string, May be absent, one of onboarding, onboarding_failed, reserve, dialing, quarantine, releasing, default dialing) - `provider` (string, May be absent, one of telnyx, twilio, vonage, default telnyx) - `quarantine_confidence` (number or null, May be absent) - `quarantine_reason` (string or null, May be absent) - `quarantine_source` (string or null, May be absent, one of hiya, behavioral, manual, autopilot) - `quarantined_at` (string or null, May be absent) - `ready_at` (string or null, May be absent) - `release_after` (string or null, May be absent) - `reputation_level` (string or null, Always present) - `reputation_score` (integer or null, Always present) - `reputation_state` (string, May be absent, one of clean, cooldown, default clean) - `show_logo_on_outbound` (boolean, May be absent, default false) - `show_logo_opt_out` (boolean, May be absent, default false) - `source` (string, Always present) - `spanish_transfer_phone` (string or null, May be absent) - `status` (string, Always present) - `updated_at` (string, Always present) - `verified` (boolean, Always present) - `meta` (object, Always present) - `page` (integer, Always present) - `per_page` (integer, Always present) - `total` (integer, Always present) - `total_pages` (integer, Always present) ## Errors - 422 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. Any request can also return `AUTHENTICATION_REQUIRED`, `TOKEN_INVALID`, `API_KEY_EXPIRED`, `RATE_LIMIT_EXCEEDED` or `INTERNAL_ERROR`. ## Request samples cURL: ```bash curl -X GET "https://api.entrovox.com/v1/phone-numbers" \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` Python: ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/phone-numbers", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", }, ) print(r.status_code, r.json()) ``` Node.js: ```javascript const res = await fetch("https://api.entrovox.com/v1/phone-numbers", { method: "GET", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, }, }); console.log(res.status, await res.json()); ``` ## Response examples 200 OK: ```json { "data": [ { "caller_id_name": null, "capabilities": [ "voice" ], "cooldown_entered_at": null, "cooldown_source": "hiya", "country_code": "US", "created_at": "2026-01-15T17:30:00Z", "forwarding_announcement": null, "forwarding_phone": null, "forwarding_use_org_default": false, "friendly_name": null, "hiya_reputation": { "checked_at": null, "last_attempt_at": null, "last_error": null, "registration": { "error": null, "queued_at": null, "state": "queued", "verified_at": null }, "reputation": { "category": "spam", "metrics": { "desirability": "good", "engagement": "good", "maturity": "good", "reaction": "good" }, "spam_status": "unflagged" }, "source": "hiya" }, "id": "PHONE_NUMBER_ID", "inbound_after_hours_ai_enabled": false, "inbound_agent_id": null, "inbound_routing_mode": "agent", "inbound_transfer_phone": null, "inbound_transfer_use_org_default": false, "monthly_cost_cents": null, "number_type": null, "organization_id": "ORGANIZATION_ID", "outbound_agent_id": null, "outbound_quarantined": false, "phone_number": "+15555550142", "pool_id": null, "pool_name": null, "pool_stage": "onboarding", "provider": "telnyx", "quarantine_confidence": null, "quarantine_reason": null, "quarantine_source": "hiya", "quarantined_at": null, "ready_at": null, "release_after": null, "reputation_level": null, "reputation_score": null, "reputation_state": "clean", "show_logo_on_outbound": false, "show_logo_opt_out": false, "source": "purchased", "spanish_transfer_phone": null, "status": "active", "updated_at": "2026-01-15T17:30:00Z", "verified": false } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } ``` 422 Unprocessable Entity: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed.", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "abc" } ] }, "param": "page", "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` --- # Retrieve a phone number `GET /v1/phone-numbers/{phone_number_id}` Get one phone number by id. ## Headers - `Authorization` (string, required): `ApiKey $ENTROVOX_KEY`. Keys are issued per organization. ## Path parameters - `phone_number_id` (string, required) ## Returns **200 OK**: Successful Response - `caller_id_name` (string or null, Always present) - `capabilities` (array of string, Always present) - `cooldown_entered_at` (string or null, May be absent) - `cooldown_source` (string or null, May be absent, one of hiya, behavioral) - `country_code` (string, Always present) - `created_at` (string, Always present) - `forwarding_announcement` (string or null, Always present) - `forwarding_phone` (string or null, Always present) - `forwarding_use_org_default` (boolean, May be absent, default false) - `friendly_name` (string or null, Always present) - `hiya_reputation` (object or null, May be absent) - `checked_at` (string or null, May be absent) - `last_attempt_at` (string or null, May be absent) - `last_error` (string or null, May be absent): The provider's last error message, if any. - `registration` (object, May be absent) - `error` (string or null, May be absent): The provider's last error message, if any. - `queued_at` (string or null, May be absent) - `state` (string, May be absent, one of queued, verified, failed, default queued) - `verified_at` (string or null, May be absent) - `reputation` (object, May be absent) - `category` (string or null, May be absent, one of spam, fraud) - `metrics` (object, May be absent) - `desirability` (string or null, May be absent, one of good, normal, poor, very_poor) - `engagement` (string or null, May be absent, one of good, normal, poor, very_poor) - `maturity` (string or null, May be absent, one of good, normal, poor, very_poor) - `reaction` (string or null, May be absent, one of good, normal, poor, very_poor) - `spam_status` (string or null, May be absent, one of unflagged, mixed_low, mixed_high, flagged) - `source` (string, May be absent, default hiya) - `id` (string, Always present) - `inbound_after_hours_ai_enabled` (boolean, May be absent, default false) - `inbound_agent_id` (string or null, Always present) - `inbound_routing_mode` (string, Always present, one of agent, forward) - `inbound_transfer_phone` (string or null, Always present) - `inbound_transfer_use_org_default` (boolean, May be absent, default false) - `monthly_cost_cents` (integer or null, Always present) - `number_type` (string or null, Always present) - `organization_id` (string, Always present) - `outbound_agent_id` (string or null, Always present) - `outbound_quarantined` (boolean, May be absent, default false) - `phone_number` (string, Always present) - `pool_id` (string or null, May be absent) - `pool_name` (string or null, May be absent) - `pool_stage` (string, May be absent, one of onboarding, onboarding_failed, reserve, dialing, quarantine, releasing, default dialing) - `provider` (string, May be absent, one of telnyx, twilio, vonage, default telnyx) - `quarantine_confidence` (number or null, May be absent) - `quarantine_reason` (string or null, May be absent) - `quarantine_source` (string or null, May be absent, one of hiya, behavioral, manual, autopilot) - `quarantined_at` (string or null, May be absent) - `ready_at` (string or null, May be absent) - `release_after` (string or null, May be absent) - `reputation_level` (string or null, Always present) - `reputation_score` (integer or null, Always present) - `reputation_state` (string, May be absent, one of clean, cooldown, default clean) - `show_logo_on_outbound` (boolean, May be absent, default false) - `show_logo_opt_out` (boolean, May be absent, default false) - `source` (string, Always present) - `spanish_transfer_phone` (string or null, May be absent) - `status` (string, Always present) - `updated_at` (string, Always present) - `verified` (boolean, Always present) ## Errors - 404 `PHONE_NUMBER_NOT_FOUND`: No phone number with that id in your organization. Next step: Retrying will fail the same way. Fix the request, or contact us. - 422 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. Any request can also return `AUTHENTICATION_REQUIRED`, `TOKEN_INVALID`, `API_KEY_EXPIRED`, `RATE_LIMIT_EXCEEDED` or `INTERNAL_ERROR`. ## Request samples cURL: ```bash curl -X GET "https://api.entrovox.com/v1/phone-numbers/PHONE_NUMBER_ID" \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` Python: ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/phone-numbers/PHONE_NUMBER_ID", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", }, ) print(r.status_code, r.json()) ``` Node.js: ```javascript const res = await fetch("https://api.entrovox.com/v1/phone-numbers/PHONE_NUMBER_ID", { method: "GET", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, }, }); console.log(res.status, await res.json()); ``` ## Response examples 200 OK: ```json { "data": { "caller_id_name": null, "capabilities": [ "voice" ], "cooldown_entered_at": null, "cooldown_source": "hiya", "country_code": "US", "created_at": "2026-01-15T17:30:00Z", "forwarding_announcement": null, "forwarding_phone": null, "forwarding_use_org_default": false, "friendly_name": null, "hiya_reputation": { "checked_at": null, "last_attempt_at": null, "last_error": null, "registration": { "error": null, "queued_at": null, "state": "queued", "verified_at": null }, "reputation": { "category": "spam", "metrics": { "desirability": "good", "engagement": "good", "maturity": "good", "reaction": "good" }, "spam_status": "unflagged" }, "source": "hiya" }, "id": "PHONE_NUMBER_ID", "inbound_after_hours_ai_enabled": false, "inbound_agent_id": null, "inbound_routing_mode": "agent", "inbound_transfer_phone": null, "inbound_transfer_use_org_default": false, "monthly_cost_cents": null, "number_type": null, "organization_id": "ORGANIZATION_ID", "outbound_agent_id": null, "outbound_quarantined": false, "phone_number": "+15555550142", "pool_id": null, "pool_name": null, "pool_stage": "onboarding", "provider": "telnyx", "quarantine_confidence": null, "quarantine_reason": null, "quarantine_source": "hiya", "quarantined_at": null, "ready_at": null, "release_after": null, "reputation_level": null, "reputation_score": null, "reputation_state": "clean", "show_logo_on_outbound": false, "show_logo_opt_out": false, "source": "purchased", "spanish_transfer_phone": null, "status": "active", "updated_at": "2026-01-15T17:30:00Z", "verified": false } } ``` 422 Unprocessable Entity: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed.", "details": { "errors": [ { "type": "missing", "loc": [ "body" ], "msg": "Field required", "input": {} } ] }, "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` --- # List AI voice agents `GET /v1/voice-agents` List your AI voice agents. Use an agent's `id` as the `agent_id` when initiating a call. ## Headers - `Authorization` (string, required): `ApiKey $ENTROVOX_KEY`. Keys are issued per organization. ## Query parameters - `status` (string or null, optional) - `line_of_business` (string or null, optional) - `page` (integer, min 1, optional, default 1) - `per_page` (integer, 1–100, optional, default 50) ## Returns **200 OK**: Successful Response - `data` (array of object, Always present) - `created_at` (string (date-time), Always present) - `description` (string or null, May be absent) - `id` (string, Always present) - `is_builtin` (boolean, May be absent, default false) - `line_of_business` (string or null, May be absent) - `name` (string, Always present) - `objective` (string, May be absent, default lead_qualification) - `prompt_mode` (string or null, May be absent) - `status` (string or null, May be absent) - `voice_id` (string or null, May be absent) - `meta` (object, Always present) - `page` (integer, Always present) - `per_page` (integer, Always present) - `total` (integer, Always present) - `total_pages` (integer, Always present) ## Errors - 422 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. Any request can also return `AUTHENTICATION_REQUIRED`, `TOKEN_INVALID`, `API_KEY_EXPIRED`, `RATE_LIMIT_EXCEEDED` or `INTERNAL_ERROR`. ## Request samples cURL: ```bash curl -X GET "https://api.entrovox.com/v1/voice-agents" \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` Python: ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/voice-agents", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", }, ) print(r.status_code, r.json()) ``` Node.js: ```javascript const res = await fetch("https://api.entrovox.com/v1/voice-agents", { method: "GET", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, }, }); console.log(res.status, await res.json()); ``` ## Response examples 200 OK: ```json { "data": [ { "created_at": "2026-01-15T17:30:00Z", "description": null, "id": "AGENT_ID", "is_builtin": false, "line_of_business": null, "name": "string", "objective": "lead_qualification", "prompt_mode": null, "status": "active", "voice_id": null } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } ``` 422 Unprocessable Entity: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed.", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "abc" } ] }, "param": "page", "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` --- # Retrieve an AI voice agent `GET /v1/voice-agents/{agent_id}` Get one AI voice agent by id. ## Headers - `Authorization` (string, required): `ApiKey $ENTROVOX_KEY`. Keys are issued per organization. ## Path parameters - `agent_id` (string, required) ## Returns **200 OK**: Successful Response - `background_sound` (string, May be absent, default none) - `call_handling_instructions` (string or null, May be absent) - `call_objective` (string or null, May be absent) - `compliance_config` (object or null, May be absent): Free-form key and value pairs. - `created_at` (string (date-time), Always present) - `custom_system_prompt` (string or null, May be absent) - `description` (string or null, May be absent) - `expressive_mode` (boolean, May be absent, default false) - `flow_config` (object or null, May be absent): Free-form key and value pairs. - `id` (string, Always present) - `is_active` (boolean or null, May be absent) - `llm_model` (string or null, May be absent) - `llm_provider` (string or null, May be absent) - `name` (string, Always present) - `objective` (string, May be absent, default lead_qualification) - `opening_line` (string or null, May be absent) - `opening_line_es` (string or null, May be absent) - `opening_line_inbound` (string or null, May be absent) - `organization_id` (string or null, May be absent) - `parent_agent_id` (string or null, May be absent) - `persona` (string or null, May be absent) - `prompt_mode` (string, May be absent, default assembled) - `qualification_criteria` (object or null, May be absent): Free-form key and value pairs. - `runtime_config` (object or null, May be absent): Free-form key and value pairs. - `screener_response` (string or null, May be absent) - `spoken_agency_name` (string or null, May be absent) - `status` (string or null, May be absent) - `tool_policy` (object or null, May be absent): Free-form key and value pairs. - `updated_at` (string (date-time), Always present) - `voice_id` (string or null, May be absent) - `voicemail_message_template` (string or null, May be absent) - `voicemail_message_template_es` (string or null, May be absent) - `voicemail_mode` (string, May be absent, default drop) ## Errors - 404 `VOICE_AGENT_NOT_FOUND`: No AI voice agent with that id in your organization. Next step: Retrying will fail the same way. Fix the request, or contact us. - 422 `VALIDATION_ERROR`: A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. Next step: Retrying will fail the same way. Fix the request, or contact us. Any request can also return `AUTHENTICATION_REQUIRED`, `TOKEN_INVALID`, `API_KEY_EXPIRED`, `RATE_LIMIT_EXCEEDED` or `INTERNAL_ERROR`. ## Request samples cURL: ```bash curl -X GET "https://api.entrovox.com/v1/voice-agents/AGENT_ID" \ -H "Authorization: ApiKey $ENTROVOX_KEY" ``` Python: ```python import os, requests r = requests.get( "https://api.entrovox.com/v1/voice-agents/AGENT_ID", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", }, ) print(r.status_code, r.json()) ``` Node.js: ```javascript const res = await fetch("https://api.entrovox.com/v1/voice-agents/AGENT_ID", { method: "GET", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, }, }); console.log(res.status, await res.json()); ``` ## Response examples 200 OK: ```json { "data": { "background_sound": "none", "call_handling_instructions": null, "call_objective": null, "compliance_config": {}, "created_at": "2026-01-15T17:30:00Z", "custom_system_prompt": null, "description": null, "expressive_mode": false, "flow_config": {}, "id": "AGENT_ID", "is_active": null, "llm_model": null, "llm_provider": null, "name": "string", "objective": "lead_qualification", "opening_line": null, "opening_line_es": null, "opening_line_inbound": null, "organization_id": null, "parent_agent_id": null, "persona": null, "prompt_mode": "assembled", "qualification_criteria": {}, "runtime_config": {}, "screener_response": null, "spoken_agency_name": null, "status": "active", "tool_policy": {}, "updated_at": "2026-01-15T17:30:00Z", "voice_id": null, "voicemail_message_template": null, "voicemail_message_template_es": null, "voicemail_mode": "drop" } } ``` 422 Unprocessable Entity: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed.", "details": { "errors": [ { "type": "missing", "loc": [ "body" ], "msg": "Field required", "input": {} } ] }, "doc_url": "https://api.entrovox.com/developer/docs#validation-error", "request_id": "REQUEST_ID" } } ``` --- # Webhooks Signed events pushed to your URL as a lead and its calls move along, so you do not have to poll. > **Webhook delivery is a preview.** The contract below is what we are building to, but nothing is delivered yet. A `webhook_url` on a call is stored and never called, and the webhook routes answer an API key with `403 API_KEY_ENDPOINT_NOT_ALLOWED`. Poll each lead's [status URL](/developers/status-url) for outcomes. We will announce when delivery goes live. ## Overview We `POST` a JSON event to your URL. Every event has the same envelope: an `id` that stays the same across retries, a `type`, a `created_at` time, an `api_version` and a `data` object that depends on the type. There are two audiences. Partner subscriptions can receive all 10 events, with the fuller payloads. Agency integrations that set `webhook_url` on a call can subscribe to the `call.*` events except `call.recording.ready`, with leaner payloads; by default they get `call.started`, `call.completed`, `call.failed` and `call.transferred`. The guide [Webhooks](/developers/webhook-delivery) covers how to choose events. ## Event catalog Most events are provisional: a later event can change what an earlier one said. Write your records once, on the final event for your audience. A typical transferred lead: `lead.accepted` → `call.started` → `call.answered` → `call.transferred` → `call.completed` → `call.analysis.completed` → `call.recording.ready` Partners store the result at `call.recording.ready`. Agency `webhook_url` callbacks never get it, so `call.analysis.completed` is their last event once added to `webhook_events`. | Event | Fires when | What to do | Partner | Agency | |---|---|---|---|---| | `lead.accepted` | We enrolled the lead | Save the lead id and status URL | n/a | Not sent | | `call.started` | The outbound dial was placed | Optional for partners; on by default for agency callbacks | Provisional | Provisional | | `call.answered` | The lead picked up and the AI voice agent began the conversation | Optional. Off by default for partners; agency callbacks opt in with webhook_events | Provisional | Provisional | | `call.failed` | An accepted call could not complete | Optional for partners; on by default for agency callbacks | Provisional | Provisional | | `call.completed` | An attempt ended | Update the duration and disposition. Provisional | Provisional | Provisional | | `call.transferred` | A warm transfer to a licensed agent has a result | Record the transfer result: connected, no_answer, voicemail or failed | Transfer result | Transfer result | | `call.analysis.completed` | The AI summary and qualification are ready | Store the summary. Partners: media may still be pending. Agency callbacks opt in with webhook_events | Provisional (media_pending) | Final (opt-in) | | `call.recording.ready` | The recording and transcript can be fetched | Write the disposition and media to your system. Final for partners | Final | Not sent | | `callback.scheduled` | The lead asked to be called back | Show the appointment | n/a | Not sent | | `webhook.test` | You asked us to send a test event | Check your signature code, then ignore it | Ignore | Not sent | ## Events One section per event, with the payload we send. IDs and times in the examples are illustrative. ### lead.accepted Partner subscriptions only. Partner: n/a. Partner only. Entrovox enrolled the lead you posted. Persist `lead.id` and `status_url`. `data.lead` is the full Lead object (the example is abbreviated). Not final. `data` carries `external_id`, `lead`. Payload: ```json { "api_version": "2026-09-10", "created_at": "2026-09-10T18:06:01Z", "data": { "external_id": "crm-lead-42", "lead": { "id": "lead_01J8", "status_url": "https://api.entrovox.com/v1/leads/lead_01J8" } }, "id": "evt_01J8XYZ", "type": "lead.accepted" } ``` ### call.started Partner and agency. Provisional. The outbound dial was placed. Not final. Agency `webhook_url` callbacks carry `data` exactly as in the example; partner subscriptions add the fields listed in `x-partner-data`. Partner `data` carries `call`, `external_id`. Agency `data` carries `call`. Partner subscription: ```json { "api_version": "2026-09-10", "created_at": "2026-09-10T18:06:01Z", "data": { "call": { "agent_id": "agent_01J8", "answered_at": null, "direction": "outbound", "disposition": null, "duration_seconds": null, "ended_at": null, "from_number": "+15555550000", "id": "call_01J8", "metadata": { "crm_id": "lead-42" }, "status": "queued", "talk_time_seconds": null, "to_number": "+15555551234" }, "external_id": "crm-lead-42" }, "id": "evt_01J8XYZ", "type": "call.started" } ``` Agency webhook_url: ```json { "api_version": "2026-09-10", "created_at": "2026-09-10T18:06:01Z", "data": { "call": { "agent_id": "agent_01J8", "answered_at": null, "direction": "outbound", "disposition": null, "duration_seconds": null, "ended_at": null, "from_number": "+15555550000", "id": "call_01J8", "metadata": { "crm_id": "lead-42" }, "status": "queued", "talk_time_seconds": null, "to_number": "+15555551234" } }, "id": "evt_01J8XYZ", "type": "call.started" } ``` ### call.answered Partner and agency. Provisional. The lead picked up; the AI conversation began. Not final. Agency `webhook_url` callbacks carry `data` exactly as in the example; partner subscriptions add the fields listed in `x-partner-data`. Partner `data` carries `call`, `external_id`. Agency `data` carries `call`. Partner subscription: ```json { "api_version": "2026-09-10", "created_at": "2026-09-10T18:06:01Z", "data": { "call": { "agent_id": "agent_01J8", "answered_at": "2026-09-10T18:05:10Z", "direction": "outbound", "disposition": null, "duration_seconds": null, "ended_at": null, "from_number": "+15555550000", "id": "call_01J8", "metadata": { "crm_id": "lead-42" }, "status": "in_progress", "talk_time_seconds": null, "to_number": "+15555551234" }, "external_id": "crm-lead-42" }, "id": "evt_01J8XYZ", "type": "call.answered" } ``` Agency webhook_url: ```json { "api_version": "2026-09-10", "created_at": "2026-09-10T18:06:01Z", "data": { "call": { "agent_id": "agent_01J8", "answered_at": "2026-09-10T18:05:10Z", "direction": "outbound", "disposition": null, "duration_seconds": null, "ended_at": null, "from_number": "+15555550000", "id": "call_01J8", "metadata": { "crm_id": "lead-42" }, "status": "in_progress", "talk_time_seconds": null, "to_number": "+15555551234" } }, "id": "evt_01J8XYZ", "type": "call.answered" } ``` ### call.failed Partner and agency. Provisional. An accepted call could not complete (a scheduled call that fails at fire-time, or a provider error). Synchronous rejections like DNC/hours come back on the POST /calls response instead. Not final. Agency `webhook_url` callbacks carry `data` exactly as in the example; partner subscriptions add the fields listed in `x-partner-data`. Partner `data` carries `call`, `external_id`. Agency `data` carries `call`, `error`. Partner subscription: ```json { "api_version": "2026-09-10", "created_at": "2026-09-10T18:06:01Z", "data": { "call": { "agent_id": "agent_01J8", "answered_at": "2026-09-10T18:05:10Z", "direction": "outbound", "disposition": null, "duration_seconds": 73, "ended_at": "2026-09-10T18:06:23Z", "from_number": "+15555550000", "id": "call_01J8", "metadata": { "crm_id": "lead-42" }, "status": "failed", "talk_time_seconds": 58, "to_number": "+15555551234" }, "external_id": "crm-lead-42" }, "id": "evt_01J8XYZ", "type": "call.failed" } ``` Agency webhook_url: ```json { "api_version": "2026-09-10", "created_at": "2026-09-10T18:06:01Z", "data": { "call": { "agent_id": "agent_01J8", "answered_at": "2026-09-10T18:05:10Z", "direction": "outbound", "disposition": null, "duration_seconds": 73, "ended_at": "2026-09-10T18:06:23Z", "from_number": "+15555550000", "id": "call_01J8", "metadata": { "crm_id": "lead-42" }, "status": "failed", "talk_time_seconds": 58, "to_number": "+15555551234" }, "error": { "code": "SIP_ERROR", "message": "upstream carrier rejected the call" } }, "id": "evt_01J8XYZ", "type": "call.failed" } ``` ### call.completed Partner and agency. Provisional. The call reached a terminal state; carries `status` + `disposition` (qualified_transfer | transferred | declined | no_answer | voicemail | callback_scheduled | connected_other). Provisional, not final: summary and media arrive later. Agency `webhook_url` callbacks carry `data` exactly as in the example; partner subscriptions add the fields listed in `x-partner-data`. Partner `data` carries `analysis_pending`, `call`, `external_id`, `media_pending`. Agency `data` carries `analysis_pending`, `call`. Partner subscription: ```json { "api_version": "2026-09-10", "created_at": "2026-09-10T18:06:01Z", "data": { "analysis_pending": true, "call": { "agent_id": "agent_01J8", "answered_at": "2026-09-10T18:05:10Z", "direction": "outbound", "disposition": "declined", "duration_seconds": 73, "ended_at": "2026-09-10T18:06:23Z", "from_number": "+15555550000", "id": "call_01J8", "metadata": { "crm_id": "lead-42" }, "status": "completed", "talk_time_seconds": 58, "to_number": "+15555551234" }, "external_id": "crm-lead-42", "media_pending": true }, "id": "evt_01J8XYZ", "type": "call.completed" } ``` Agency webhook_url: ```json { "api_version": "2026-09-10", "created_at": "2026-09-10T18:06:01Z", "data": { "analysis_pending": true, "call": { "agent_id": "agent_01J8", "answered_at": "2026-09-10T18:05:10Z", "direction": "outbound", "disposition": "declined", "duration_seconds": 73, "ended_at": "2026-09-10T18:06:23Z", "from_number": "+15555550000", "id": "call_01J8", "metadata": { "crm_id": "lead-42" }, "status": "completed", "talk_time_seconds": 58, "to_number": "+15555551234" } }, "id": "evt_01J8XYZ", "type": "call.completed" } ``` ### call.transferred Partner and agency. Partner: Transfer result. A warm transfer to a licensed agent connected (the hot handoff). Fires during the call. Carries the transfer result. Not final. Agency `webhook_url` callbacks carry `data` exactly as in the example; partner subscriptions add the fields listed in `x-partner-data`. Partner `data` carries `call`, `external_id`, `transfer`. Agency `data` carries `call`, `transfer`. Partner subscription: ```json { "api_version": "2026-09-10", "created_at": "2026-09-10T18:06:01Z", "data": { "call": { "agent_id": "agent_01J8", "answered_at": "2026-09-10T18:05:10Z", "direction": "outbound", "disposition": "qualified_transfer", "duration_seconds": 73, "ended_at": "2026-09-10T18:06:23Z", "from_number": "+15555550000", "id": "call_01J8", "metadata": { "crm_id": "lead-42" }, "status": "in_progress", "talk_time_seconds": 58, "to_number": "+15555551234" }, "external_id": "crm-lead-42", "transfer": { "connected_at": "2026-09-10T18:05:58Z", "human_talk_seconds": 41, "initiated_at": "2026-09-10T18:05:50Z", "status": "connected", "to_number": "+15555559999" } }, "id": "evt_01J8XYZ", "type": "call.transferred" } ``` Agency webhook_url: ```json { "api_version": "2026-09-10", "created_at": "2026-09-10T18:06:01Z", "data": { "call": { "agent_id": "agent_01J8", "answered_at": "2026-09-10T18:05:10Z", "direction": "outbound", "disposition": "qualified_transfer", "duration_seconds": 73, "ended_at": "2026-09-10T18:06:23Z", "from_number": "+15555550000", "id": "call_01J8", "metadata": { "crm_id": "lead-42" }, "status": "in_progress", "talk_time_seconds": 58, "to_number": "+15555551234" }, "transfer": { "connected_at": "2026-09-10T18:05:58Z", "initiated_at": "2026-09-10T18:05:50Z", "status": "connected", "to_agent": "Jane (Acme Insurance)" } }, "id": "evt_01J8XYZ", "type": "call.transferred" } ``` ### call.analysis.completed Partner and agency. Last event for agency callbacks, once opted in. Partner: Provisional (media_pending). The post-call AI summary, qualification, transcript and recording links are ready (arrives after call.completed). Recording/transcript are links you fetch on demand, so no expiring URLs sit in your webhook logs. For agency `webhook_url` callbacks this is the last event of the call. Partner subscriptions: not final while `media_pending` is true; wait for call.recording.ready. Agency `webhook_url` callbacks carry `data` exactly as in the example; partner subscriptions add the fields listed in `x-partner-data`. Partner `data` carries `analysis`, `call_id`, `external_id`, `links`, `media_pending`. Agency `data` carries `analysis`, `call_id`, `links`. Partner subscription: ```json { "api_version": "2026-09-10", "created_at": "2026-09-10T18:06:01Z", "data": { "analysis": { "outcome": "qualified_transfer", "qualification_data": { "current_carrier": "Geico", "line_of_business": "auto" }, "qualification_score": 0.82, "summary": "Shopping auto+home bundle; renewal in 3 weeks; with Geico." }, "call_id": "call_01J8", "external_id": "crm-lead-42", "links": { "recording": "https://api.entrovox.com/v1/calls/call_01J8/recording-url", "transcript": "https://api.entrovox.com/v1/calls/call_01J8/transcript" }, "media_pending": true }, "id": "evt_01J8XYZ", "type": "call.analysis.completed" } ``` Agency webhook_url: ```json { "api_version": "2026-09-10", "created_at": "2026-09-10T18:06:01Z", "data": { "analysis": { "outcome": "qualified_transfer", "qualification_data": { "current_carrier": "Geico", "line_of_business": "auto" }, "qualification_score": 0.82, "summary": "Shopping auto+home bundle; renewal in 3 weeks; with Geico." }, "call_id": "call_01J8", "links": { "recording": "https://api.entrovox.com/v1/calls/call_01J8/recording-url", "transcript": "https://api.entrovox.com/v1/calls/call_01J8/transcript" } }, "id": "evt_01J8XYZ", "type": "call.analysis.completed" } ``` ### call.recording.ready Partner subscriptions only. Final for partners. Partner only. The recording and transcript are fetchable. This is the one final event: write your disposition and artifacts to your LMS here. `status` is `uploaded` or `failed`. `links` are Entrovox API paths (fetch with your API key), not expiring signed URLs. `x-final` describes the partner contract; `x-audience` says who receives the event; agency `webhook_url` callbacks end at call.analysis.completed. `data` carries `call_id`, `external_id`, `links`, `status`. Payload: ```json { "api_version": "2026-09-10", "created_at": "2026-09-10T18:06:01Z", "data": { "call_id": "call_01J8", "external_id": "crm-lead-42", "links": { "recording": "https://api.entrovox.com/v1/calls/call_01J8/recording-url", "transcript": "https://api.entrovox.com/v1/calls/call_01J8/transcript" }, "status": "uploaded" }, "id": "evt_01J8XYZ", "type": "call.recording.ready" } ``` ### callback.scheduled Partner subscriptions only. Partner: n/a. Partner only. The lead asked to be called back. Show the appointment. Not final. `data` carries `call_id`, `callback_datetime`, `external_id`, `lead_id`, `timezone`. Payload: ```json { "api_version": "2026-09-10", "created_at": "2026-09-10T18:06:01Z", "data": { "call_id": "call_01J8", "callback_datetime": "2026-09-11T15:00:00", "external_id": "crm-lead-42", "lead_id": "lead_01J8", "timezone": "America/Chicago" }, "id": "evt_01J8XYZ", "type": "callback.scheduled" } ``` ### webhook.test Partner subscriptions only. Partner: Ignore. Partner only. Sent by `POST /v1/webhooks/{id}/test` with a real signature so you can confirm verification before live leads. Ignore it as a lead event. `data` carries `ok`. Payload: ```json { "api_version": "2026-09-10", "created_at": "2026-09-10T18:06:01Z", "data": { "ok": true }, "id": "evt_01J8XYZ", "type": "webhook.test" } ``` ## Verify signatures We sign every delivery with [Standard Webhooks (standardwebhooks.com)](https://www.standardwebhooks.com/), so an off-the-shelf library for your language can verify it. Each request carries three headers. - `webhook-id` (string): The event `id`. Stable across retries, so dedupe on it. - `webhook-timestamp` (string): Unix seconds when we signed the delivery. Reject one more than 300 seconds from your clock. - `webhook-signature` (string): One or more space-separated `v1,` entries. Several appear while a secret is rotated, and a match on any one passes. - The signing secret starts with `whsec_` and is shown once. Keep it on your server. - Verify against the raw request body, before any JSON parsing. Re-serializing the JSON breaks the signature. - Return a 2xx within about five seconds, then process in the background. ### With a library Python (verify-library.py): ```python # pip install standardwebhooks import os from standardwebhooks.webhooks import Webhook wh = Webhook(os.environ["ENTROVOX_WEBHOOK_SECRET"]) # whsec_... def handle(raw_body: bytes, headers: dict) -> dict: # Checks webhook-id, webhook-timestamp (300 seconds) and webhook-signature. # Raises WebhookVerificationError when any of them is wrong. return wh.verify(raw_body, headers) ``` Node.js (verify-library.mjs): ```javascript // npm install standardwebhooks import { Webhook } from "standardwebhooks"; const wh = new Webhook(process.env.ENTROVOX_WEBHOOK_SECRET); // whsec_... export function handle(rawBody, headers) { // Throws on a bad signature or a timestamp more than 300 seconds off. return wh.verify(rawBody, headers); } ``` PHP (verify-library.php): ```php verify($rawBody, $headers); } // $event = handle(file_get_contents('php://input'), getallheaders()); ``` ### By hand Without a library, the HMAC key is the base64-decoded part of your secret after `whsec_`. Sign `{webhook-id}.{webhook-timestamp}.{raw body}` exactly, base64-encode the SHA-256 digest, and compare it with each `v1,` entry in constant time. Reject timestamps outside the 300 second window. Python (verify-by-hand.py): ```python import base64 import hashlib import hmac import os import time # The key is the base64-decoded part of the secret after "whsec_". KEY = base64.b64decode(os.environ["ENTROVOX_WEBHOOK_SECRET"].removeprefix("whsec_")) TOLERANCE_SECONDS = 300 def verify(raw_body: bytes, headers: dict) -> bool: msg_id = headers["webhook-id"] timestamp = headers["webhook-timestamp"] if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS: return False # Sign "{id}.{timestamp}.{raw body}" exactly, with the raw bytes. signed = msg_id.encode() + b"." + timestamp.encode() + b"." + raw_body expected = base64.b64encode(hmac.new(KEY, signed, hashlib.sha256).digest()).decode() # The header holds one or more space-separated "v1," entries. for entry in headers["webhook-signature"].split(" "): version, _, signature = entry.partition(",") if version == "v1" and hmac.compare_digest(signature, expected): return True return False ``` Node.js (verify-by-hand.mjs): ```javascript import { createHmac, timingSafeEqual } from "node:crypto"; // The key is the base64-decoded part of the secret after "whsec_". const key = Buffer.from(process.env.ENTROVOX_WEBHOOK_SECRET.replace(/^whsec_/, ""), "base64"); const TOLERANCE_SECONDS = 300; export function verify(rawBody, headers) { const id = headers["webhook-id"]; const timestamp = headers["webhook-timestamp"]; if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false; // Sign "{id}.{timestamp}.{raw body}" exactly, with the raw bytes. const signed = Buffer.concat([Buffer.from(`${id}.${timestamp}.`), Buffer.from(rawBody)]); const expected = createHmac("sha256", key).update(signed).digest(); // The header holds one or more space-separated "v1," entries. return headers["webhook-signature"].split(" ").some((entry) => { const [version, signature = ""] = entry.split(","); const given = Buffer.from(signature, "base64"); return version === "v1" && given.length === expected.length && timingSafeEqual(given, expected); }); } ``` PHP (verify-by-hand.php): ```php TOLERANCE_SECONDS) { return false; } // Sign "{id}.{timestamp}.{raw body}" exactly, with the raw bytes. $expected = base64_encode(hash_hmac('sha256', "$id.$timestamp.$rawBody", $key, true)); // The header holds one or more space-separated "v1," entries. foreach (explode(' ', $headers['webhook-signature']) as $entry) { [$version, $signature] = array_pad(explode(',', $entry, 2), 2, ''); if ($version === 'v1' && hash_equals($expected, $signature)) { return true; } } return false; } ``` ## Retries and replay Acknowledge a delivery with any 2xx within about five seconds. A non-2xx response or a timeout is retried with exponential backoff, about five attempts over a few hours. - **At least once.** A retry is the same event with the same `id`. Dedupe on it. - **Unordered.** Under retries `call.completed` can arrive before `call.answered`. Reconcile against the call's own state, not arrival order. - **After the last attempt** the event is not sent again on its own. Fetch the current state from the lead's [status URL](/developers/status-url), and contact us with the event `id` if you need one resent. To check your signature code before live leads arrive, a partner subscription can ask for a `webhook.test` event, signed like any other. --- # Error reference Branch on `code`, never on the message. Every code below says whether a retry can help and what to do next. ## Error shape A failed request returns a JSON body with one `error` object and the HTTP status that goes with the code. ```json { "error": { "code": "DNC_BLOCKED", "message": "The phone is on the Do Not Call list. No lead was created.", "param": "phone", "details": null, "doc_url": "https://api.entrovox.com/developer/docs#dnc-blocked", "request_id": "REQUEST_ID" } } ``` | Field | Type | Presence | Meaning | |---|---|---|---| | `code` | string | Always present | A stable identifier. Branch on this. | | `message` | string | Always present | A sentence for a person. It can change, so do not match on it. | | `param` | string | May be absent | The field that failed, when one did. | | `details` | object or null | May be absent | Extra data some codes add, such as `next_attempt_local`. It can be null, and some auth errors omit it. | | `doc_url` | string | May be absent | Present on partner lead-surface errors and on API-key validation errors; it links to the code's entry in the error reference, by way of an `api.entrovox.com/developer/docs` address that redirects to the entry in a browser. Other errors omit it. | | `request_id` | string | Always present | Quote it when you contact us. | ## What to do next Each code carries one of four next steps. It tells you whether sending the same request again can ever work. - **Don't retry**: Retrying will fail the same way. Fix the request, or contact us. - **Retry, same key**: Safe to retry after Retry-After when present, otherwise back off. On a POST, resend the same Idempotency-Key and body. - **Look up**: The lead or request already exists. Fetch it instead of sending it again. - **Retry later**: Retry after the time in details.next_attempt_local when present. Otherwise retry when the blocking condition ends, as the meaning says. ## Error codes Each row links to its own anchor. A `doc_url` is an `api.entrovox.com/developer/docs#anchor` link that redirects to this page and lands on that row in a browser. The last step needs JavaScript; a client without it ends on the API reference. | HTTP | Code | What happened | Returned by | Next | |---|---|---|---|---| | 400 | [`DNC_BLOCKED`](#dnc-blocked) | The phone is on the Do Not Call list. No lead was created. | `POST /v1/calls`, `POST /v1/leads` | Don't retry | | 400 | [`CONSENT_INVALID`](#consent-invalid) | trustedform_cert_url is not a TrustedForm certificate URL. Entrovox checks the format only. | | Don't retry | | 400 | [`SOURCE_PAUSED`](#source-paused) | The campaign is paused. No lead was created. Retry only after we tell you the campaign is live. | `POST /v1/leads` | Don't retry | | 400 | [`SOURCE_INACTIVE`](#source-inactive) | The campaign is completed or not taking leads. A draft campaign accepts the lead and pauses it instead. | `POST /v1/leads` | Don't retry | | 400 | [`CROSS_SELL_PAIR_INVALID`](#cross-sell-pair-invalid) | The owned and target lines of business are not a pair this cross-sell campaign quotes. No lead was created. | | Don't retry | | 400 / 422 | [`VALIDATION_ERROR`](#validation-error) | A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field. | `GET /v1/leads`, `POST /v1/leads`, `POST /v1/leads/batch`, `POST /v1/leads/ping`, `POST /v1/leads/{lead_id}/pause` | Don't retry | | 400 | [`FROM_NUMBER_NOT_FOUND`](#from-number-not-found) | from_number is not a phone number in your organization. | `POST /v1/calls` | Don't retry | | 400 | [`FROM_NUMBER_NOT_ACTIVE`](#from-number-not-active) | The from number is not active, so it cannot place a call. | `POST /v1/calls` | Don't retry | | 400 | [`FROM_NUMBER_QUARANTINED`](#from-number-quarantined) | The from number is quarantined. Use another number. | `POST /v1/calls` | Don't retry | | 400 | [`AGENT_NOT_ACTIVE`](#agent-not-active) | The AI voice agent is not active. | `POST /v1/calls` | Don't retry | | 400 | [`LEAD_REFERENCE_MISMATCH`](#lead-reference-mismatch) | lead_id or lead_source_id does not belong to the enrollment named in the request. | `POST /v1/calls` | Don't retry | | 400 | [`MUTED_TURN_HOLD`](#muted-turn-hold) | A recent call to this number has an unreviewed muted turn pending compliance review. Retry after the hold resolves. | `POST /v1/calls` | Retry later | | 400 | [`DIAL_BLOCKED`](#dial-blocked) | The call cannot be placed now. details.reason says why. Retry later for outside_calling_hours, outside_transfer_hours_flag_off, org_holiday, the tcpa_* window reasons and same_phone_inflight: at details.next_attempt_local when present, otherwise when your agency's calling hours reopen, or after the current call to that number ends. Do not retry for org_calling_hours_invalid, org_invalid_timezone, tcpa_missing_timezone, tcpa_invalid_timezone or a cross-sell reason: fix your agency settings or the lead first. | `POST /v1/calls` | Retry later | | 401 | [`AUTHENTICATION_REQUIRED`](#authentication-required) | The request has no API key. | | Don't retry | | 401 | [`TOKEN_INVALID`](#token-invalid) | The API key is not valid. | | Don't retry | | 401 | [`API_KEY_EXPIRED`](#api-key-expired) | The API key has expired. | | Don't retry | | 402 | [`CALL_QUOTA_EXCEEDED`](#call-quota-exceeded) | Your plan's included calls are used up. Enable extra calls in Billing. | `POST /v1/calls` | Don't retry | | 403 | [`INSUFFICIENT_SCOPE`](#insufficient-scope) | A read key tried to write. Use a key with write scope. | | Don't retry | | 403 | [`API_KEY_ENDPOINT_NOT_ALLOWED`](#api-key-endpoint-not-allowed) | The endpoint is outside the partner surface, or the key's campaign binding is invalid. Ask for a new key. | `GET /v1/leads`, `GET /v1/leads/{lead_id}`, `GET /v1/leads/{lead_id}/calls`, `POST /v1/leads`, `POST /v1/leads/batch`, `POST /v1/leads/ping`, `POST /v1/leads/{lead_id}/pause`, `POST /v1/leads/{lead_id}/resume` | Don't retry | | 403 | [`LEAD_SOURCE_NOT_ALLOWED`](#lead-source-not-allowed) | The body names a campaign other than the one this key is bound to. | `GET /v1/calls`, `GET /v1/leads`, `POST /v1/leads`, `POST /v1/leads/batch`, `POST /v1/leads/ping` | Don't retry | | 403 | [`CALLS_NOT_ALLOWED_ON_BOUND_KEY`](#calls-not-allowed-on-bound-key) | A partner key called POST /calls. | `POST /v1/calls` | Don't retry | | 404 | [`LEAD_NOT_FOUND`](#lead-not-found) | No lead with that id in your organization. | `GET /v1/leads/{lead_id}`, `GET /v1/leads/{lead_id}/calls`, `POST /v1/calls`, `POST /v1/leads`, `POST /v1/leads/{lead_id}/pause`, `POST /v1/leads/{lead_id}/resume` | Don't retry | | 404 | [`CALL_NOT_FOUND`](#call-not-found) | No call with that id in your organization. | `GET /v1/calls/{call_id}`, `GET /v1/calls/{call_id}/analysis`, `GET /v1/calls/{call_id}/recording-url`, `GET /v1/calls/{call_id}/transcript` | Don't retry | | 404 | [`LEAD_SOURCE_NOT_FOUND`](#lead-source-not-found) | lead_source_id is not a campaign in your organization. | `POST /v1/calls`, `POST /v1/leads`, `POST /v1/leads/batch`, `POST /v1/leads/ping` | Don't retry | | 404 | [`CALL_ANALYSIS_NOT_FOUND`](#call-analysis-not-found) | The call exists but its analysis is not written yet. It is pending until call.analysis.completed, or until analysis_status is completed. | `GET /v1/calls/{call_id}/analysis` | Retry later | | 404 | [`RECORDING_NOT_FOUND`](#recording-not-found) | The call has no recording, or its file is missing. | `GET /v1/calls/{call_id}/recording-url` | Don't retry | | 404 | [`RECORDING_NOT_READY`](#recording-not-ready) | The call has a recording that is still being processed. Retry after Retry-After, or wait for call.recording.ready (partner subscriptions, once webhook delivery is live). | `GET /v1/calls/{call_id}/recording-url` | Retry later | | 404 | [`VOICE_AGENT_NOT_FOUND`](#voice-agent-not-found) | No AI voice agent with that id in your organization. | `POST /v1/calls` | Don't retry | | 404 | [`PHONE_NUMBER_NOT_FOUND`](#phone-number-not-found) | No phone number with that id in your organization. | `POST /v1/calls` | Don't retry | | 404 | [`LEAD_SOURCE_LEAD_NOT_FOUND`](#lead-source-lead-not-found) | lead_source_lead_id is not a lead in one of your campaigns. | `POST /v1/calls` | Don't retry | | 404 | [`ORGANIZATION_NOT_FOUND`](#organization-not-found) | The organization on this account was not found. Contact us. | `POST /v1/calls` | Don't retry | | 409 | [`EXTERNAL_ID_CONFLICT`](#external-id-conflict) | The same external_id exists in the campaign with a different phone or is_test. | `POST /v1/leads` | Look up | | 409 | [`LEAD_PHONE_CONFLICT`](#lead-phone-conflict) | A live lead with this phone is already enrolled under another external_id. | `POST /v1/leads` | Look up | | 409 | [`IDEMPOTENCY_KEY_REUSED`](#idempotency-key-reused) | The same Idempotency-Key and path came with a different body. | `POST /v1/calls`, `POST /v1/leads`, `POST /v1/leads/batch` | Don't retry | | 409 | [`IDEMPOTENCY_IN_PROGRESS`](#idempotency-in-progress) | A request with this Idempotency-Key is still being processed. | `POST /v1/calls`, `POST /v1/leads`, `POST /v1/leads/batch` | Retry, same key | | 409 | [`LEAD_NOT_PAUSEABLE`](#lead-not-pauseable) | The lead's sequence already ended, so it cannot be paused. | `POST /v1/leads/{lead_id}/pause`, `POST /v1/leads/{lead_id}/resume` | Don't retry | | 409 | [`LEAD_ENROLLED_ELSEWHERE`](#lead-enrolled-elsewhere) | Entrovox also runs this lead outside your campaign, so you cannot pause or resume it. Ask us. | `POST /v1/leads/{lead_id}/pause`, `POST /v1/leads/{lead_id}/resume` | Don't retry | | 409 | [`LEAD_PAUSED_BY_AGENCY`](#lead-paused-by-agency) | Your Entrovox contact, their integration or the system paused this lead. A campaign key cannot resume it. Ask us. | `POST /v1/leads/{lead_id}/resume` | Don't retry | | 422 | [`UNSUPPORTED_FILTER`](#unsupported-filter) | That filter is not available to API keys. | `GET /v1/leads` | Don't retry | | 422 | [`LEAD_IS_TEST`](#lead-is-test) | The lead is a test lead, so it cannot be called. | `POST /v1/calls` | Don't retry | | 422 | [`LEAD_SCREENED_OUT`](#lead-screened-out) | The lead check blocked this lead, so no call was placed. | `POST /v1/calls` | Don't retry | | 429 | [`AI_MINUTES_EXHAUSTED`](#ai-minutes-exhausted) | The monthly AI minutes limit is reached. Unlike RATE_LIMIT_EXCEEDED, this 429 has no Retry-After and will not clear until the plan's minutes reset. Upgrade the plan or wait. | `POST /v1/calls` | Don't retry | | 429 | [`RATE_LIMIT_EXCEEDED`](#rate-limit-exceeded) | Too many requests. Wait for Retry-After. | | Retry, same key | | 500 | [`INTERNAL_ERROR`](#internal-error) | Something failed on our side. Include request_id if you contact us. | | Retry, same key | | 502 | [`UPSTREAM_ERROR`](#upstream-error) | Billing is not set up for your account, so the call was not placed. Contact us. | `POST /v1/calls` | Don't retry | | 503 | [`DB_ADMISSION_OVERLOADED`](#db-admission-overloaded) | Our database is at capacity. A request with several writes may have saved some. Retry after Retry-After; retrying with the same key is safe. | | Retry, same key | | 503 | [`DB_ADMISSION_UNAVAILABLE`](#db-admission-unavailable) | Our database is temporarily unavailable. Retry after Retry-After. | | Retry, same key | | 503 | [`DB_BACKEND_UNAVAILABLE`](#db-backend-unavailable) | Our database did not answer. Retry after Retry-After. | | Retry, same key | | 503 | [`PROVIDER_UNAVAILABLE`](#provider-unavailable) | Our DNC check could not run, or other posts for the same phone were being written at that moment. No lead was created. On a batch result row, resend only the failed rows in a new batch with a fresh Idempotency-Key; the external_id keeps it idempotent. | `POST /v1/leads`, `POST /v1/leads/ping` | Retry, same key | | 503 | [`RECORDING_UNAVAILABLE`](#recording-unavailable) | The recording exists but a signed link could not be made right now. Retry after Retry-After. | `GET /v1/calls/{call_id}/recording-url` | Retry, same key | | 503 | [`RECORDING_TRANSCODE_FAILED`](#recording-transcode-failed) | The recording could not be prepared as m4a. Retry after Retry-After, or use the Ogg recording. | `GET /v1/calls/{call_id}/recording-url` | Retry, same key |