Outbound calls

Have the AI call someone who agreed to AI calls. Needs outbound:write.

Endpoints

GET/outbound-callsList outbound calls
POST/outbound-callsQueue an outbound AI call
GET/outbound-calls/{outboundCall}Get an outbound call

List outbound calls

GET/outbound-calls

Needs the outbound:write scope

Your outbound AI calls, newest first: the ones you queued and those from speed-to-lead, campaigns and agents.

Query parameters

statusstringOptional
One ofqueuedscheduledblockedconnecting_agentdialingin_progresscompletedno_answervoicemailfailed
sourcestringOptional
What started the call: api, speed_to_lead, campaign or agent_dial. | | |---| | 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. |
One ofspeed_to_leadagent_dialcampaignapi
phone_numberstringOptional
Calls to this number, in any common US format.
Up to 32 characters
sincestring (date-time)Optional
Calls queued at or after this time (ISO 8601).
untilstring (date-time)Optional
Calls queued before this time (ISO 8601).
per_pageintegerOptional
How many items per page, 1 to 100.
Minimum 1 · Maximum 100
cursorstring | nullOptional
The meta.next_cursor (or meta.prev_cursor) of the previous page.
Up to 1024 characters

Returns

Paginated set of OutboundCallResource

dataarray of objectsRequired
linksobjectRequired
metaobjectRequired

Responses

200Paginated set of OutboundCallResource
401The API key is missing, invalid, expired or revoked.
403The key does not have the outbound:write scope.
422Validation error
429Too many requests for this key. Wait for the Retry-After seconds.

curl https://vocenya.com/api/public/v1/outbound-calls \
  -H "Authorization: Bearer $VOCENYA_API_KEY"

Response 200

{
  "data": [
    {
      "id": 1,
      "livemode": true,
      "source": "speed_to_lead",
      "purpose": "marketing",
      "status": "queued",
      "contact_name": "Maria Rivera",
      "phone_number": "+15125550123",
      "blocked_reason": "string",
      "blocked_reason_message": "string",
      "scheduled_for": "string",
      "attempts": 1,
      "answered_at": "2026-10-02T14:03:11+00:00",
      "answered_by": "human",
      "voicemail_left_at": "2026-10-02T14:03:11+00:00",
      "ended_at": "2026-10-02T14:03:11+00:00",
      "duration_seconds": 1,
      "summary": "string",
      "transcript": [
        {
          "role": "string",
          "text": "string"
        }
      ],
      "created_at": "2026-10-02T14:03:11+00:00"
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "path": "string",
    "per_page": 1,
    "next_cursor": "string",
    "prev_cursor": "string"
  }
}

Queue an outbound AI call

POST/outbound-calls

Needs the outbound:write scope

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

phone_numberstringRequired
The US number to call. It needs AI-call consent on record and must not be on a Do Not Call list.
Up to 32 characters
contact_namestring | nullOptional
Up to 255 characters
purposestring | nullOptional
marketing (the default) needs marketing consent. informational is for reminders and follow-ups the person asked for, and the only purpose HIPAA-mode accounts may use.
One ofmarketinginformational
contextarray of strings | nullOptional
Anything the AI should know for the call, like the service they asked about (up to 20 keys).
Up to 20 items

Returns

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

dataobjectRequired
decisionobjectRequired

Responses

202Accepted. decision.allowed is true when the call can ring now; otherwise decision.retry_at says when it will.
401The API key is missing, invalid, expired or revoked.
403The key does not have the outbound:write scope.
422The 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.
429Too many requests for this key. Wait for the Retry-After seconds.

curl -X POST https://vocenya.com/api/public/v1/outbound-calls \
  -H "Authorization: Bearer $VOCENYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone_number": "+15125550123",
  "contact_name": "Maria Rivera",
  "context": {
    "service": "Water heater replacement",
    "preferred_time": "mornings"
  }
}'

Response 202

{
  "data": {
    "id": 88,
    "source": "api",
    "purpose": "marketing",
    "status": "queued",
    "phone_number": "+15125550123"
  },
  "decision": {
    "allowed": false,
    "reason": "outside_hours",
    "message": "It is outside calling hours (8am to 8pm) where that number is.",
    "retry_at": "2026-09-29T08:00:00-05:00"
  }
}

Get an outbound call

GET/outbound-calls/{outboundCall}

Needs the outbound:write scope

Check on a call you queued: its status, why it was blocked or delayed and, once it ended, its transcript (not for HIPAA-mode accounts).

Path parameters

outboundCallintegerRequired
The outbound call id.

Returns

OutboundCallResource

dataobjectRequired

Responses

200OutboundCallResource
401The API key is missing, invalid, expired or revoked.
403The key does not have the outbound:write scope.
404No record with that id belongs to your account.
429Too many requests for this key. Wait for the Retry-After seconds.

curl https://vocenya.com/api/public/v1/outbound-calls/88 \
  -H "Authorization: Bearer $VOCENYA_API_KEY"

Response 200

{
  "data": {
    "id": 1,
    "livemode": true,
    "source": "speed_to_lead",
    "purpose": "marketing",
    "status": "queued",
    "contact_name": "Maria Rivera",
    "phone_number": "+15125550123",
    "blocked_reason": "string",
    "blocked_reason_message": "string",
    "scheduled_for": "string",
    "attempts": 1,
    "answered_at": "2026-10-02T14:03:11+00:00",
    "answered_by": "human",
    "voicemail_left_at": "2026-10-02T14:03:11+00:00",
    "ended_at": "2026-10-02T14:03:11+00:00",
    "duration_seconds": 1,
    "summary": "string",
    "transcript": [
      {
        "role": "string",
        "text": "string"
      }
    ],
    "created_at": "2026-10-02T14:03:11+00:00"
  }
}