Skip to content

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

MethodPathTierPurpose
GET/voice-agentsreadList your AI voice agents and get an agent_id
GET/voice-agents/{id}readOne AI voice agent
GET/phone-numbersreadList your numbers and get a caller ID
GET/phone-numbers/{id}readOne number
POST/callswriteInitiate an outbound call
GET/callsreadList calls
GET/calls/{id}readCall status and detail
GET/calls/{id}/analysisreadPost-call summary and outcome
GET/calls/{id}/transcriptreadTranscript
GET/calls/{id}/recording-urlreadShort-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.

  1. 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 https://api.entrovox.com/v1/voice-agents \
      -H "Authorization: ApiKey $ENTROVOX_KEY"
    curl https://api.entrovox.com/v1/phone-numbers \
      -H "Authorization: ApiKey $ENTROVOX_KEY"
  2. Place the call

    POST /v1/calls needs the write tier. Send an Idempotency-Key so 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" }
      }'
    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_numberstringRequired

    Who to call, in E.164.

    from_numberstringRequired

    Your caller ID, in E.164. It must be a number you own: list yours with GET /phone-numbers.

    agent_idstringRequired

    The AI voice agent to use, from GET /voice-agents.

    variablesobjectOptional

    Key and value pairs injected into the AI voice agent's prompt, like first_name.

    metadataobjectOptional

    A free-form object stored on the call and echoed back on reads.

    is_testbooleanOptional

    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.

    schedulingobjectOptional

    Dial later instead of now.

    webhook_urlstringOptional

    Where to send call events. Webhook delivery is a preview: the URL is accepted and stored, and nothing is sent yet. See Webhooks.

    webhook_eventsarrayOptional

    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.

  3. 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. Webhooks will push the same events once delivery ships.

    curl https://api.entrovox.com/v1/calls/call_01J8K3Q7M2 \
      -H "Authorization: ApiKey $ENTROVOX_KEY"

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

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.

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)

Errors

Every error returns { "error": { "code", "message", "details" } }. The code is stable: branch on it, not on the message text.

Authentication and authorization

HTTPCodeMeaning
401AUTHENTICATION_REQUIREDMissing or malformed Authorization header
401TOKEN_INVALIDAPI key not found or wrong format
401API_KEY_EXPIREDKey is past its expiry
403INSUFFICIENT_SCOPEKey lacks the tier, like a read key calling POST /calls
403API_KEY_ENDPOINT_NOT_ALLOWEDThe endpoint is outside the API-key surface

Request and compliance

HTTPCodeMeaning
400DNC_BLOCKED or a compliance codeDestination is on DNC or outside its calling-hours window
404*_NOT_FOUNDAn id in the request, like agent_id or from_number, is not in your organization
409IDEMPOTENCY_IN_PROGRESSA request with this Idempotency-Key is still running: retry shortly
409IDEMPOTENCY_KEY_REUSEDThis Idempotency-Key was already used for a different request: send a fresh key for a new call
422VALIDATION_ERRORThe body failed validation, and details lists the fields
429RATE_LIMIT_EXCEEDEDToo 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.

Updated Nov 7, 2026