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

# Twilio integration

> Import phone numbers from your Twilio account.

Connect your Twilio account to use your existing numbers, including international numbers, for inbound and outbound calls.

## Prerequisites

* A [Twilio account](https://www.twilio.com/try-twilio) with at least one phone number
* A [Cartesia account](https://play.cartesia.ai) with an API key

## Set up

### Step 1: Create a Twilio subaccount (recommended)

A dedicated subaccount keeps the numbers and credentials you share with Cartesia separate from the rest of your Twilio setup.

1. Open the [Twilio Console](https://console.twilio.com).
2. Go to **Account** → **Subaccounts** → **Create new Subaccount**.
3. Name it, for example `cartesia-production`.
4. Copy the **Account SID**.

<Tip>
  You can also use your main Twilio account. Subaccounts are recommended but not required.
</Tip>

### Step 2: Create an API key

Create a Standard API key in your subaccount. API keys can be rotated independently, which auth tokens cannot.

1. In your subaccount, go to **Account** → **API keys & tokens**, or open the [create page](https://console.twilio.com/us1/account/keys-credentials/api-keys/create) directly.
2. Click **Create API Key** and choose **Standard**.
3. Save the **SID** and **Secret** in a password manager.

<Warning>
  Twilio shows the API key secret once. If you lose it, create a new key.
</Warning>

If you import numbers from more than one Twilio region, create a separate API key for each region. See [Regional routing](/line/integrations/telephony/twilio/regional-routing).

### Step 3: Connect your Twilio account

Cartesia validates the credentials against Twilio before saving them.

<Tabs>
  <Tab title="Playground">
    1. Go to **Phone Numbers**, click **Add Number**, then **Import from Twilio**.
    2. Select **Link new account**.
    3. Enter your Account SID, API Key SID, API Key Secret, and region.

    <Frame caption="Import from Twilio panel with Link new account fields">
      <img src="https://mintcdn.com/cartesia-2650f86a/cyPOLB5BGhebR1Zv/assets/images/agents/telephony/import-from-twilio.png?fit=max&auto=format&n=cyPOLB5BGhebR1Zv&q=85&s=dec025eb32889c5ed3f30473316974f2" alt="Linking a Twilio account in the Playground" width="2872" height="1914" data-path="assets/images/agents/telephony/import-from-twilio.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST "https://api.cartesia.ai/agents/phone-numbers/providers" \
      -H "X-API-Key: $CARTESIA_API_KEY" \
      -H "Cartesia-Version: 2026-08-14" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "twilio",
        "account_sid": "YOUR_TWILIO_ACCOUNT_SID",
        "api_key_sid": "YOUR_API_KEY_SID",
        "api_key_secret": "YOUR_API_KEY_SECRET",
        "region": "us1"
      }'
    ```
  </Tab>
</Tabs>

### Step 4: Import a phone number

The number must already exist in your Twilio account. Cartesia does not purchase numbers on your behalf.

<Tabs>
  <Tab title="Playground">
    1. In the **Import from Twilio** panel, enter the phone number with its country code, for example `+14155551234`.
    2. Give it a name.
    3. Optionally assign an agent. You can also do this later.
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST "https://api.cartesia.ai/agents/phone-numbers" \
      -H "X-API-Key: $CARTESIA_API_KEY" \
      -H "Cartesia-Version: 2026-08-14" \
      -H "Content-Type: application/json" \
      -d '{
        "label": "Support line",
        "number": "+14155551234",
        "provider": { "id": "YOUR_PROVIDER_ID" }
      }'
    ```
  </Tab>
</Tabs>

### Step 5: Assign an agent

Inbound calls on the number are routed to the agent you assign. Assign it from the number's detail page in the Playground or through the [Phone Numbers API](/line/integrations/telephony/phone-numbers#assign-an-inbound-agent). One agent can handle several numbers, for example a US line and a UK line.

<Frame caption="Phone number detail page with agent assignment">
  <img src="https://mintcdn.com/cartesia-2650f86a/cyPOLB5BGhebR1Zv/assets/images/agents/telephony/phone-number-details.png?fit=max&auto=format&n=cyPOLB5BGhebR1Zv&q=85&s=f05407f657941a7a6c9cbda1a8dee44e" alt="Assigning an agent to a phone number" width="2872" height="1042" data-path="assets/images/agents/telephony/phone-number-details.png" />
</Frame>

## Outbound calls

Your agent can call any phone number, including international numbers at your Twilio rates. Use the imported number as `from_number_id` when you [place an outbound call](/line/integrations/telephony/outbound-dialing).

Outbound calls use the credentials of the number's provider. A `us1` provider routes through Twilio's US edge, and an `ie1` provider routes through Ireland. See [Regional routing](/line/integrations/telephony/twilio/regional-routing).

## Rotate credentials

Rotate your Twilio API key without downtime:

1. Create a new API key in Twilio, as in Step 2.
2. Update the provider in Cartesia. Cartesia validates the new credentials and checks that every number on the provider is reachable before applying the change.
3. Revoke the old key in the Twilio console.

<Tabs>
  <Tab title="Playground">
    Go to **Phone Numbers** → **Settings** and update the credentials for your Twilio account.
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X PATCH "https://api.cartesia.ai/agents/phone-numbers/providers/YOUR_PROVIDER_ID" \
      -H "X-API-Key: $CARTESIA_API_KEY" \
      -H "Cartesia-Version: 2026-08-14" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "twilio",
        "api_key_sid": "NEW_API_KEY_SID",
        "api_key_secret": "NEW_API_KEY_SECRET",
        "region": "us1"
      }'
    ```
  </Tab>
</Tabs>

## Remove a number

Unassign an imported number before deleting it. Deleting a number from Cartesia does not remove it from your Twilio account.