Update Phone Number

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

import requests

url = "https://api.cartesia.ai/agents/phone-numbers/{id}"

payload = {
    "label": "<string>",
    "agent_id": "<string>",
    "provider": { "id": "<string>" }
}
headers = {
    "Cartesia-Version": "<cartesia-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    'Cartesia-Version': '<cartesia-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({label: '<string>', agent_id: '<string>', provider: {id: '<string>'}})
};

fetch('https://api.cartesia.ai/agents/phone-numbers/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cartesia.ai/agents/phone-numbers/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'label' => '<string>',
    'agent_id' => '<string>',
    'provider' => [
        'id' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Cartesia-Version: <cartesia-version>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cartesia.ai/agents/phone-numbers/{id}"

	payload := strings.NewReader("{\n  \"label\": \"<string>\",\n  \"agent_id\": \"<string>\",\n  \"provider\": {\n    \"id\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Cartesia-Version", "<cartesia-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.cartesia.ai/agents/phone-numbers/{id}")
  .header("Cartesia-Version", "<cartesia-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"label\": \"<string>\",\n  \"agent_id\": \"<string>\",\n  \"provider\": {\n    \"id\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cartesia.ai/agents/phone-numbers/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Cartesia-Version"] = '<cartesia-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"label\": \"<string>\",\n  \"agent_id\": \"<string>\",\n  \"provider\": {\n    \"id\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "number": "<string>",
  "agent": {
    "id": "<string>",
    "name": "<string>"
  },
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "provider": {
    "type": "twilio",
    "id": "<string>",
    "account_sid": "<string>",
    "api_key_sid": "<string>",
    "region": "us1",
    "label": "<string>"
  },
  "label": "<string>"
}

PATCH

agents

phone-numbers

{id}

Update Phone Number

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

import requests

url = "https://api.cartesia.ai/agents/phone-numbers/{id}"

payload = {
    "label": "<string>",
    "agent_id": "<string>",
    "provider": { "id": "<string>" }
}
headers = {
    "Cartesia-Version": "<cartesia-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    'Cartesia-Version': '<cartesia-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({label: '<string>', agent_id: '<string>', provider: {id: '<string>'}})
};

fetch('https://api.cartesia.ai/agents/phone-numbers/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cartesia.ai/agents/phone-numbers/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'label' => '<string>',
    'agent_id' => '<string>',
    'provider' => [
        'id' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Cartesia-Version: <cartesia-version>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cartesia.ai/agents/phone-numbers/{id}"

	payload := strings.NewReader("{\n  \"label\": \"<string>\",\n  \"agent_id\": \"<string>\",\n  \"provider\": {\n    \"id\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Cartesia-Version", "<cartesia-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.cartesia.ai/agents/phone-numbers/{id}")
  .header("Cartesia-Version", "<cartesia-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"label\": \"<string>\",\n  \"agent_id\": \"<string>\",\n  \"provider\": {\n    \"id\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cartesia.ai/agents/phone-numbers/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Cartesia-Version"] = '<cartesia-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"label\": \"<string>\",\n  \"agent_id\": \"<string>\",\n  \"provider\": {\n    \"id\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "number": "<string>",
  "agent": {
    "id": "<string>",
    "name": "<string>"
  },
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "provider": {
    "type": "twilio",
    "id": "<string>",
    "account_sid": "<string>",
    "api_key_sid": "<string>",
    "region": "us1",
    "label": "<string>"
  },
  "label": "<string>"
}

Authorizations

Authorization

string

header

default:$CARTESIA_API_KEY

required

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

Headers

Cartesia-Version

enum<string>

default:2026-03-01

required

API version header.

Available options:

2026-03-01

Example:

"2026-03-01"

Path Parameters

string

required

The phone number ID.

Body

application/json

Fields to update on a phone number. All fields are optional. Set agent_id to null to unassign the current agent.

label

string

A new human-readable name.

agent_id

string | null

Assign an agent to answer inbound calls to this number, or null to unassign.

provider

By ID · object

Change the provider. Pass { "id": "..." } for an existing provider, or pass Twilio account fields for lookup convenience. For Twilio, the phone number must exist in the target provider account. For SIP trunk providers, Cartesia handles reassignment between SIP providers. Switching between provider types is not supported; delete and re-import the number instead.

By ID
By Twilio Account

Show child attributes

Response

Phone number updated.

A phone number with its provider and agent assignment details.

string

required

Unique identifier for the phone number.

number

string

required

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

agent

object | null

required

The agent that answers inbound calls to this number, 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.

provider

Twilio · object

required

A linked Twilio account. The api_key_sid field is partially masked in responses.

Twilio
Cartesia
SIP Trunk

Show child attributes

label

string | null

A human-readable name for the phone number.

⌘I