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.
Headers
AuthorizationstringRequiredApiKey $ENTROVOX_KEY. Keys are issued per organization.Idempotency-Keystring or nullOptionalBody
lead_source_idstring or nullOptionalleadsarray of objectRequiredReturns
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 presentitemsarray of objectAlways presentlead_source_idstringAlways presentrejectedintegerAlways presentreplayedintegerAlways present201 CreatedSuccessful Response
createdintegerAlways presentdeduplicatedintegerAlways presenterrorsarray of objectMay be absentlead_source_idstringAlways presentErrors
- 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.
- 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.
Any request can also return AUTHENTICATION_REQUIRED, TOKEN_INVALID, API_KEY_EXPIRED, RATE_LIMIT_EXCEEDED or INTERNAL_ERROR.