Retell AI Update Phone Number API
The Update Phone Number API from Retell AI — 1 operation(s) for update phone number.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/retell-ai-update-phone-number-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Retell SDK Add Community Voice Update Phone Number API
version: 3.0.0
contact:
name: Retell Support
url: https://www.retellai.com/
email: support@retellai.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.retellai.com
description: The production server.
security:
- api_key: []
tags:
- name: Update Phone Number
paths:
/update-phone-number/{phone_number}:
patch:
description: Update agent bound to a purchased phone number
operationId: updatePhoneNumber
parameters:
- in: path
name: phone_number
schema:
type: string
minLength: 1
example: '+14157774444'
required: true
description: 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.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
inbound_agents:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/AgentWeight'
description: 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.
outbound_agents:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/AgentWeight'
description: 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.
inbound_sms_agents:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/AgentWeight'
description: 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. If not set or empty, fallback to inbound_sms_agent_id.
outbound_sms_agents:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/AgentWeight'
description: 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. If not set or empty, fallback to outbound_sms_agent_id.
nickname:
type:
- string
- 'null'
example: Frontdesk Number
description: Nickname of the number. This is for your reference only.
inbound_webhook_url:
type:
- string
- 'null'
example: https://example.com/inbound-webhook
description: If set, will send a webhook for inbound calls, where you can to override agent id, set dynamic variables and other fields specific to that call.
inbound_sms_webhook_url:
type:
- string
- 'null'
example: https://example.com/inbound-sms-webhook
description: If set, will send a webhook for inbound SMS, where you can override agent id, set dynamic variables and other fields specific to that chat.
allowed_inbound_country_list:
type:
- array
- 'null'
items:
type: string
example:
- US
- CA
- GB
description: 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.
allowed_outbound_country_list:
type:
- array
- 'null'
items:
type: string
example:
- US
- CA
description: 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.
termination_uri:
type: string
example: someuri.pstn.twilio.com
description: The termination uri to update for the phone number. This is used for outbound calls.
auth_username:
type: string
example: username
description: The username used for authentication for the SIP trunk to update for the phone number.
auth_password:
type: string
example: '123456'
description: The password used for authentication for the SIP trunk to update for the phone number.
transport:
type:
- string
- 'null'
example: TCP
description: Outbound transport protocol to update for the phone number. Valid values are "TLS", "TCP" and "UDP". Default is "TCP".
fallback_number:
type:
- string
- 'null'
example: '+14155551234'
description: Enterprise only. Phone number to transfer inbound calls to when organization is in outage mode. 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:
inbound_agents:
- agent_id: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
agent_version: 1
weight: 1
outbound_agents:
- agent_id: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
agent_version: 1
weight: 1
nickname: Frontdesk Number
responses:
'200':
description: Successfully updated an phone number object.
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneNumberResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableContent'
'500':
$ref: '#/components/responses/InternalServerError'
tags:
- Update Phone Number
components:
responses:
UnprocessableContent:
description: Unprocessable Content
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: Cannot find requested asset under given api key.
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: API key is missing or invalid.
InternalServerError:
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: An unexpected server error occurred.
BadRequest:
description: Bad Request
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
message:
type: string
example: Invalid request format, please check API reference.
schemas:
PhoneNumberResponse:
type: object
required:
- phone_number
- phone_number_type
- last_modification_timestamp
properties:
phone_number:
type: string
example: '+14157774444'
description: 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.
phone_number_type:
type: string
enum:
- retell-twilio
- retell-telnyx
- custom
example: retell-twilio
description: Type of the phone number.
phone_number_pretty:
type: string
example: +1 (415) 777-4444
description: Pretty printed phone number, provided for your reference.
allowed_inbound_country_list:
type:
- array
- 'null'
items:
type: string
example:
- US
- CA
- GB
description: 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.
allowed_outbound_country_list:
type:
- array
- 'null'
items:
type: string
example:
- US
- CA
description: 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.
area_code:
type: integer
example: 415
description: Area code of the number to obtain. Format is a 3 digit integer. Currently only supports US area code.
inbound_agents:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/AgentWeight'
description: 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.
outbound_agents:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/AgentWeight'
description: 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.
inbound_sms_agents:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/AgentWeight'
description: 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. If not set or empty, fallback to inbound_sms_agent_id.
outbound_sms_agents:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/AgentWeight'
description: 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. If not set or empty, fallback to outbound_sms_agent_id.
nickname:
type:
- string
- 'null'
example: Frontdesk Number
description: Nickname of the number. This is for your reference only.
inbound_webhook_url:
type:
- string
- 'null'
example: https://example.com/inbound-webhook
description: If set, will send a webhook for inbound calls, where you can to override agent id, set dynamic variables and other fields specific to that call.
inbound_sms_webhook_url:
type:
- string
- 'null'
example: https://example.com/inbound-sms-webhook
description: If set, will send a webhook for inbound SMS, where you can override agent id, set dynamic variables and other fields specific to that chat.
last_modification_timestamp:
type: integer
example: 1703413636133
description: Last modification timestamp (milliseconds since epoch). Either the time of last update or creation if no updates available.
sip_outbound_trunk_config:
type:
- object
- 'null'
properties:
termination_uri:
type:
- string
- 'null'
example: someuri.pstn.twilio.com
description: The termination URI for the SIP trunk for the phone number.
auth_username:
type:
- string
- 'null'
example: username
description: The username used for authenticating the SIP trunk for the phone number.
transport:
type:
- string
- 'null'
example: TCP
description: Outbound transport protocol for the SIP trunk for the phone number. Valid values are "TLS", "TCP" and "UDP". Default is "TCP".
fallback_number:
type:
- string
- 'null'
example: '+14155551234'
description: Enterprise only. Phone number to transfer inbound calls to when organization is in outage mode. 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).
AgentWeight:
type: object
required:
- agent_id
- weight
properties:
agent_id:
type: string
minLength: 1
example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD
agent_version:
$ref: '#/components/schemas/AgentVersionReference'
weight:
type: number
example: 0.5
maximum: 1
description: The weight of the agent. When used in a list of agents, the total weights must add up to 1.
exclusiveMinimum: 0
AgentVersionReference:
oneOf:
- type: integer
minimum: 0
example: 1
- type: string
minLength: 1
maxLength: 20
pattern: ^[a-z0-9_-]+$
example: prod
description: Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version (or latest) is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.
securitySchemes:
api_key:
type: http
scheme: bearer
bearerFormat: string
description: Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"