Skip to content

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.

  1. Ping with the lead's phone and ZIP

    POST /v1/leads/ping is a POST on purpose: the phone must not land in query logs. It uses the same field names as a lead, so send zip_code, not zip.

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

    200OK
    {
      "accepted": true,
      "reason": null,
      "queued_reason": null,
      "lead_source_id": "c222…"
    }

    accepted: false is the never-accepted class, with a reason of dnc, already_enrolled, invalid_phone, source_paused or source_inactive. Resell that lead.

    After-hours and unknown geography still return accepted: true, with a queued_reason of outside_hours or missing_geography. Post the lead: we call when we can.

  3. Post the lead

    Send the accepted lead with Post a live lead. A ping that answered 503 PROVIDER_UNAVAILABLE means our DNC check could not run, so retry it after Retry-After. A campaign that is not in your organization is 404 LEAD_SOURCE_NOT_FOUND, the same as a post.

Fields

All fields are optional. They match the lead write fields.

phonestringOptional

E.164. Without it, the phone checks are skipped.

statestringOptional

Two-letter USPS code.

zip_codestringOptional

5-digit or ZIP+4.

target_line_of_businessstringOptional

The line of business we should quote.

lead_source_idstringOptional

Campaign. A bound key may omit it. Naming another campaign is 403 LEAD_SOURCE_NOT_ALLOWED.

external_idstringOptional

For 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:

  1. The campaign is completed or otherwise not live: source_inactive.
  2. The campaign is paused: source_paused.
  3. phone is not a US or Canadian E.164 number: invalid_phone.
  4. phone is on your DNC list, or a prior lead on it was marked DNC: dnc.
  5. phone is 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.

Updated Nov 7, 2026