Skip to main content

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 phone numbers are scoped to a region through the API credentials used to manage them. This region determines how Twilio API calls are routed — this can help optimize latency by directing region-specific traffic to a regional Cartesia cluster.

​
How It Works

When you import a Twilio phone number into Cartesia:
  1. Twilio routes the call regionally: Twilio directs incoming calls to the region configured on the API key managing that number — us1, ie1 (Ireland), or au1 (Australia).
  2. Cartesia must target the same region: To act on a live call (transfers, hold, hangup), Cartesia sends API requests back to Twilio. These requests must reach the same region where Twilio is handling the call.
  3. Setting the region on the provider keeps both sides aligned: When you specify a region on your Cartesia provider, all outgoing API requests from Cartesia automatically target the correct Twilio regional edge.
The region is tied to the provider’s API credentials, not the phone number’s country code or your agent’s deployment region. A UK number (+44...) under a us1 provider may route to a US Twilio server. To route it through the closest server instead, create it under an ie1 (Ireland) API key.
If the region is missing or incorrect, operations like transfers and outbound calls fail. The region on Twilio credentials must match the region specified in Cartesia.

​
Configuration

1

Check your Twilio region

In the Twilio Console, go to Phone Numbers → Manage → Active numbers, select your number, and check the Edge Location under Voice & Fax.Supported regions: us1 (US, default), ie1 (Ireland), au1 (Australia).
2

Set the region in Twilio (if needed)

If the edge location doesn’t match your desired region, update it in the Voice & Fax section of your phone number configuration and save.
Non-default regions require a region-specific API key from Twilio. A standard US key will not work for ie1 or au1 routing and will result in authentication errors.
3

Match the region in Cartesia

When you create a provider or import a phone number, set the region field to match your Twilio configuration. If the regions don’t match, mid-call operations like transfers will fail with authentication errors.For non-US regions, you must use a region-specific Twilio API key — a standard US key will not work.

​
Setting Up Multi-Region

If you operate in multiple Twilio regions, create a separate provider object for each:
  1. In your Twilio account, create a region-specific API key (see Integration guide, Step 2)
  2. Link the same Twilio Account SID with each region:
# US region
curl -X POST "https://api.cartesia.ai/agents/phone-numbers/providers" \
  -H "Authorization: Bearer $CARTESIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Cartesia-Version: 2026-03-01" \
  -d '{
    "type": "twilio",
    "account_sid": "YOUR_TWILIO_ACCOUNT_SID",
    "api_key_sid": "US_API_KEY_SID",
    "api_key_secret": "US_API_KEY_SECRET",
    "region": "us1"
  }'

# Ireland region
curl -X POST "https://api.cartesia.ai/agents/phone-numbers/providers" \
  -H "Authorization: Bearer $CARTESIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Cartesia-Version: 2026-03-01" \
  -d '{
    "type": "twilio",
    "account_sid": "YOUR_TWILIO_ACCOUNT_SID",
    "api_key_sid": "IE_API_KEY_SID",
    "api_key_secret": "IE_API_KEY_SECRET",
    "region": "ie1"
  }'
Each Account SID + region pair is unique. Import phone numbers under the provider matching their intended routing region.

​
Troubleshooting

SymptomCauseFix
Outbound call fails with auth errorAPI key region doesn’t match the provider region in CartesiaVerify the region on the provider matches the region your Twilio API key was created for
Calls route through the wrong regionPhone number imported under wrong providerUpdate the phone number’s provider via PATCH /agents/phone-numbers/{id} with the correct provider ID
Credential update rejected with unreachable numbersNew API key can’t access phone numbers in the provider’s regionEnsure the new key has access to all numbers. Twilio returns the list of unreachable numbers in the error response