Place calls
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.
On this page
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, 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. 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_idcomes from your AI voice agents, andfrom_numbermust be a number you own. Both calls need only thereadtier. Use theidof the AI voice agent and thephone_numberof the number.curl https://api.entrovox.com/v1/voice-agents \ -H "Authorization: ApiKey $ENTROVOX_KEY"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"])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 https://api.entrovox.com/v1/phone-numbers \ -H "Authorization: ApiKey $ENTROVOX_KEY"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"])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/callsneeds thewritetier. Send anIdempotency-Keyso a retry never dials twice.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" } }'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"])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);201Created{ "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_numberstringRequiredWho to call, in E.164.
from_numberstringRequiredYour caller ID, in E.164. It must be a number you own: list yours with
GET /phone-numbers.agent_idstringRequiredThe AI voice agent to use, from
GET /voice-agents.variablesobjectOptionalKey and value pairs injected into the AI voice agent's prompt, like
first_name.metadataobjectOptionalA free-form object stored on the call and echoed back on reads.
is_testbooleanOptionaltruemarks 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.schedulingobjectOptionalDial later instead of now.
webhook_urlstringOptionalWhere to send call events. Webhook delivery is a preview: the URL is accepted and stored, and nothing is sent yet. See Webhooks.
webhook_eventsarrayOptionalWhich events to deliver once delivery is on. The default is
call.started,call.completed,call.failedandcall.transferred.call.analysis.completedandcall.answeredare opt-in: add them to receive them.call.analysis.completedis the last event for an agency callback. See Webhooks.Get the outcome
A call is asynchronous. Poll
GET /v1/calls/{id}forstatus, then fetch the analysis, transcript and recording once the call has ended, as in Recordings and transcripts. Webhooks will push the same events once delivery ships.curl https://api.entrovox.com/v1/calls/call_01J8K3Q7M2 \ -H "Authorization: ApiKey $ENTROVOX_KEY"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"])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.
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" }
}'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"])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.
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 is live.
# 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 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.
Next steps
Pull the transcript and recording for the call you placed, or learn the rate limits that apply. POST /calls shares the 100 per minute default bucket, and reads have their own 300 per minute bucket.