Skip to main content
POST
/
v1
/
calls
curl -X POST https://api.ringyo.ai/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "agent_id": "agent_abc123",
    "metadata": {
      "customer_id": "cust_456",
      "campaign": "follow_up"
    }
  }'

{
  "id": "call_xyz789",
  "status": "queued",
  "phone_number": "+14155551234",
  "from_number": "+18005551234",
  "agent_id": "agent_abc123",
  "metadata": {
    "customer_id": "cust_456",
    "campaign": "follow_up"
  },
  "record": true,
  "created_at": "2024-01-15T10:30:00Z"
}

​
Request

Initiate an outbound call to a phone number using a specified agent.

​
Headers

​
Authorization
string
required
Bearer token for authentication. Format: Bearer YOUR_API_KEY
​
Content-Type
string
required
Must be application/json

​
Body Parameters

​
phone_number
string
required
The destination phone number in E.164 format (e.g., +14155551234)
​
agent_id
string
required
The ID of the agent to use for this call
​
from_number
string
The phone number to call from. Must be a number you own. Defaults to your primary number.
​
metadata
object
Custom key-value pairs to attach to the call for your reference
​
webhook_url
string
URL to receive real-time call events. Overrides account-level webhook settings.
​
record
boolean
default:"true"
Whether to record the call
​
max_duration
integer
default:"3600"
Maximum call duration in seconds (1-3600)

​
Response

​
id
string
Unique identifier for the call
​
status
string
Current status: queued, ringing, in_progress, completed, failed
​
phone_number
string
The destination phone number
​
agent_id
string
The agent ID used for the call
​
created_at
string
ISO 8601 timestamp of when the call was created
curl -X POST https://api.ringyo.ai/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "agent_id": "agent_abc123",
    "metadata": {
      "customer_id": "cust_456",
      "campaign": "follow_up"
    }
  }'

{
  "id": "call_xyz789",
  "status": "queued",
  "phone_number": "+14155551234",
  "from_number": "+18005551234",
  "agent_id": "agent_abc123",
  "metadata": {
    "customer_id": "cust_456",
    "campaign": "follow_up"
  },
  "record": true,
  "created_at": "2024-01-15T10:30:00Z"
}

​
Error Codes

CodeDescription
invalid_phone_numberPhone number is not in valid E.164 format
agent_not_foundThe specified agent_id does not exist
insufficient_creditsAccount doesn’t have enough credits
rate_limit_exceededToo many concurrent calls
invalid_from_numberThe from_number is not owned by your account