Send leads
Batch post
Send up to 500 aged or unsold leads in one request and reconcile one result per row.
On this page
Batch post is for aged or unsold inventory. Each item has the same shape as a single post. The response has one result per input row, in the same order, so you can always reconcile.
Post the batch
POST
/v1/leads/batchtakes 1 to 500 leads. Putis_test: trueon any row to store it as a test lead, the same as on a single post.curl -X POST https://api.entrovox.com/v1/leads/batch \ -H "Authorization: ApiKey $ENTROVOX_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "leads": [ { "first_name": "Alex", "last_name": "Nguyen", "phone": "+14255550001", "external_id": "inv-1001" }, { "first_name": "Sam", "last_name": "Ortiz", "phone": "+14255550002", "external_id": "inv-1002" } ] }'import os, uuid, requests r = requests.post( "https://api.entrovox.com/v1/leads/batch", headers={ "Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "leads": [ { "first_name": "Alex", "last_name": "Nguyen", "phone": "+14255550001", "external_id": "inv-1001", }, { "first_name": "Sam", "last_name": "Ortiz", "phone": "+14255550002", "external_id": "inv-1002", }, ] }, timeout=60, ) r.raise_for_status() batch = r.json() for item in batch["items"]: print(item["index"], item["status"], item["status_url"] or item["code"])import { randomUUID } from "node:crypto"; const res = await fetch("https://api.entrovox.com/v1/leads/batch", { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, "Idempotency-Key": randomUUID(), "Content-Type": "application/json", }, body: JSON.stringify({ leads: [ { first_name: "Alex", last_name: "Nguyen", phone: "+14255550001", external_id: "inv-1001" }, { first_name: "Sam", last_name: "Ortiz", phone: "+14255550002", external_id: "inv-1002" }, ], }), }); const batch = await res.json(); for (const item of batch.items) console.log(item.index, item.status, item.status_url ?? item.code);Reconcile every row
200always means the request was well formed. Partial success lives initems.200OK{ "lead_source_id": "c222…", "created": 1, "replayed": 0, "rejected": 1, "items": [ { "index": 0, "status": "created", "external_id": "inv-1001", "lead_id": "a111…", "status_url": "https://api.entrovox.com/v1/leads/a111…", "code": null, "message": null }, { "index": 1, "status": "rejected", "external_id": "inv-1002", "lead_id": null, "status_url": null, "code": "DNC_BLOCKED", "message": "Phone is on the DNC list, so we did not create a lead. Remove it from your list or pause it; do not retry." } ] }Each item's
statusis one ofcreated,replayed,conflictorrejected. The totalscreated,replayedandrejectedare conveniences.rejectedcounts rows whose status isrejectedorconflict.Resend only what is safe to resend
A row with
codePROVIDER_UNAVAILABLEcreated nothing. It is safe to resend in a new batch, and itsexternal_idmakes the resend idempotent. Every otherrejectedrow is final for that payload: fix it (aVALIDATION_ERRORrow is fixable) or resell it.
Choosing the campaign
The campaign for the whole batch comes from the envelope, next to leads.
lead_source_idstringOptionalThe campaign id. Required for an unbound agency key: without it the batch answers 422 with param lead_source_id. A bound partner key may omit it, and naming a different campaign is 403 LEAD_SOURCE_NOT_ALLOWED. A campaign that is not in your organization is 404 LEAD_SOURCE_NOT_FOUND.
leadsarrayRequired1 to 500 lead objects.
A row-level lead_source_id does not pick the batch's campaign. A row that repeats the batch's campaign is accepted. A row that names a different campaign is rejected as that item, with param lead_source_id, and the rest of the batch continues.
An agency key that is not bound to a campaign posts like this:
curl -X POST https://api.entrovox.com/v1/leads/batch \
-H "Authorization: ApiKey $ENTROVOX_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"lead_source_id": "YOUR_CAMPAIGN_ID",
"leads": [
{
"first_name": "Alex",
"last_name": "Nguyen",
"phone": "+14255550001",
"external_id": "inv-1001"
}
]
}'import os, uuid, requests
r = requests.post(
"https://api.entrovox.com/v1/leads/batch",
headers={
"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"lead_source_id": "YOUR_CAMPAIGN_ID",
"leads": [
{
"first_name": "Alex",
"last_name": "Nguyen",
"phone": "+14255550001",
"external_id": "inv-1001",
},
],
},
timeout=60,
)
r.raise_for_status()
print(r.json()["items"])import { randomUUID } from "node:crypto";
const res = await fetch("https://api.entrovox.com/v1/leads/batch", {
method: "POST",
headers: {
Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`,
"Idempotency-Key": randomUUID(),
"Content-Type": "application/json",
},
body: JSON.stringify({
lead_source_id: "YOUR_CAMPAIGN_ID",
leads: [
{ first_name: "Alex", last_name: "Nguyen", phone: "+14255550001", external_id: "inv-1001" },
],
}),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log((await res.json()).items);Rules that apply to every batch
- A bad row never fails the batch. DNC, a bad phone, a missing
external_idor a paused campaign comes back as arejecteditem with itscode. The whole request fails only when it is malformed (422: noleads, an empty array, more than 500 rows) or names a campaign your key cannot use (403 LEAD_SOURCE_NOT_ALLOWED,404 LEAD_SOURCE_NOT_FOUND). - Rows that share a phone run in order. Rows run in parallel, except that rows with the same
phone(orexternal_id) run in input order. The first iscreated; a later one isconflict(LEAD_PHONE_CONFLICT) orreplayed. - Retrying a whole batch. The batch
Idempotency-Keymust be a UUID, or the request gets400 VALIDATION_ERROR. Send the same key and the same body. You get the original response back and no row is processed again. - Limits. 500 leads per request and 20 batches per minute on a standard partner key. See Rate limits and volume.
Next steps
Follow each created lead from its status URL, and read Safe retries and idempotency before you automate resends.