Calls
Create a call
POST/v1/calls
Initiate an outbound call with a specific AI voice agent.
Not available to campaign-bound partner keys, which post leads instead (POST /v1/leads).
Pass an Idempotency-Key header to make retries safe: a repeated key with the same body returns the original response instead of placing a second call. The same key with a different body is refused with 409 IDEMPOTENCY_KEY_REUSED.
Headers
AuthorizationstringRequiredApiKey $ENTROVOX_KEY. Keys are issued per organization.Idempotency-Keystring or nullOptionalBody
agent_idstringRequiredagent_overridesobject or nullOptionalfrom_numberstring or null, 2–20Optionalfrom_number_idstring or nullOptionalis_testbooleanOptionalDefault false
lead_idstring or nullOptionallead_source_idstring or nullOptionallead_source_lead_idstring or nullOptionalmetadataobjectOptionalowned_line_of_businessstring or null, max 32Optionalretry_configobject or nullOptionalschedulingobject or nullOptionaltarget_line_of_businessstring or null, max 32Optionalto_numberstring, 2–20RequiredvariablesobjectOptionalwebhook_eventsarray of stringOptionalwebhook_urlstring or null, max 2048OptionalReturns
201 CreatedSuccessful Response
agent_idstringAlways presentcreated_atstring (date-time)Always presentfrom_numberstringAlways presentidstringAlways presentscheduled_atstring (date-time) or nullMay be absentstatusstringAlways presentto_numberstringAlways presentErrors
- 400
AGENT_NOT_ACTIVEThe AI voice agent is not active.
Retrying will fail the same way. Fix the request, or contact us.
- 400
DIAL_BLOCKEDThe call cannot be placed now. details.reason says why. Retry later for outside_calling_hours, outside_transfer_hours_flag_off, org_holiday, the tcpa_* window reasons and same_phone_inflight: at details.next_attempt_local when present, otherwise when your agency's calling hours reopen, or after the current call to that number ends. Do not retry for org_calling_hours_invalid, org_invalid_timezone, tcpa_missing_timezone, tcpa_invalid_timezone or a cross-sell reason: fix your agency settings or the lead first.
Retry after the time in details.next_attempt_local when present. Otherwise retry when the blocking condition ends, as the meaning says.
- 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
FROM_NUMBER_NOT_ACTIVEThe from number is not active, so it cannot place a call.
Retrying will fail the same way. Fix the request, or contact us.
- 400
FROM_NUMBER_NOT_FOUNDfrom_number is not a phone number in your organization.
Retrying will fail the same way. Fix the request, or contact us.
- 400
FROM_NUMBER_QUARANTINEDThe from number is quarantined. Use another number.
Retrying will fail the same way. Fix the request, or contact us.
- 400
LEAD_REFERENCE_MISMATCHlead_id or lead_source_id does not belong to the enrollment named in the request.
Retrying will fail the same way. Fix the request, or contact us.
- 400
MUTED_TURN_HOLDA recent call to this number has an unreviewed muted turn pending compliance review. Retry after the hold resolves.
Retry after the time in details.next_attempt_local when present. Otherwise retry when the blocking condition ends, as the meaning says.
- 402
CALL_QUOTA_EXCEEDEDYour plan's included calls are used up. Enable extra calls in Billing.
Retrying will fail the same way. Fix the request, or contact us.
- 403
CALLS_NOT_ALLOWED_ON_BOUND_KEYA partner key called POST /calls.
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.
- 404
LEAD_SOURCE_LEAD_NOT_FOUNDlead_source_lead_id is not a lead in one of your campaigns.
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
ORGANIZATION_NOT_FOUNDThe organization on this account was not found. Contact us.
Retrying will fail the same way. Fix the request, or contact us.
- 404
PHONE_NUMBER_NOT_FOUNDNo phone number with that id in your organization.
Retrying will fail the same way. Fix the request, or contact us.
- 404
VOICE_AGENT_NOT_FOUNDNo AI voice agent with that id in your organization.
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.
- 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.
- 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.
- 422
LEAD_IS_TESTThe lead is a test lead, so it cannot be called.
Retrying will fail the same way. Fix the request, or contact us.
- 422
LEAD_SCREENED_OUTThe lead check blocked this lead, so no call was placed.
Retrying will fail the same way. Fix the request, or contact us.
- 429
AI_MINUTES_EXHAUSTEDThe monthly AI minutes limit is reached. Unlike RATE_LIMIT_EXCEEDED, this 429 has no Retry-After and will not clear until the plan's minutes reset. Upgrade the plan or wait.
Retrying will fail the same way. Fix the request, or contact us.
- 502
UPSTREAM_ERRORBilling is not set up for your account, so the call was not placed. Contact us.
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.