Skip to content

Get outcomes

The status URL

Every accepted lead returns one URL that holds its disposition and every call attempt. Poll it until webhooks ship.

On this page

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 will replace polling once delivery ships.

  1. 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 https://api.entrovox.com/v1/leads/7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40 \
      -H "Authorization: ApiKey $ENTROVOX_KEY"
    200OK
    {
      "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"
          }
        ]
      }
    }
  2. 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 from the URLs on that row.
  3. 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.

    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"])

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 "https://api.entrovox.com/v1/leads?external_id=px-88421" \
  -H "Authorization: ApiKey $ENTROVOX_KEY"

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. 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 for a finished call, or subscribe to webhooks when delivery turns on.

Updated Nov 7, 2026