---
title: "Queue an outbound AI call"
method: POST
path: "/outbound-calls"
tags: ["Outbound calls"]
---

# Queue an outbound AI call

`POST /outbound-calls`

## Request

- Base URL: `https://vocenya.com/api/public/v1`
- URL: `https://vocenya.com/api/public/v1/outbound-calls`
- Auth: HTTP bearer

Queue an AI call. Every call is checked against the same rules as calls from the portal:
the number must have AI-call consent on record (marketing consent for `marketing` calls) and
must not be on your or GH's Do Not Call list. Those refusals return 422 with the `decision`.

A call that cannot ring right now (outside 8am to 8pm where the number is, three calls in the
last 24 hours, or already on a call) is still accepted: `decision.retry_at` says when it will
ring. Asking again for a number that is still waiting returns the same call.

With a test key (`vk_test_`) the call is checked exactly the same way (against your test Do Not
Call list and test consents), except the free trial's AI minutes, and is then simulated: it never
rings anyone, moves from `queued` to `in_progress` to `completed` with a sample transcript within
a few seconds, and sends `outbound_call.completed` to your test webhook endpoints.

## Request body

- StoreOutboundCallRequest
  - `phone_number` string, required: The US number to call. It needs AI-call consent on record and must not be on a Do Not Call list.
  - `contact_name` string, nullable
  - `purpose` 'marketing' | 'informational': Why an outbound call is made. Telemarketing needs prior express written consent for AI voices.
  - `context` string[], nullable: Anything the AI should know for the call, like the service they asked about (up to 20 keys).

## Response `202`

Accepted. `decision.allowed` is true when the call can ring now; otherwise `decision.retry_at` says when it will.

- object
  - `data` OutboundCallResource, required
    - `id` integer, required
    - `livemode` boolean, required: `true` for live data, `false` for test data (created with a `vk_test_` key).
    - `source` 'speed_to_lead' | 'agent_dial' | 'campaign' | 'api', required: | | |---| | `speed_to_lead` <br/> The AI calls back someone who just asked to be contacted. | | `agent_dial` <br/> A GH Live agent dials a number by hand from the workspace. | | `campaign` <br/> The AI works through a client's campaign contact list. | | `api` <br/> The client's own system queued an AI call through the public API or platform MCP server. |
    - `purpose` 'marketing' | 'informational', required: Why an outbound call is made. Telemarketing needs prior express written consent for AI voices.
    - `status` 'queued' | 'scheduled' | 'blocked' | 'connecting_agent' | 'dialing' | 'in_progress' | 'completed' | 'no_answer' | 'voicemail' | 'failed', required
    - `contact_name` string, nullable, required
    - `phone_number` string, required
    - `blocked_reason` string, nullable, required: Why the call was blocked or delayed, as a code.
    - `blocked_reason_message` string, nullable, required: Why the call was blocked or delayed, in words.
    - `scheduled_for` string, nullable, required: When a delayed call is due to ring (calling hours, daily limit).
    - `attempts` integer, required
    - `answered_at` string, nullable, required
    - `answered_by` 'human' | 'machine' | 'unknown', required: Who the carrier's answering machine detection heard pick up an outbound AI call. Null when detection gave no result.
    - `voicemail_left_at` string, nullable, required: When the AI finished leaving a message on voicemail, under the account's "leave a message" setting.
    - `ended_at` string, nullable, required
    - `duration_seconds` integer, nullable, required
    - `summary` string, nullable: The AI's summary of the call. Not included for HIPAA-mode accounts.
    - `transcript` object[], nullable: The conversation, turn by turn. Only on `GET /outbound-calls/{id}`, and never for HIPAA-mode accounts.
      - `role` string, required
      - `text` string, required
    - `created_at` string, nullable, required
  - `decision` object, required
    - `allowed` boolean, required
    - `reason` string, nullable, required
    - `message` string, nullable, required
    - `retry_at` string, nullable, required

## Other responses

- `401`: The API key is missing, invalid, expired or revoked.
- `403`: The key does not have the `outbound:write` scope.
- `422`: The call can never be placed: `do_not_call`, `no_consent`, `invalid_number`, `outbound_disabled`, `service_inactive`, `terms_not_accepted`, `hipaa_marketing`, `trial_minutes_exhausted` (the free trial's included AI minutes are used up) or `no_receptionist`.
- `429`: Too many requests for this key. Wait for the `Retry-After` seconds.

---

[API](https://skmtc.dev/vocenya/apis/vocenya-api.md) · [All operations](https://skmtc.dev/vocenya/apis/vocenya-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vocenya/apis/vocenya-api/revisions/946913941565?raw)