Skip to content

Send leads

Post a live lead

Enroll one lead the moment it arrives. First dial is immediate inside calling hours.

On this page

A live post is the 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.

  1. Post the lead

    Send the four required fields and any geography you have. Send a fresh Idempotency-Key with every request.

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

    201Created
    {
      "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": []
      }
    }
  3. 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.

Fields

first_namestringRequired

Who to call. 1 to 200 characters, not blank.

last_namestringRequired

Who to call. 1 to 200 characters, not blank.

phonestringRequired

E.164. US and Canada numbers are +1 plus 10 digits. Anything else is 400 VALIDATION_ERROR.

external_idstringRequired

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_idstringOptional

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_altstringOptional

A second E.164 number. Stored. It is not dialed in v1.

owned_line_of_businessstringOptional

Cross-sell: the line of business the person already has.

target_line_of_businessstringOptional

The line of business we should quote.

emailstringOptional

Stored on the lead.

statestringOptional

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_codestringOptional

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.

timezonestringOptional

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_languagestringOptional

es opens the first call in Spanish.

One ofenes

lead_generated_atstringOptional

Your create time, as a date-time. Drives oldest-first and newest-first dial order. Defaults to when we received the post.

is_testbooleanOptional

true stores a test lead we never call or text. Omit it for a real lead. See the quickstart.

Default false

trustedform_cert_urlstringOptional

A TrustedForm certificate URL. We check the format only: a malformed URL is 400 CONSENT_INVALID.

jornaya_leadidstringOptional

Jornaya LeadiD. Stored, not validated.

metadataobjectOptional

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.

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, or send inventory in bulk with Batch post.

Updated Nov 7, 2026