Skip to content

Leads

Ping a lead

POST/v1/leads/ping

Would this lead be taken right now? Creates nothing. API keys only.

200 {accepted, reason, queued_reason, lead_source_id}; accepted: false is the never-accepted class. An unknown campaign is the post's 404; a DNC check that could not run is 503 PROVIDER_UNAVAILABLE. Takes no idempotency reservation; an Idempotency-Key header is ignored.

On this page

Headers

AuthorizationstringRequired
ApiKey $ENTROVOX_KEY. Keys are issued per organization.

Body

external_idstring or null, 1–128Optional
Correlation only. A lead in this campaign with the same external_id holding the phone counts as a replay, so it is accepted. Not stored or echoed.
lead_source_idstring or nullOptional
phonestring or null, max 32Optional
statestring or null, max 64Optional
target_line_of_businessstring or null, max 64Optional
zip_codestring or null, max 10Optional

Returns

200 OKAlways, when the request is well-formed: accepted false with a reason is the never-accepted class (dnc, already_enrolled, source_inactive, source_paused, invalid_phone; consent_invalid is reserved). accepted true may carry a queued_reason (outside_hours, missing_geography; capacity is reserved). Nothing is created or reserved.

acceptedbooleanAlways present
False only for the never-accepted class.
lead_source_idstringAlways present
The campaign evaluated.
queued_reasonstring or nullMay be absent
Set only when accepted is true but the first dial will wait. capacity is reserved and not returned yet.

One ofoutside_hourscapacitymissing_geography

reasonstring or nullMay be absent
Why it would not be accepted. consent_invalid is reserved: ping carries no consent certificate, so it is not returned yet.

One ofdncalready_enrolledsource_inactivesource_pausedinvalid_phoneconsent_invalid

Errors

  • 400VALIDATION_ERROR

    A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field.

    Retrying will fail the same way. Fix the request, or contact us.

  • 403INSUFFICIENT_SCOPE

    A read key tried to write. Use a key with write scope.

    Retrying will fail the same way. Fix the request, or contact us.

  • 403API_KEY_ENDPOINT_NOT_ALLOWED

    The endpoint is outside the partner surface, or the key's campaign binding is invalid. Ask for a new key.

    Retrying will fail the same way. Fix the request, or contact us.

  • 403LEAD_SOURCE_NOT_ALLOWED

    The body names a campaign other than the one this key is bound to.

    Retrying will fail the same way. Fix the request, or contact us.

  • 404LEAD_SOURCE_NOT_FOUND

    lead_source_id is not a campaign in your organization.

    Retrying will fail the same way. Fix the request, or contact us.

  • 422VALIDATION_ERROR

    A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field.

    Retrying will fail the same way. Fix the request, or contact us.

  • 503PROVIDER_UNAVAILABLE

    Our DNC check could not run, or other posts for the same phone were being written at that moment. No lead was created. On a batch result row, resend only the failed rows in a new batch with a fresh Idempotency-Key; the external_id keeps it idempotent.

    Safe to retry after Retry-After when present, otherwise back off. On a POST, resend the same Idempotency-Key and body.

Any request can also return AUTHENTICATION_REQUIRED, TOKEN_INVALID, API_KEY_EXPIRED, RATE_LIMIT_EXCEEDED or INTERNAL_ERROR.