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

# Outbound phone calls

> Dial through an assigned provider number and interpret the accepted request.

## Purpose

This contract applies to connected provider phone numbers. SIP uses its [own outbound operation](/docs/api-reference/agent-runtime/voice/sip/outbound). Use [Start an outbound call](/docs/guides/developers/voice/outbound-calls) for the complete task.

## Authentication

Use a Voiceflow API key with access to read the assigned agent and its versions. SIP digest credentials and socket session keys do not authorize this request. Keep the key on your server.

## Operations

#### Place an outbound phone call

Dial through an assigned Twilio, Vonage, Telnyx or Voiceflow-provisioned number. Success confirms the provider dial request was accepted, not that the customer answered. No call ID or JSON response is returned.

##### Endpoint

```http
POST /v1/phone-number/{phoneNumberID}/outbound
```

Server: https://runtime-api.voiceflow.com

##### Authentication

```json
[
  {
    "ApiKeyAuth": []
  }
]
```

`ApiKeyAuth`:

```json
{
  "type": "apiKey",
  "in": "header",
  "name": "Authorization",
  "description": "A Voiceflow API key authorized for project:READ and project.versions:READ on the connection's assigned agent. Keep the key server-side. SIP digest credentials and Socket.IO session keys do not authorize this request."
}
```

##### Path parameters

###### `phoneNumberID`

Required · string

ID of an assigned phone number, not the E.164 number or project ID.

```json
{
  "type": "string"
}
```

##### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "to"
        ],
        "properties": {
          "to": {
            "type": "string",
            "description": "Destination in E.164 format.",
            "example": "+14165550123"
          },
          "variables": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Initial agent variables. Values must be strings."
          },
          "amd": {
            "type": "boolean",
            "default": true,
            "description": "Answering-machine detection. Twilio ends the call on machine_end_beep or fax; Telnyx requests detect_beep. The inspected Vonage consumer does not apply this field. This is not a configurable voicemail message."
          },
          "overrides": {
            "type": "object",
            "additionalProperties": true,
            "description": "Provider-specific options consumed by Twilio. No common provider-independent option schema. Omit unless using a verified Twilio option."
          }
        }
      }
    }
  }
}
```

##### Responses

###### 201

Dial request accepted. Empty response body.

###### 400

Invalid destination; connection not assigned; outbound settings incomplete; or connection not ready for outbound calls. Check the destination and saved connection settings before retrying.

###### 402

Workspace credit limit reached.

###### 404

Phone number not found.

###### 429

Production concurrency limit reached. Wait for capacity before retrying.

##### Request examples

###### cURL

```bash
curl --request POST \
  --url 'https://runtime-api.voiceflow.com/v1/phone-number/<phoneNumberID>/outbound' \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "to": "+14165550123",
  "variables": {},
  "amd": true,
  "overrides": {}
}'
```

###### JavaScript

```javascript
const response = await fetch('https://runtime-api.voiceflow.com/v1/phone-number/<phoneNumberID>/outbound', {
  method: 'POST',
  headers: {
    Authorization: '<api-key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "to": "+14165550123",
    "variables": {},
    "amd": true,
    "overrides": {}
  }),
});
// This operation returns no response body.
console.log(response.status);
```

###### Python

```python
import requests

response = requests.post(
    'https://runtime-api.voiceflow.com/v1/phone-number/<phoneNumberID>/outbound',
    headers={'Authorization': '<api-key>'},
    json={
      "to": "+14165550123",
      "variables": {},
      "amd": True,
      "overrides": {}
    },
)
response.raise_for_status()
# This operation returns no response body.
```

## Provider differences

| Connection | Initial variables | Answering-machine behavior |
| --- | --- | --- |
| Twilio | String-valued map | `amd` defaults to true; machine-end-beep or fax ends the call. |
| Vonage | String-valued map | The outbound consumer does not apply `amd` or `overrides`. |
| Telnyx | String-valued map | When enabled, AMD requests provider `detect_beep`; this does not define a configurable voicemail-message workflow. |
| SIP | Not accepted by the SIP outbound route | No `amd` request field. |

Provider-specific `overrides` are consumed by Twilio; they are not a portable configuration object. A successful request does not establish that a human answered. Voiceflow-provisioned numbers also support outbound calling.

## Minimal request

```json title="Phone-number request body"
{"to":"+14165550123","variables":{"order_number":"1042"},"amd":false}
```

## Errors and recovery

A 400 reports an invalid destination, connection or provider failure; 402 means workspace credits are exhausted; 429 means production concurrency is full. An HTTP timeout after sending does not prove the provider failed to dial. Inspect the call before retrying.
