---
title: "Import Phone Number"
method: POST
path: "/agents/phone-numbers"
tags: ["Phone Numbers"]
---

# Import Phone Number

`POST /agents/phone-numbers`

## Headers

- `Cartesia-Version` '2026-03-01', date, required

## Request body

- ImportPhoneNumberBody — Request body for importing a phone number from an existing provider. The number of Cartesia phone numbers is limited by your subscription plan.
  - `label` string, required — A human-readable name for the phone number.
  - `number` string, required — The phone number in E.164 format.
  - `provider` union, required — Reference to the provider. Pass `{ "id": "..." }` for an existing provider, or `{ "type": "twilio", "account_sid": "...", "region": "..." }` to look up by account.
    - object
      - `id` string, required
    - object
      - `type` 'twilio', required
      - `account_sid` string, required
      - `region` 'us1' | 'ie1' | 'au1' — The Twilio region the phone number and API key are configured for. `us1` (US), `ie1` (Ireland), `au1` (Australia). Default is `us1`.
  - `agent_id` string — Optionally assign an agent to answer inbound calls to this number. Omit to keep the number outbound-only.

## Response `201`

Phone number imported.

- PhoneNumberResponse — Common phone number fields.
  - `id` string, required — Unique identifier for the phone number.
  - `label` string, nullable — A human-readable name for the phone number.
  - `number` string, required — The phone number in E.164 format (e.g. +14155551234).
  - `agent` object, nullable, required — The agent that answers inbound calls to this number, or `null` if unassigned
    - `id` string, required
    - `name` string, required
  - `created_at` string, date-time, required — UTC timestamp when the phone number was created.
  - `updated_at` string, date-time, required — UTC timestamp when the phone number was last updated.
  - `provider` union, required — The telephony provider associated with a phone number. One of `Twilio` or `Cartesia`, determined by the `type` field.
    - TwilioProviderResponse — A linked Twilio account. The `api_key_sid` field is partially masked in responses.
      - `type` 'twilio', required — Always `"twilio"`.
      - `id` string, required — Unique identifier for the provider.
      - `account_sid` string, required — The Twilio account SID.
      - `api_key_sid` string, required — The Twilio API key SID (partially masked).
      - `region` 'us1' | 'ie1' | 'au1', required — The Twilio region the phone number and API key are configured for. `us1` (US), `ie1` (Ireland), `au1` (Australia). Default is `us1`.
    - CartesiaProviderResponse — A Cartesia-managed provider. US phone numbers only.
      - `type` 'cartesia', required — Always `"cartesia"`.

## Other responses

- `400` — Import failed. Possible reasons: phone number not found in the provider account, Twilio lookup failed, provider credentials incomplete, webhook configuration failed (number imported but agent not assigned — retry via PATCH), or unsupported provider type.
- `404` — Provider or agent not found.
- `409` — Phone number has already been imported.

---

[API](https://skmtc.net/cartesia/apis/cartesia-api.md) · [All operations](https://skmtc.net/cartesia/apis/cartesia-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cartesia/cartesia-api/revisions/8910812440d3/schema)