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.
Headers
AuthorizationstringRequiredApiKey $ENTROVOX_KEY. Keys are issued per organization.Body
external_idstring or null, 1–128Optionallead_source_idstring or nullOptionalphonestring or null, max 32Optionalstatestring or null, max 64Optionaltarget_line_of_businessstring or null, max 64Optionalzip_codestring or null, max 10OptionalReturns
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 presentlead_source_idstringAlways presentqueued_reasonstring or nullMay be absentOne ofoutside_hourscapacitymissing_geography
reasonstring or nullMay be absentOne ofdncalready_enrolledsource_inactivesource_pausedinvalid_phoneconsent_invalid
Errors
- 400
VALIDATION_ERRORA 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.
- 403
INSUFFICIENT_SCOPEA read key tried to write. Use a key with write scope.
Retrying will fail the same way. Fix the request, or contact us.
- 403
API_KEY_ENDPOINT_NOT_ALLOWEDThe 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.
- 403
LEAD_SOURCE_NOT_ALLOWEDThe 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.
- 404
LEAD_SOURCE_NOT_FOUNDlead_source_id is not a campaign in your organization.
Retrying will fail the same way. Fix the request, or contact us.
- 422
VALIDATION_ERRORA 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.
- 503
PROVIDER_UNAVAILABLEOur 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.