> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ringyo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Call

> Initiate a new outbound phone call

## Request

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

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer YOUR_API_KEY`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

### Body Parameters

<ParamField body="phone_number" type="string" required>
  The destination phone number in E.164 format (e.g., `+14155551234`)
</ParamField>

<ParamField body="agent_id" type="string" required>
  The ID of the agent to use for this call
</ParamField>

<ParamField body="from_number" type="string">
  The phone number to call from. Must be a number you own. Defaults to your primary number.
</ParamField>

<ParamField body="metadata" type="object">
  Custom key-value pairs to attach to the call for your reference
</ParamField>

<ParamField body="webhook_url" type="string">
  URL to receive real-time call events. Overrides account-level webhook settings.
</ParamField>

<ParamField body="record" type="boolean" default="true">
  Whether to record the call
</ParamField>

<ParamField body="max_duration" type="integer" default="3600">
  Maximum call duration in seconds (1-3600)
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier for the call
</ResponseField>

<ResponseField name="status" type="string">
  Current status: `queued`, `ringing`, `in_progress`, `completed`, `failed`
</ResponseField>

<ResponseField name="phone_number" type="string">
  The destination phone number
</ResponseField>

<ResponseField name="agent_id" type="string">
  The agent ID used for the call
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the call was created
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.ringyo.ai/v1/calls', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      phone_number: '+14155551234',
      agent_id: 'agent_abc123',
      metadata: {
        customer_id: 'cust_456',
        campaign: 'follow_up'
      }
    })
  });

  const call = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.ringyo.ai/v1/calls',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json',
      },
      json={
          'phone_number': '+14155551234',
          'agent_id': 'agent_abc123',
          'metadata': {
              'customer_id': 'cust_456',
              'campaign': 'follow_up'
          }
      }
  )

  call = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "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"
  }
  ```

  ```json 400 - Bad Request theme={null}
  {
    "error": {
      "code": "invalid_phone_number",
      "message": "Phone number must be in E.164 format"
    }
  }
  ```

  ```json 402 - Insufficient Credits theme={null}
  {
    "error": {
      "code": "insufficient_credits",
      "message": "Your account has insufficient credits for this call"
    }
  }
  ```

  ```json 404 - Agent Not Found theme={null}
  {
    "error": {
      "code": "agent_not_found",
      "message": "The specified agent does not exist"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Code                   | Description                                   |
| ---------------------- | --------------------------------------------- |
| `invalid_phone_number` | Phone number is not in valid E.164 format     |
| `agent_not_found`      | The specified agent\_id does not exist        |
| `insufficient_credits` | Account doesn't have enough credits           |
| `rate_limit_exceeded`  | Too many concurrent calls                     |
| `invalid_from_number`  | The from\_number is not owned by your account |