Send leads
Ping before you post
An optional accept or reject pre-check for publishers that already run ping and post.
On this page
Use ping only if your publisher already speaks ping and post. Direct post is the default path. A ping creates nothing, reserves nothing and ignores Idempotency-Key. A read key is enough.
Ping with the lead's phone and ZIP
POST
/v1/leads/pingis a POST on purpose: the phone must not land in query logs. It uses the same field names as a lead, so sendzip_code, notzip.curl -X POST https://api.entrovox.com/v1/leads/ping \ -H "Authorization: ApiKey $ENTROVOX_KEY" \ -H "Content-Type: application/json" \ -d '{"phone": "+14255551234", "zip_code": "98101"}'import os, requests r = requests.post( "https://api.entrovox.com/v1/leads/ping", headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"}, json={"phone": "+14255551234", "zip_code": "98101"}, timeout=15, ) r.raise_for_status() ping = r.json() print(ping["accepted"], ping["reason"], ping["queued_reason"])const res = await fetch("https://api.entrovox.com/v1/leads/ping", { method: "POST", headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ phone: "+14255551234", zip_code: "98101" }), }); const ping = await res.json(); console.log(ping.accepted, ping.reason, ping.queued_reason);Branch on accepted
200OK{ "accepted": true, "reason": null, "queued_reason": null, "lead_source_id": "c222…" }accepted: falseis the never-accepted class, with areasonofdnc,already_enrolled,invalid_phone,source_pausedorsource_inactive. Resell that lead.After-hours and unknown geography still return
accepted: true, with aqueued_reasonofoutside_hoursormissing_geography. Post the lead: we call when we can.Post the lead
Send the accepted lead with Post a live lead. A ping that answered
503 PROVIDER_UNAVAILABLEmeans our DNC check could not run, so retry it afterRetry-After. A campaign that is not in your organization is404 LEAD_SOURCE_NOT_FOUND, the same as a post.
Fields
All fields are optional. They match the lead write fields.
phonestringOptionalE.164. Without it, the phone checks are skipped.
statestringOptionalTwo-letter USPS code.
zip_codestringOptional5-digit or ZIP+4.
target_line_of_businessstringOptionalThe line of business we should quote.
lead_source_idstringOptionalCampaign. A bound key may omit it. Naming another campaign is 403 LEAD_SOURCE_NOT_ALLOWED.
external_idstringOptionalFor the replay check below. Used for correlation only: it is not stored or echoed.
Re-posting a lead you already sent
Ping with its phone and external_id. Ping then answers the way the post would: accepted: true for a clean replay, and dnc or already_enrolled if the post would be refused.
How a ping is decided
The first match wins for reason:
- The campaign is completed or otherwise not live:
source_inactive. - The campaign is paused:
source_paused. phoneis not a US or Canadian E.164 number:invalid_phone.phoneis on your DNC list, or a prior lead on it was marked DNC:dnc.phoneis in an active sequence under another lead:already_enrolled.
Next steps
Read Rate limits and volume for the ping bucket, then Post a live lead.