Provision Cartesia Number

curl --request POST \ --url https://api.cartesia.ai/agents/phone-numbers/provision \ --header 'Authorization: Bearer <token>' \ --header 'Cartesia-Version: <cartesia-version>' \ --header 'Content-Type: application/json' \ --data ' { "label": "<string>", "agent_id": "<string>" } '

{ "id": "pn_abc123", "label": "Support line", "number": "+14155551234", "agent": { "id": "agent_abc123", "name": "Customer support" }, "created_at": "2026-03-01T00:00:00Z", "updated_at": "2026-03-01T00:00:00Z" }

Authorizations

Authorization

string

header

required

Cartesia API key (sk_car_...). Get one at play.cartesia.ai/keys.

Headers

Cartesia-Version

enum<string>

required

API version header.

Available options:

2026-03-01

Example:

"2026-03-01"

Body

application/json

Request body for provisioning a new Cartesia-managed phone number.

label

string

required

A human-readable name for the phone number.

agent_id

string

Optional agent ID to assign. Inbound calls to the number will be routed to this agent.

Response

Phone number provisioned.

The number supports inbound calls and outbound calls to US numbers only

string

required

Unique identifier for the phone number.

number

string

required

The phone number in E.164 format (e.g. +14155551234).

agent

object

required

The agent assigned to handle inbound calls, or null if unassigned.

Show child attributes

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.

label

string | null

A human-readable name for the phone number.