Skip to content

Leads

Create leads in a batch

POST/v1/leads/batch

Post up to 500 leads.

API keys: 200 with items, one per input row in order, whatever the mix of created / replayed / conflict / rejected. A row with code PROVIDER_UNAVAILABLE created nothing and is safe to resend in a new batch. Send an Idempotency-Key (UUID) to replay the whole response on a retry.

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

lead_source_idstring or nullOptional
Campaign id. Optional when the key is bound to a campaign.
leadsarray of objectRequired

Returns

200 OKAlways, when the request itself is well-formed: partial success is in items, one per input row in input order (a batch where every row failed is still 200). A row with code PROVIDER_UNAVAILABLE created nothing and is safe to resend in a new batch; its external_id makes that idempotent. A retry with the same Idempotency-Key and body returns this response unchanged (X-Idempotency-Replayed: true).

createdintegerAlways present
itemsarray of objectAlways present
lead_source_idstringAlways present
rejectedintegerAlways present
Rows with status rejected or conflict.
replayedintegerAlways present

201 CreatedSuccessful Response

createdintegerAlways present
deduplicatedintegerAlways present
errorsarray of objectMay be absent
lead_source_idstringAlways present

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.

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

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