Outbound calls

Queue an outbound AI call

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.

post/outbound-calls

Request

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

Request body

phone_numberstring required

The US number to call. It needs AI-call consent on record and must not be on a Do Not Call list.

contact_namestring nullable
purpose'marketing' | 'informational'

Why an outbound call is made. Telemarketing needs prior express written consent for AI voices.

contextstring[] nullable

Anything the AI should know for the call, like the service they asked about (up to 20 keys).

Example request

{
  "phone_number": "+15125550123",
  "contact_name": "Maria Rivera"
}

Response

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

Example response

{
  "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"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.