Skip to content

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.

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

agent_idstringRequired
agent_overridesobject or nullOptional
from_numberstring or null, 2–20Optional
The caller ID to dial from, in E.164. One of from_number or from_number_id is required; send either one.
from_number_idstring or nullOptional
The id of one of your phone numbers, used as the caller ID. One of from_number_id or from_number is required; send either one.
is_testbooleanOptional

Default false

lead_idstring or nullOptional
lead_source_idstring or nullOptional
lead_source_lead_idstring or nullOptional
metadataobjectOptional
Free-form key and value pairs.
owned_line_of_businessstring or null, max 32Optional
retry_configobject or nullOptional
schedulingobject or nullOptional
target_line_of_businessstring or null, max 32Optional
to_numberstring, 2–20Required
variablesobjectOptional
webhook_eventsarray of stringOptional
webhook_urlstring or null, max 2048Optional

Returns

201 CreatedSuccessful Response

agent_idstringAlways present
created_atstring (date-time)Always present
from_numberstringAlways present
idstringAlways present
scheduled_atstring (date-time) or nullMay be absent
statusstringAlways present
to_numberstringAlways present

Errors

  • 400AGENT_NOT_ACTIVE

    The AI voice agent is not active.

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

  • 400DIAL_BLOCKED

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

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

  • 400FROM_NUMBER_NOT_ACTIVE

    The from number is not active, so it cannot place a call.

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

  • 400FROM_NUMBER_NOT_FOUND

    from_number is not a phone number in your organization.

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

  • 400FROM_NUMBER_QUARANTINED

    The from number is quarantined. Use another number.

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

  • 400LEAD_REFERENCE_MISMATCH

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

  • 400MUTED_TURN_HOLD

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

  • 402CALL_QUOTA_EXCEEDED

    Your plan's included calls are used up. Enable extra calls in Billing.

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

  • 403CALLS_NOT_ALLOWED_ON_BOUND_KEY

    A partner key called POST /calls.

    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.

  • 404LEAD_SOURCE_LEAD_NOT_FOUND

    lead_source_lead_id is not a lead in one of your campaigns.

    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.

  • 404ORGANIZATION_NOT_FOUND

    The organization on this account was not found. Contact us.

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

  • 404PHONE_NUMBER_NOT_FOUND

    No phone number with that id in your organization.

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

  • 404VOICE_AGENT_NOT_FOUND

    No AI voice agent with that id in your organization.

    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.

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

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

  • 422LEAD_IS_TEST

    The lead is a test lead, so it cannot be called.

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

  • 422LEAD_SCREENED_OUT

    The lead check blocked this lead, so no call was placed.

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

  • 429AI_MINUTES_EXHAUSTED

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

  • 502UPSTREAM_ERROR

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