Update Phone Number
Updates a phone number in Retell AI.
Query
Comma-separated response fields to include.
Body
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.
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.
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. If not set or empty, fallback to inbound_agent_id.
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 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. If not set or empty, fallback to outbound_agent_id.
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.
Unique id of agent to bind to the number. The number will automatically use the agent when receiving inbound calls. If set to null, this number would not accept inbound call. Deprecated. See https://docs.retellai.com/deprecation-notice/2026/03-31_phone_number_agent_fields
Unique id of agent to bind to the number. The number will automatically use the agent when conducting outbound calls. If set to null, this number would not be able to initiate outbound call without agent id override. Deprecated. See https://docs.retellai.com/deprecation-notice/2026/03-31_phone_number_agent_fields
Version of the inbound agent to bind to the number. If not provided, will default to latest version. Deprecated. See https://docs.retellai.com/deprecation-notice/2026/03-31_phone_number_agent_fields
Version of the outbound agent to bind to the number. If not provided, will default to latest version.
The weight of the agent. When used in a list of agents, the total weights must add up to 1.
The weight of the agent. When used in a list of agents, the total weights must add up to 1.
The weight of the agent. When used in a list of agents, the total weights must add up to 1.
The weight of the agent. When used in a list of agents, the total weights must add up to 1.
Nickname of the number. This is for your reference only.
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.
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.
The termination uri to update for the phone number. This is used for outbound calls.
The username used for authentication for the SIP trunk to update for the phone number.
The password used for authentication for the SIP trunk to update for the phone number.
Outbound transport protocol to update for the phone number. Valid values are "TLS", "TCP" and "UDP". Default is "TCP".
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).