Update Phone Number

PATCH

update-phone-number

{phone_number}

JavaScript

import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted
});

const phoneNumberResponse = await client.phoneNumber.update('+14157774444', {
  inbound_agents: [
    {
      agent_id: 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD',
      agent_version: 1,
      weight: 1,
    },
  ],
  nickname: 'Frontdesk Number',
  outbound_agents: [
    {
      agent_id: 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD',
      agent_version: 1,
      weight: 1,
    },
  ],
});

console.log(phoneNumberResponse.last_modification_timestamp);

import os
from retell import Retell

client = Retell(
    api_key=os.environ.get("RETELL_API_KEY"),  # This is the default and can be omitted
)
phone_number_response = client.phone_number.update(
    phone_number="+14157774444",
    inbound_agents=[{
        "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
        "agent_version": 1,
        "weight": 1,
    }],
    nickname="Frontdesk Number",
    outbound_agents=[{
        "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
        "agent_version": 1,
        "weight": 1,
    }],
)
print(phone_number_response.last_modification_timestamp)

curl --request PATCH \
  --url https://api.retellai.com/update-phone-number/{phone_number} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "inbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": 1,
      "weight": 1
    }
  ],
  "outbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": 1,
      "weight": 1
    }
  ],
  "nickname": "Frontdesk Number"
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.retellai.com/update-phone-number/{phone_number}",
  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([
    'inbound_agents' => [
        [
                'agent_id' => 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD',
                'agent_version' => 1,
                'weight' => 1
        ]
    ],
    'outbound_agents' => [
        [
                'agent_id' => 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD',
                'agent_version' => 1,
                'weight' => 1
        ]
    ],
    'nickname' => 'Frontdesk Number'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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.retellai.com/update-phone-number/{phone_number}"

	payload := strings.NewReader("{\n  \"inbound_agents\": [\n    {\n      \"agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n      \"agent_version\": 1,\n      \"weight\": 1\n    }\n  ],\n  \"outbound_agents\": [\n    {\n      \"agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n      \"agent_version\": 1,\n      \"weight\": 1\n    }\n  ],\n  \"nickname\": \"Frontdesk Number\"\n}")

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

	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.retellai.com/update-phone-number/{phone_number}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"inbound_agents\": [\n    {\n      \"agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n      \"agent_version\": 1,\n      \"weight\": 1\n    }\n  ],\n  \"outbound_agents\": [\n    {\n      \"agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n      \"agent_version\": 1,\n      \"weight\": 1\n    }\n  ],\n  \"nickname\": \"Frontdesk Number\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.retellai.com/update-phone-number/{phone_number}")

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

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"inbound_agents\": [\n    {\n      \"agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n      \"agent_version\": 1,\n      \"weight\": 1\n    }\n  ],\n  \"outbound_agents\": [\n    {\n      \"agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n      \"agent_version\": 1,\n      \"weight\": 1\n    }\n  ],\n  \"nickname\": \"Frontdesk Number\"\n}"

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

{
  "phone_number": "+14157774444",
  "phone_number_type": "retell-twilio",
  "last_modification_timestamp": 1703413636133,
  "phone_number_pretty": "+1 (415) 777-4444",
  "allowed_inbound_country_list": [
    "US",
    "CA",
    "GB"
  ],
  "allowed_outbound_country_list": [
    "US",
    "CA"
  ],
  "area_code": 415,
  "inbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "weight": 0.5,
      "agent_version": "latest_published"
    }
  ],
  "outbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "weight": 0.5,
      "agent_version": "latest_published"
    }
  ],
  "inbound_sms_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "weight": 0.5,
      "agent_version": "latest_published"
    }
  ],
  "outbound_sms_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "weight": 0.5,
      "agent_version": "latest_published"
    }
  ],
  "nickname": "Frontdesk Number",
  "inbound_webhook_url": "https://example.com/inbound-webhook",
  "inbound_sms_webhook_url": "https://example.com/inbound-sms-webhook",
  "sip_outbound_trunk_config": {
    "termination_uri": "someuri.pstn.twilio.com",
    "auth_username": "username",
    "transport": "TCP",
    "codecs": [
      "PCMU",
      "PCMA",
      "G.722"
    ]
  },
  "fallback_number": "+14155551234",
  "inbound_fallback_enabled": false
}

{
  "status": "error",
  "message": "Invalid request format, please check API reference."
}

{
  "status": "error",
  "message": "API key is missing or invalid."
}

{
  "status": "error",
  "message": "Cannot find requested asset under given api key."
}

{
  "status": "error",
  "message": "An unexpected server error occurred."
}

Authorizations

Authorization

string

header

required

Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"

Path Parameters

phone_number

string

required

E.164 format of the number (+country code, then number with no space, no special characters), used as the unique identifier for phone number APIs.

Minimum string length: 1

Example:

"+14157774444"

Body

application/json

inbound_agents

object[] | null

Inbound agents to bind to the number with weights. If set and non-empty, one agent will be picked randomly for each inbound call, with probability proportional to the weight. Total weights must add up to 1.

Show child attributes

outbound_agents

object[] | null

Outbound agents to bind to the number with weights. If set and non-empty, one agent will be picked randomly for each outbound call, with probability proportional to the weight. Total weights must add up to 1.

Show child attributes

inbound_sms_agents

object[] | null

Inbound SMS agents to bind to the number with weights. If set and non-empty, one agent will be picked randomly for each inbound SMS, with probability proportional to the weight. Total weights must add up to 1.

Show child attributes

outbound_sms_agents

object[] | null

Outbound SMS agents to bind to the number with weights. If set and non-empty, one agent will be picked randomly for each outbound SMS, with probability proportional to the weight. Total weights must add up to 1.

Show child attributes

nickname

string | null

Nickname of the number. This is for your reference only.

Example:

"Frontdesk Number"

inbound_webhook_url

string | null

If set, Retell will send a webhook for inbound calls, where you can override the agent ID, set dynamic variables, reject the call, and configure other fields specific to that call. Includes call_inbound.call_id for deduplication across HTTP retries. Early setup failures may not create a call history record.

Example:

"https://example.com/inbound-webhook"

inbound_sms_webhook_url

string | null

If set, Retell will send a webhook for inbound SMS, where you can override the agent ID, set dynamic variables, reject the SMS, and configure other fields specific to that chat. Includes chat_inbound.chat_id for deduplication across HTTP retries. Early setup failures may not create a chat history record.

Example:

"https://example.com/inbound-sms-webhook"

allowed_inbound_country_list

string[] | null

List of ISO 3166-1 alpha-2 country codes from which inbound calls are allowed. If not set or empty, calls from all countries are allowed.

Example:

["US", "CA", "GB"]

allowed_outbound_country_list

string[] | null

List of ISO 3166-1 alpha-2 country codes to which outbound calls are allowed. If not set or empty, calls to all countries are allowed.

Example:

["US", "CA"]

codecs

string[]

SIP codec preferences for custom phone numbers only, used for inbound and outbound gateway calls. Retell-managed Twilio and Telnyx phone numbers do not support this setting. An empty list uses the gateway's default codecs. Codec names are extensible and are not limited to the examples.

Minimum string length: 1

Example:

["PCMU", "PCMA", "G.722"]

termination_uri

string

The termination uri to update for the phone number. This is used for outbound calls.

Example:

"someuri.pstn.twilio.com"

auth_username

string

The username used for authentication for the SIP trunk to update for the phone number.

Example:

"username"

auth_password

string

The password used for authentication for the SIP trunk to update for the phone number.

Example:

"123456"

transport

string | null

Outbound transport protocol to update for the phone number. Valid values are "TLS", "TCP" and "UDP". Default is "TCP".

Example:

"TCP"

fallback_number

string | null

When inbound call concurrency is reached and a slot does not free up after extended ringing, the call will fall back to this number. Can be either a Retell phone number or an external number. Set to null to remove. Cannot be the same as this phone number, and cannot be a number that already has its own fallback configured (prevents nested forwarding).

Example:

"+14155551234"

inbound_fallback_enabled

boolean

Whether to enable inbound fallback for this phone number. When enabled, inbound calls are transferred to the fallback number. Requires fallback_number to be set.

Example:

true

Response

Successfully updated an phone number object.

phone_number

string

required

E.164 format of the number (+country code, then number with no space, no special characters), used as the unique identifier for phone number APIs.

Example:

"+14157774444"

phone_number_type

enum<string>

required

Type of the phone number.

Available options:

retell-twilio,

retell-telnyx,

custom

Example:

"retell-twilio"

last_modification_timestamp

integer

required

Last modification timestamp (milliseconds since epoch). Either the time of last update or creation if no updates available.

Example:

1703413636133

phone_number_pretty

string

Pretty printed phone number, provided for your reference.

Example:

"+1 (415) 777-4444"

allowed_inbound_country_list

string[] | null

List of ISO 3166-1 alpha-2 country codes from which inbound calls are allowed. If not set or empty, calls from all countries are allowed.

Example:

["US", "CA", "GB"]

allowed_outbound_country_list

string[] | null

List of ISO 3166-1 alpha-2 country codes to which outbound calls are allowed. If not set or empty, calls to all countries are allowed.

Example:

["US", "CA"]

area_code

integer

Area code of the number to obtain. Format is a 3 digit integer. Currently only supports US area code.

Example:

415

inbound_agents

object[] | null

Show child attributes

outbound_agents

object[] | null

Show child attributes

inbound_sms_agents

object[] | null

Show child attributes

outbound_sms_agents

object[] | null

Show child attributes

nickname

string | null

Nickname of the number. This is for your reference only.

Example:

"Frontdesk Number"

inbound_webhook_url

string | null

Example:

"https://example.com/inbound-webhook"

inbound_sms_webhook_url

string | null

Example:

"https://example.com/inbound-sms-webhook"

sip_outbound_trunk_config

object | null

Show child attributes

fallback_number

string | null

When inbound call concurrency is reached and a slot does not free up after extended ringing, the call will fall back to this number. Can be either a Retell phone number or an external number. Cannot be the same as this phone number, and cannot be a number that already has its own fallback configured (prevents nested forwarding).

Example:

"+14155551234"

inbound_fallback_enabled

boolean

Whether inbound fallback is enabled for this phone number. When enabled, inbound calls are transferred to the fallback number.

Example:

false

⌘I

JavaScript

import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted
});

const phoneNumberResponse = await client.phoneNumber.update('+14157774444', {
  inbound_agents: [
    {
      agent_id: 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD',
      agent_version: 1,
      weight: 1,
    },
  ],
  nickname: 'Frontdesk Number',
  outbound_agents: [
    {
      agent_id: 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD',
      agent_version: 1,
      weight: 1,
    },
  ],
});

console.log(phoneNumberResponse.last_modification_timestamp);

import os
from retell import Retell

client = Retell(
    api_key=os.environ.get("RETELL_API_KEY"),  # This is the default and can be omitted
)
phone_number_response = client.phone_number.update(
    phone_number="+14157774444",
    inbound_agents=[{
        "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
        "agent_version": 1,
        "weight": 1,
    }],
    nickname="Frontdesk Number",
    outbound_agents=[{
        "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
        "agent_version": 1,
        "weight": 1,
    }],
)
print(phone_number_response.last_modification_timestamp)

curl --request PATCH \
  --url https://api.retellai.com/update-phone-number/{phone_number} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "inbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": 1,
      "weight": 1
    }
  ],
  "outbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": 1,
      "weight": 1
    }
  ],
  "nickname": "Frontdesk Number"
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.retellai.com/update-phone-number/{phone_number}",
  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([
    'inbound_agents' => [
        [
                'agent_id' => 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD',
                'agent_version' => 1,
                'weight' => 1
        ]
    ],
    'outbound_agents' => [
        [
                'agent_id' => 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD',
                'agent_version' => 1,
                'weight' => 1
        ]
    ],
    'nickname' => 'Frontdesk Number'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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.retellai.com/update-phone-number/{phone_number}"

	payload := strings.NewReader("{\n  \"inbound_agents\": [\n    {\n      \"agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n      \"agent_version\": 1,\n      \"weight\": 1\n    }\n  ],\n  \"outbound_agents\": [\n    {\n      \"agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n      \"agent_version\": 1,\n      \"weight\": 1\n    }\n  ],\n  \"nickname\": \"Frontdesk Number\"\n}")

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

	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.retellai.com/update-phone-number/{phone_number}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"inbound_agents\": [\n    {\n      \"agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n      \"agent_version\": 1,\n      \"weight\": 1\n    }\n  ],\n  \"outbound_agents\": [\n    {\n      \"agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n      \"agent_version\": 1,\n      \"weight\": 1\n    }\n  ],\n  \"nickname\": \"Frontdesk Number\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.retellai.com/update-phone-number/{phone_number}")

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

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"inbound_agents\": [\n    {\n      \"agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n      \"agent_version\": 1,\n      \"weight\": 1\n    }\n  ],\n  \"outbound_agents\": [\n    {\n      \"agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n      \"agent_version\": 1,\n      \"weight\": 1\n    }\n  ],\n  \"nickname\": \"Frontdesk Number\"\n}"

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

{
  "phone_number": "+14157774444",
  "phone_number_type": "retell-twilio",
  "last_modification_timestamp": 1703413636133,
  "phone_number_pretty": "+1 (415) 777-4444",
  "allowed_inbound_country_list": [
    "US",
    "CA",
    "GB"
  ],
  "allowed_outbound_country_list": [
    "US",
    "CA"
  ],
  "area_code": 415,
  "inbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "weight": 0.5,
      "agent_version": "latest_published"
    }
  ],
  "outbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "weight": 0.5,
      "agent_version": "latest_published"
    }
  ],
  "inbound_sms_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "weight": 0.5,
      "agent_version": "latest_published"
    }
  ],
  "outbound_sms_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "weight": 0.5,
      "agent_version": "latest_published"
    }
  ],
  "nickname": "Frontdesk Number",
  "inbound_webhook_url": "https://example.com/inbound-webhook",
  "inbound_sms_webhook_url": "https://example.com/inbound-sms-webhook",
  "sip_outbound_trunk_config": {
    "termination_uri": "someuri.pstn.twilio.com",
    "auth_username": "username",
    "transport": "TCP",
    "codecs": [
      "PCMU",
      "PCMA",
      "G.722"
    ]
  },
  "fallback_number": "+14155551234",
  "inbound_fallback_enabled": false
}

{
  "status": "error",
  "message": "Invalid request format, please check API reference."
}

{
  "status": "error",
  "message": "API key is missing or invalid."
}

{
  "status": "error",
  "message": "Cannot find requested asset under given api key."
}

{
  "status": "error",
  "message": "An unexpected server error occurred."
}

Call

Chat

Playground

Phone Number

Voice Agent

Chat Agent

Retell LLM Response Engine (for single / multi prompt agent)

Conversation Flow Response Engine (for conversation flow agent)

Conversation Flow Subflows

MCP Tool

Knowledge Base

Voice

Batch call

Contact

App

CRM

Test Case Definitions

Batch Tests

Test Runs

Account

Custom Telephony

Custom LLM

Update Phone Number

Authorizations

Path Parameters

Body

Response