Leads
Create a lead
POST/v1/leads
Post one lead into a campaign.
API keys: external_id is required; 201 enrolls the lead, a retry with the same external_id (same phone, campaign and is_test) replays it with 200 and X-Duplicate: external_id. DNC, invalid phone, a paused or inactive campaign and invalid consent are 4xx with no row. Send an Idempotency-Key (UUID) to make transport retries safe.
Headers
AuthorizationstringRequiredApiKey $ENTROVOX_KEY. Keys are issued per organization.Idempotency-Keystring or nullOptionalBody
emailstring or null, max 320Optionalexternal_idstring or null, 1–128Requiredfirst_namestring, 1–200Requiredis_testbooleanOptionalDefault false
jornaya_leadidstring or null, max 256Optionallast_namestring, 1–200Requiredlead_generated_atstring or nullOptionallead_source_idstring or nullOptionalmetadataobject or nullOptionalowned_line_of_businessstring or null, max 64Optionalphonestring, 1–32Requiredphone_altstring or nullOptionalpreferred_languagestring or nullOptionalOne ofenes
statestring or null, max 64Optionaltarget_line_of_businessstring or null, max 64Optionaltimezonestring or null, max 64Optionaltransfer_phonestring or nullOptionaltrustedform_cert_urlstring or null, max 512Optionalzip_codestring or null, max 10OptionalReturns
200 OKReplay: same external_id, phone, campaign and is_test (data.replayed true, X-Duplicate: external_id). A lead that never enrolled, or that a duplicate check parked, is refused instead (400 DNC_BLOCKED / 409 LEAD_PHONE_CONFLICT).
attempt_countintegerMay be absentDefault 0
callsarray of object or nullMay be absentcalls_urlstringAlways presentcreated_atstring (date-time)Always presentcurrent_dispositionstringAlways presentdedup_statusstring or nullMay be absentdial_blockerstring or nullMay be absentdisposition_atstring (date-time) or nullMay be absentemailstring or nullMay be absentexternal_idstring or nullMay be absentfirst_namestring or nullMay be absentidstringAlways presentis_dncbooleanMay be absentDefault false
is_testbooleanMay be absentDefault false
jornaya_leadidstring or nullMay be absentlast_attempted_atstring (date-time) or nullMay be absentlast_namestring or nullMay be absentmetadataobjectMay be absentnational_dnc_statusstring or nullMay be absentnext_attempt_atstring (date-time) or nullMay be absentorganization_idstringAlways presentpause_is_queuedbooleanMay be absentDefault false
pausedbooleanMay be absentDefault false
paused_atstring (date-time) or nullMay be absentpaused_reasonstring or nullMay be absentphonestringAlways presentphone_altstring or nullMay be absentpreferred_languagestring or nullMay be absentreplayedboolean or nullMay be absentsequence_statusstring or nullMay be absentsequence_stepintegerMay be absentDefault 0
statestring or nullMay be absentstatus_urlstringAlways presenttimezonestring or nullMay be absenttransfer_phonestring or nullMay be absenttrustedform_cert_urlstring or nullMay be absentupdated_atstring (date-time)Always presentzip_codestring or nullMay be absent201 CreatedCreated and enrolled. A draft campaign is accepted and paused (not dialed). A retry with the same Idempotency-Key and body returns this response unchanged (X-Idempotency-Replayed: true).
Same body as above.
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.
- 400
DNC_BLOCKEDThe phone is on the Do Not Call list. No lead was created.
Retrying will fail the same way. Fix the request, or contact us.
- 400
SOURCE_PAUSEDThe campaign is paused. No lead was created. Retry only after we tell you the campaign is live.
Retrying will fail the same way. Fix the request, or contact us.
- 400
SOURCE_INACTIVEThe campaign is completed or not taking leads. A draft campaign accepts the lead and pauses it instead.
Retrying will fail the same way. Fix the request, or contact us.
- 400
CONSENT_INVALIDtrustedform_cert_url is not a TrustedForm certificate URL. Entrovox checks the format only.
Retrying will fail the same way. Fix the request, or contact us.
- 400
CROSS_SELL_PAIR_INVALIDThe owned and target lines of business are not a pair this cross-sell campaign quotes. No lead was created.
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.
- 404
LEAD_NOT_FOUNDNo lead with that id in your organization.
Retrying will fail the same way. Fix the request, or contact us.
- 409
EXTERNAL_ID_CONFLICTThe same external_id exists in the campaign with a different phone or is_test.
The lead or request already exists. Fetch it instead of sending it again.
- 409
LEAD_PHONE_CONFLICTA live lead with this phone is already enrolled under another external_id.
The lead or request already exists. Fetch it instead of sending it again.
- 409
IDEMPOTENCY_KEY_REUSEDThe same Idempotency-Key and path came with a different body.
Retrying will fail the same way. Fix the request, or contact us.
- 409
IDEMPOTENCY_IN_PROGRESSA request with this Idempotency-Key is still being processed.
Safe to retry after Retry-After when present, otherwise back off. On a POST, resend the same Idempotency-Key and body.
- 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.