> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://poly-ai.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://poly-ai.ferndocs.com/_mcp/server.

# Numbers

> Connect phone numbers to your agent using PolyAI, Twilio, or outbound calling

Numbers is how PolyAI connects your agent to the public phone network. Provision a number directly through PolyAI, bring your own Twilio number, or route through your existing contact-centre provider — every option terminates on the same agent runtime so the conversation logic is identical across channels. Manage everything in **Voice > Numbers**.

| Option                                                                    | Best for              | What you get                                               |
| ------------------------------------------------------------------------- | --------------------- | ---------------------------------------------------------- |
| **[Buy a number](/agent-studio/voice/numbers/buy-a-number-from-poly-ai)** | No existing provider  | Purchase directly from PolyAI.                             |
| **[Twilio integration](/agent-studio/voice/numbers/twilio/overview)**     | Existing Twilio setup | Connect your Twilio numbers. Voice, SMS, and Flex routing. |
| **[Outbound calling](/agent-studio/voice/numbers/outbound-calling)**      | Proactive outreach    | Agent-initiated calls through API or SIP.                  |

> **Note**
>
> You can also connect through other contact center platforms like [Genesys](/integrations/telephony/genesys), [Five9](/integrations/telephony/five-9), or [NICE CXone](/integrations/telephony/nice-c-xone) with SIP. See [Integrations](/integrations/integrations/overview) for the full list.

## Integration options

#### [Buy a number](/agent-studio/voice/numbers/buy-a-number-from-poly-ai)

Purchase a number directly from PolyAI.

#### [Twilio integration](/agent-studio/voice/numbers/twilio/overview)

Voice, SMS, and contact center routing with Twilio.

#### [Outbound calling](/agent-studio/voice/numbers/outbound-calling)

Agent-initiated calls for reminders and follow-ups.

## Twilio integration guides

* **[Twilio overview](/agent-studio/voice/numbers/twilio/overview)** – Benefits and setup overview
* **[Phone number integration](/agent-studio/voice/numbers/twilio/phone-number-integration)** – Connect a Twilio-hosted number
* **[SMS integration](/agent-studio/voice/message-templates)** – Set up SMS messaging with Twilio
* **[Twilio Flex integration](/integrations/telephony/twilio)** – Advanced contact center routing

## Outbound calling

Agent-initiated calls for reminders, follow-ups, and notifications.

* **[Outbound calling overview](/agent-studio/voice/numbers/outbound-calling)** – Methods and best practices

- **[Outbound Calling API](/api-reference/runtime-data/outbound-calling-api/overview)** – Programmatically trigger calls
- **[SIP integration](/integrations/managed-services/telephony/custom-sip)** – Route through your SIP infrastructure

## Automate with the Agents API

Telephony plumbing is scriptable too — helpful for bulk provisioning and for reshaping routing as part of a broader deployment.

#### Provision numbers and connectors via the Agents API

Connectors bind phone numbers to voice infrastructure; phone numbers are E.164 strings routed through a connector. The [Agents API](/api-reference/build-deploy/agents-api/overview) has CRUD for both.

**`curl`**

```bash curl
# Import a phone number onto an existing connector
curl -X POST https://api.us.poly.ai/v1/agents/AGENT_ID/telephony/phone-numbers/+442071234567 \
  -H "x-api-key: $POLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "connectorId": "conn_abc123" }'

# Reassign a number to a different connector
curl -X PATCH https://api.us.poly.ai/v1/agents/AGENT_ID/telephony/phone-numbers/+442071234567 \
  -H "x-api-key: $POLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "connectorId": "conn_new456" }'
```

**`Python`**

```python Python
import os, requests

BASE = "https://api.us.poly.ai"
HEADERS = {"x-api-key": os.environ["POLYAI_API_KEY"]}

# Look up which connector serves a given number
resp = requests.post(
    f"{BASE}/v1/agents/{AGENT_ID}/telephony/connectors/lookup",
    headers=HEADERS,
    json={"phoneNumber": "+442071234567"},
)
connector = resp.json()
```

See [Connectors](/api-reference/api-reference/agents/connectors/list) and [Phone numbers](/api-reference/api-reference/agents/phone-numbers/list) for the full endpoint list.

## Related pages

#### [Route management](/agent-studio/voice/numbers/phone-numbers)

Configure how calls are routed to your agent

#### [Integrations](/integrations/integrations/overview)

Connect to Genesys, Five9, NICE, and other platforms

#### [SMS](/agent-studio/voice/message-templates)

Send text messages during voice conversations

#### [Phone number endpoints](/api-reference/api-reference/agents/phone-numbers/list)

Import and reassign numbers via the Agents API.