> ## Documentation Index > Fetch the complete documentation index at: https://docs.retellai.com/llms.txt > Use this file to discover all available pages before exploring further. # Update Phone Number > Update agent bound to a purchased phone number ## OpenAPI ````yaml openapi-final patch /update-phone-number/{phone_number} openapi: 3.0.3 info: title: Retell SDK 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: [] 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 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. nullable: true outbound_agents: type: array 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. nullable: true inbound_sms_agents: type: array 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. nullable: true outbound_sms_agents: type: array 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. nullable: true nickname: type: string example: Frontdesk Number description: Nickname of the number. This is for your reference only. nullable: true inbound_webhook_url: type: string 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. nullable: true inbound_sms_webhook_url: type: string 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. nullable: true allowed_inbound_country_list: type: array 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. nullable: true allowed_outbound_country_list: type: array 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. nullable: true 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 example: TCP description: >- Outbound transport protocol to update for the phone number. Valid values are "TLS", "TCP" and "UDP". Default is "TCP". nullable: true fallback_number: type: string 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). nullable: true 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' x-codeSamples: - lang: JavaScript source: >- 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); - lang: Python source: |- 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) components: schemas: 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 minimum: 0 exclusiveMinimum: true maximum: 1 description: >- The weight of the agent. When used in a list of agents, the total weights must add up to 1. 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 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. nullable: true allowed_outbound_country_list: type: array 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. nullable: true 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 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. nullable: true outbound_agents: type: array 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. nullable: true inbound_sms_agents: type: array 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. nullable: true outbound_sms_agents: type: array 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. nullable: true nickname: type: string example: Frontdesk Number description: Nickname of the number. This is for your reference only. nullable: true inbound_webhook_url: type: string 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. nullable: true inbound_sms_webhook_url: type: string 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. nullable: true 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 nullable: true properties: termination_uri: type: string example: someuri.pstn.twilio.com nullable: true description: The termination URI for the SIP trunk for the phone number. auth_username: type: string example: username nullable: true description: >- The username used for authenticating the SIP trunk for the phone number. transport: type: string example: TCP nullable: true 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 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). nullable: true 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. responses: 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. 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. 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. 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. 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" ````