Skip to content

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.

On this page

Headers

AuthorizationstringRequired
ApiKey $ENTROVOX_KEY. Keys are issued per organization.
Idempotency-Keystring or nullOptional
A UUID you generate for each new request. Resending the same key and body returns the original response.

Body

emailstring or null, max 320Optional
external_idstring or null, 1–128Required
Your lead id. Unique per organization; a retry with it replays the lead.
first_namestring, 1–200Required
is_testbooleanOptional
true stores a test lead (a safe hello-world): it is never enrolled, dialed or texted, never blocks a live phone, and is not listed. Read it back by id.

Default false

jornaya_leadidstring or null, max 256Optional
last_namestring, 1–200Required
lead_generated_atstring or nullOptional
lead_source_idstring or nullOptional
metadataobject or nullOptional
Free-form key and value pairs.
owned_line_of_businessstring or null, max 64Optional
phonestring, 1–32Required
phone_altstring or nullOptional
preferred_languagestring or nullOptional

One ofenes

statestring or null, max 64Optional
target_line_of_businessstring or null, max 64Optional
timezonestring or null, max 64Optional
transfer_phonestring or nullOptional
Not supported yet: any value is rejected with 400 VALIDATION_ERROR (param transfer_phone). Qualified leads transfer to the campaign number.
trustedform_cert_urlstring or null, max 512Optional
zip_codestring or null, max 10Optional

Returns

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 absent

Default 0

callsarray of object or nullMay be absent
Every attempt, newest last. On GET /leads/{id} and POST responses.
calls_urlstringAlways present
created_atstring (date-time)Always present
current_dispositionstringAlways present
dedup_statusstring or nullMay be absent
dial_blockerstring or nullMay be absent
disposition_atstring (date-time) or nullMay be absent
emailstring or nullMay be absent
external_idstring or nullMay be absent
first_namestring or nullMay be absent
idstringAlways present
is_dncbooleanMay be absent

Default false

is_testbooleanMay be absent

Default false

jornaya_leadidstring or nullMay be absent
last_attempted_atstring (date-time) or nullMay be absent
last_namestring or nullMay be absent
metadataobjectMay be absent
Free-form key and value pairs.
national_dnc_statusstring or nullMay be absent
next_attempt_atstring (date-time) or nullMay be absent
organization_idstringAlways present
pause_is_queuedbooleanMay be absent

Default false

pausedbooleanMay be absent

Default false

paused_atstring (date-time) or nullMay be absent
paused_reasonstring or nullMay be absent
phonestringAlways present
phone_altstring or nullMay be absent
preferred_languagestring or nullMay be absent
replayedboolean or nullMay be absent
On POST responses: true on a 200 replay.
sequence_statusstring or nullMay be absent
sequence_stepintegerMay be absent

Default 0

statestring or nullMay be absent
status_urlstringAlways present
timezonestring or nullMay be absent
transfer_phonestring or nullMay be absent
Always null for now.
trustedform_cert_urlstring or nullMay be absent
updated_atstring (date-time)Always present
zip_codestring or nullMay be absent

201 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

  • 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.

  • 400DNC_BLOCKED

    The phone is on the Do Not Call list. No lead was created.

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

  • 400SOURCE_PAUSED

    The 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.

  • 400SOURCE_INACTIVE

    The 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.

  • 400CONSENT_INVALID

    trustedform_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.

  • 400CROSS_SELL_PAIR_INVALID

    The 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.

  • 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.

  • 404LEAD_NOT_FOUND

    No lead with that id in your organization.

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

  • 409EXTERNAL_ID_CONFLICT

    The 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.

  • 409LEAD_PHONE_CONFLICT

    A 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.

  • 409IDEMPOTENCY_KEY_REUSED

    The same Idempotency-Key and path came with a different body.

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

  • 409IDEMPOTENCY_IN_PROGRESS

    A 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.

  • 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.