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.
Post the lead
Send the four required fields and any geography you have. Send a fresh
Idempotency-Keywith 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" }'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 thisimport { 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 thisRead the 201
201means we enrolled the lead. First dial is immediate when we are inside TCPA calling hours and have capacity. Otherwisenext_attempt_attells you when. Persistidandstatus_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": [] } }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
4xxand 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_namestringRequiredWho to call. 1 to 200 characters, not blank.
last_namestringRequiredWho to call. 1 to 200 characters, not blank.
phonestringRequiredE.164. US and Canada numbers are +1 plus 10 digits. Anything else is 400 VALIDATION_ERROR.
external_idstringRequiredYour 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_idstringOptionalThe 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_altstringOptionalA second E.164 number. Stored. It is not dialed in v1.
owned_line_of_businessstringOptionalCross-sell: the line of business the person already has.
target_line_of_businessstringOptionalThe line of business we should quote.
emailstringOptionalStored on the lead.
statestringOptionalTwo-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_codestringOptional5-digit or ZIP+4. With no state and no timezone, the ZIP sets the timezone, accurate to 5 digits in states with two zones.
timezonestringOptionalAn 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_languagestringOptionales opens the first call in Spanish.
One ofenes
lead_generated_atstringOptionalYour create time, as a date-time. Drives oldest-first and newest-first dial order. Defaults to when we received the post.
is_testbooleanOptionaltrue stores a test lead we never call or text. Omit it for a real lead. See the quickstart.
Default false
trustedform_cert_urlstringOptionalA TrustedForm certificate URL. We check the format only: a malformed URL is 400 CONSENT_INVALID.
jornaya_leadidstringOptionalJornaya LeadiD. Stored, not validated.
metadataobjectOptionalYour 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:
"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.