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

# Trigger an outbound call

> Initiate an outbound call to a phone number

Triggers a new outbound call to the specified phone number. When the request is accepted, the call is placed close to immediately.

The API should only be called to make a call. The call is always attempted, and the [start tool](/tools/start-tool) (`start_function`) is executed **after** the call connects.

<Warning>
  It is your responsibility to ensure that calls are placed in compliance with applicable laws and regulations.
</Warning>

## Request

### Headers

<ParamField header="X-PolyAi-Auth-Token" type="string" required>
  Authentication token provided by your PolyAI representative
</ParamField>

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

### Body

<ParamField body="to_number" type="string" required>
  Phone number to call. Provide it in E.164 format (e.g., `+14155552671`), or supply `country_code` and pass a national-format number for that country.
</ParamField>

<ParamField body="country_code" type="string">
  Optional ISO 3166-1 alpha-2 country code (e.g., `US`, `GB`) used to parse a non-E.164 `to_number`. Leave unset when `to_number` is already in E.164 format.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key/value pairs to attach to the call. **All values must be strings.** The base64 representation of the metadata must be less than 26 KB.

  Each key is delivered to the agent as a SIP header and can be read inside `start_function` (or any tool) with:

  ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  conv.sip_headers.get('key_name')
  ```
</ParamField>

<ParamField body="encryption" type="string" default="TLS/SRTP">
  Telephony encryption type for the outbound leg. One of:

  * `TLS/SRTP` (default)
  * `TLS/RTP`
  * `UDP/SRTP`
  * `UDP/RTP`
</ParamField>

## Response

<ResponseField name="call_sid" type="string">
  Unique identifier for the triggered call. Always prefixed with `OUT-`. Use this to check call status.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.us-1.platform.polyai.app/v1/outbound-calling \
    -H "X-PolyAi-Auth-Token: YOUR_AUTH_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "to_number": "+16176451984",
      "metadata": {
        "patient_first_name": "Paul",
        "patient_last_name": "Glynn",
        "patient_dob": "1981-August-26",
        "referred_by_name": "Dr. Alex Deerman",
        "variant": "Inpatient at St Charles",
        "patient_address_street": "13 Main Street",
        "patient_city_state": "Colonia, New Jersey",
        "patient_zip_code": "07676"
      }
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  url = "https://api.us-1.platform.polyai.app/v1/outbound-calling"
  headers = {
      "X-PolyAi-Auth-Token": "YOUR_AUTH_TOKEN",
      "Content-Type": "application/json"
  }
  payload = {
      "to_number": "+16176451984",
      "metadata": {
          "patient_first_name": "Paul",
          "patient_last_name": "Glynn",
          "patient_dob": "1981-August-26",
          "referred_by_name": "Dr. Alex Deerman",
          "variant": "Inpatient at St Charles",
          "patient_address_street": "13 Main Street",
          "patient_city_state": "Colonia, New Jersey",
          "patient_zip_code": "07676"
      }
  }

  response = requests.post(url, json=payload, headers=headers)
  call_sid = response.json()["call_sid"]
  print(f"Call triggered: {call_sid}")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    'https://api.us-1.platform.polyai.app/v1/outbound-calling',
    {
      method: 'POST',
      headers: {
        'X-PolyAi-Auth-Token': 'YOUR_AUTH_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        to_number: '+16176451984',
        metadata: {
          patient_first_name: 'Paul',
          patient_last_name: 'Glynn',
          patient_dob: '1981-August-26'
        }
      })
    }
  );

  const data = await response.json();
  console.log('Call triggered:', data.call_sid);
  ```
</CodeGroup>

## Response example

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "call_sid": "OUT-550e8400-e29b-41d4-a716-446655440000"
}
```

## Error responses

<ResponseField name="400 Bad Request">
  Invalid request parameters – for example, an unparseable `to_number`, a metadata value that isn't a string, or metadata that exceeds the 26 KB base64 size limit.
</ResponseField>

<ResponseField name="401 Unauthorized">
  Invalid or missing authentication token, or the connector behind the token is not configured for outbound calling.
</ResponseField>

<ResponseField name="500 Internal Server Error">
  Failed to place the outbound call. Retry with exponential backoff.
</ResponseField>

## Notes

* Phone numbers must be in E.164 format unless you also pass `country_code`.
* All `metadata` values must be strings; nested objects, numbers, and booleans are rejected.
* Use the [Get call status](/api-reference/outbound/endpoint/get-call-status) endpoint to monitor call progress.
* Call status data is retained for approximately 2 hours after the call ends.