Phone Numbers - Cartesia Docs

Cartesia supports two ways to connect phone numbers to your agents: Cartesia-provisioned numbers and Twilio (bring your own) numbers.

Feature	Cartesia Numbers	Twilio Numbers
Number origin	US only	Any country available in Twilio
Inbound calls	✓	✓
Outbound to US	✓	✓
Outbound international	✗	✓ (at your Twilio cost)
Regional routing	N/A	Configurable
Provisioning	Automatic	Import from Twilio
Cost	Included in plan	Your Twilio usage rates

Cartesia Numbers

Cartesia provisions US phone numbers tied to your subscription plan. Provision numbers from the Playground or via the API and assign them to agents immediately. See the Cartesia Numbers guide for setup and management.

Twilio Numbers (Bring Your Own)

Import phone numbers from your Twilio account for full international support, including inbound and outbound calling to any destination supported by Twilio. See the Twilio Integration guide for step-by-step setup.

Managing Numbers

View and manage all your phone numbers — both Cartesia and Twilio — in the Phone Numbers dashboard, via the Phone Numbers API, or with the CLI.

Phone Numbers tab listing numbers in the Playground

List all phone numbers from the CLI:

cartesia phone-numbers ls

Filter by provider type or agent:

cartesia phone-numbers ls --type twilio
cartesia phone-numbers ls --agent-id <agent-id>

Assigning an Agent

Assigning a phone number to an agent routes inbound calls on that number to the agent. A number can only be assigned to one agent at a time, but an agent can have multiple numbers route to it.

Playground
CLI
API

Click on a phone number to open its detail page
In the Agent card, search for and select your agent

cartesia phone-numbers assign <phone-number-id> --agent-id <agent-id>

To unassign a number from its agent:

cartesia phone-numbers unassign <phone-number-id>

curl -X PATCH "https://api.cartesia.ai/agents/phone-numbers/YOUR_PHONE_NUMBER_ID" \
  -H "Authorization: Bearer $CARTESIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Cartesia-Version: 2026-03-01" \
  -d '{
    "agent_id": "YOUR_AGENT_ID"
  }'

To unassign, set agent_id to null.

​Cartesia Numbers

​Twilio Numbers (Bring Your Own)

​Managing Numbers

​Assigning an Agent

Cartesia Numbers

Twilio Numbers (Bring Your Own)

Managing Numbers

Assigning an Agent