AI Voice Agents API

Use the AI Voice Agents Public API to start autonomous calls from your server and read their structured results. Agent creation, configuration, knowledge sources and browser testing remain in the Ringee dashboard.

Authentication and base URL

Authenticate every request with the cik_live_… API key from an active Custom Integration:

curl "https://api.ringee.io/api/v1/ai-voice-agents" \
  -H "X-Ringee-Api-Key: cik_live_xxxxxxxx…"

You can instead send the same key as a Bearer credential:

Authorization: Bearer cik_live_xxxxxxxx…

Send the key in exactly one of those headers. A request containing both is rejected.

A Custom Integration API key is a server-side secret. Never expose it in browser code, logs or a client application.

For self-hosting, replace https://api.ringee.io with PUBLIC_BACKEND_URL. The integration determines the user and organization; the API never accepts a client-supplied workspace id as authorization. AI Voice Agents require an organization-scoped Custom Integration. A personal-workspace key is valid for other Public API capabilities but returns 403 on these routes.

Endpoints

Method	Path	Purpose
`GET`	`/api/v1/ai-voice-agents`	List agents and their accepted variables
`GET`	`/api/v1/ai-voice-agents/phone-numbers`	List eligible caller numbers
`POST`	`/api/v1/ai-voice-agents/:agentId/calls`	Start one real, billed call
`GET`	`/api/v1/ai-voice-agents/:agentId/calls`	List calls for one agent
`GET`	`/api/v1/ai-voice-agents/calls/:callId`	Read one normalized call result

List agents

curl "https://api.ringee.io/api/v1/ai-voice-agents?page=1&limit=20&type=appointment_booking" \
  -H "X-Ringee-Api-Key: cik_live_xxxxxxxx…"

page defaults to 1; limit defaults to 20 and cannot exceed 100. type can be appointment_booking or reminders_notifications.

{
  "data": [
    {
      "id": "7c819553-25be-43b5-9fc6-58effe1569f8",
      "name": "Maya",
      "type": "appointment_booking",
      "status": "active",
      "voice": "Carolina",
      "callCount": 14,
      "callerNumberId": "1c93cab1-e97a-42e0-9ddf-e7a87cc950fd",
      "callsFrom": "+13055550100",
      "createdAt": "2026-09-04T14:00:00.000Z",
      "updatedAt": "2026-09-04T14:30:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "callerNumbers": [
    {
      "id": "1c93cab1-e97a-42e0-9ddf-e7a87cc950fd",
      "phoneNumber": "+13055550100",
      "isoCountry": "US",
      "kind": "purchased"
    }
  ],
  "variablesByType": {
    "appointment_booking": [
      {
        "key": "first_name",
        "label": "First name",
        "required": true,
        "description": "The first name of the person being called."
      }
    ]
  }
}

The response excludes provider identifiers, credential references and callback secrets. Resolve agentId, from_number_id and required variables from this response before starting a call.

List caller numbers

GET /api/v1/ai-voice-agents/phone-numbers returns the same callerNumbers entries as the list response, without the surrounding pagination object.

Start a call

curl -X POST "https://api.ringee.io/api/v1/ai-voice-agents/<agentId>/calls" \
  -H "X-Ringee-Api-Key: cik_live_xxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+13055550123",
    "from_number_id": "1c93cab1-e97a-42e0-9ddf-e7a87cc950fd",
    "variables": {
      "first_name": "Carlos",
      "reason": "Product demo"
    },
    "metadata": {
      "external_id": "crm-contact-42"
    }
  }'

Field	Required	Description
`to`	Yes	Destination number. Ringee validates and normalizes it before dialing.
`from_number_id`	No	Eligible caller number. Required if the agent has no assigned or default number.
`variables`	No	String values defined by the agent type. Every required variable must be supplied.
`metadata`	No	Arbitrary correlation data echoed in the result. `external_id` also propagates to related webhooks.

The response returns immediately:

{
  "id": "8ddf384a-9b9d-44dd-a120-23395b1f4c98",
  "status": "initiating"
}

id is the AI Voice Agent call id. Use it with the result endpoints. Outbound webhooks identify the underlying telephony call as data.callId; call.outcome.updated also includes the start-response id as data.agentCallId. Use metadata.external_id when you need one correlation id across every event type. Starting a call is non-idempotent. Each successful request creates a new call and can incur real usage. Do not automatically retry an ambiguous response.

List and read calls

List one agent’s calls with GET /api/v1/ai-voice-agents/:agentId/calls?page=1&limit=20, or read a known result directly:

curl "https://api.ringee.io/api/v1/ai-voice-agents/calls/<callId>" \
  -H "X-Ringee-Api-Key: cik_live_xxxxxxxx…"

Both routes return the normalized public result shape:

{
  "call_id": "8ddf384a-9b9d-44dd-a120-23395b1f4c98",
  "status": "completed",
  "outcome": "meeting_booked",
  "summary": "Carlos agreed to a product demo on Friday at 10:30 AM.",
  "sentiment": "positive",
  "extracted_data": {
    "budget_range": "$5k-$10k"
  },
  "metadata": {
    "external_id": "crm-contact-42"
  }
}

The list route wraps results in { data, total, page, limit }. Post-call analysis can arrive shortly after the phone status becomes terminal, so poll again if summary, sentiment or extracted_data is still empty.

Receive results by webhook

Polling and outbound webhooks can be used together. Subscribe the same Custom Integration to the events you need:

Event	What it reports
`call.completed`	The terminal phone detail for a completed or unanswered call
`call.failed`	A terminal technical failure
`call.outcome.updated`	The normalized public outcome plus `data.call` telephony detail
`callback.created`	A callback the live agent successfully scheduled
`meeting.created`	A meeting the live agent successfully booked
`recording.ready`	The processed recording

When the start request contains metadata.external_id or metadata.externalId, each call-linked event exposes the value as data.externalId. It also includes data.user and the AI Voice Agent reference under data.agent when those actors can be resolved.

The result API and webhook contract use the same canonical outcome names, including meeting_booked and callback_scheduled. Ringee normalizes the historical names appointment_booked and callback_requested before returning them.

Common errors

Status	Meaning
`400`	Invalid pagination, number or variables; no usable caller number; the agent is not ready; or provider failure
`401`	Missing, malformed, unknown or disabled Custom Integration API key, or both supported auth headers were sent
`403`	The integration is personal-scoped, calling is disabled, the number is on DNC or credits are unavailable
`404`	The agent, call or caller number does not belong to the integration’s organization

Configuration stays in the dashboard

The Public API intentionally exposes execution, not agent administration. Create, edit, enable, disable, test and delete agents in the Ringee dashboard, then use their ids from GET /api/v1/ai-voice-agents in your server integration.

Next steps

Authentication

Create and protect a Custom Integration API key

Calls and results

Understand status, outcomes, polling and billing

Outbound webhooks

Receive terminal, outcome and artifact events

Get Started

Build an Agent

Automation

Operations

Authentication and base URL

Endpoints

List agents

List caller numbers

Start a call

List and read calls

Receive results by webhook

Common errors

Configuration stays in the dashboard

Next steps

Authentication

Calls and results

Outbound webhooks

​Authentication and base URL

​Endpoints

​List agents

​List caller numbers

​Start a call

​List and read calls

​Receive results by webhook

​Common errors

​Configuration stays in the dashboard

​Next steps

Authentication

Calls and results

Outbound webhooks

Authentication and base URL

Endpoints

List agents

List caller numbers

Start a call

List and read calls

Receive results by webhook

Common errors

Configuration stays in the dashboard

Next steps