Sign in

v77

OpenAPI 3.1.0MITraw.githubusercontent.com2026-08-012528701.8 MB
Phone Numbers

Update phone number

Updates a phone number.

Permissions

The API token used to authenticate must have the following scope(s) enabled to make a successful request: Numbers.

Learn more about API scopes.

put/api/relay/rest/phone_numbers/{id}

Path parameters

idstring uuid required

Universal Unique Identifier.

Unique ID of the phone number.

Request body

namestring

The friendly name for the phone number.

call_handler'relay_context' | 'relay_topic' | 'relay_script' | 'relay_application' | 'relay_connector' | 'relay_sip_endpoint' | 'relay_verto_endpoint' | 'laml_webhooks' | 'laml_application' | 'dialogflow' | 'video_room'

Call handler type for phone number update requests. Excludes handlers that can only be set via Fabric API.

call_receive_modestring

The call receive mode for the phone number.

call_request_urlstring

The call request URL for the phone number.

call_request_method'GET' | 'POST'

The call request method for the phone number.

call_fallback_urlstring

The call fallback URL for the phone number.

call_fallback_method'GET' | 'POST'

The call fallback method for the phone number.

call_status_callback_urlstring

The call status callback URL for the phone number.

call_status_callback_method'GET' | 'POST'

The call status callback method for the phone number.

call_laml_application_idstring

The ID of the LaML Application to use when using the laml_application call handler.

call_dialogflow_agent_idstring

The ID of the Dialogflow Agent to start when using the dialogflow call handler.

call_relay_topicstring

A string representing the Relay topic to forward incoming calls to.

call_relay_topic_status_callback_urlstring

A string representing a URL to send status change messages to when call_handler is set to relay_topic.

call_relay_script_urlstring

The URL to make a request to when using the relay_script call handler.

call_relay_contextstring

This handler type is deprecated. Please use call_relay_application or call_relay_topic instead.

call_relay_context_status_callback_urlstring

This property is deprecated. Please use call_relay_topic_status_callback_url instead.

call_relay_applicationstring

A string representing the Relay Application to forward incoming calls to.

call_relay_connector_idstring

The ID of the Relay Connector to use when using the relay_connector call handler.

call_sip_endpoint_idstring

The ID of the SIP Endpoint to use when using the relay_sip_endpoint call handler.

call_verto_resourcestring

The Verto resource to use when using the relay_verto_endpoint call handler.

call_video_room_idstring uuid

Universal Unique Identifier.

message_handler'relay_context' | 'relay_topic' | 'relay_application' | 'laml_webhooks' | 'laml_application'

Message handler type for phone numbers.

message_request_urlstring

The message request URL for the phone number.

message_request_method'GET' | 'POST'

The message request method for the phone number.

message_fallback_urlstring

The message fallback URL for the phone number.

message_fallback_method'GET' | 'POST'

The message fallback method for the phone number.

message_laml_application_idstring

The ID of the LaML Application to use for messages.

message_relay_topicstring

A string representing the Relay topic to forward incoming messages to.

message_relay_contextstring

This handler type is deprecated. Please use message_relay_application or message_relay_topic instead.

message_relay_applicationstring

A string representing the Relay Application to forward incoming messages to.

Example request

{
  "name": "Main Office Line",
  "call_relay_topic": "office",
  "call_relay_topic_status_callback_url": "https://myapplication/handle_relay_callbacks",
  "call_relay_script_url": "https://example.signalwire.com/relay-bins/60e2ba7b-366e-44de-84e3-0c76cfccf1cc",
  "call_relay_context": "my_relay_app",
  "call_relay_context_status_callback_url": "https://myapplication/handle_relay_callbacks",
  "call_relay_application": "my-relay-app"
}

Response

The request has succeeded.

idstring uuid required

Universal Unique Identifier.

numberstring required

The phone number in E.164 format.

namestring nullable required

The name given to the phone number. Helps to distinguish different phone numbers within your project.

capabilitiesPhoneNumberCapability[] required

A list of communication methods this phone number supports.

number_type'toll-free' | 'longcode' required

Phone number type.

e911_address_idstring uuid required

Universal Unique Identifier.

e911_status'pending' | 'active' | 'failed' | 'pending_removal' | 'unregistered' required

E911 provisioning status of a phone number.

created_atstring date-time required

The date the number was added to your project.

updated_atstring date-time required

The date the number was last updated.

next_billed_atstring date-time nullable required

The next date the number will be billed for.

call_handler'relay_context' | 'relay_topic' | 'relay_script' | 'relay_application' | 'relay_connector' | 'relay_sip_endpoint' | 'relay_verto_endpoint' | 'laml_webhooks' | 'laml_application' | 'dialogflow' | 'video_room' | 'call_flow' | 'ai_agent' | 'fabric_subscriber' | 'sip_gateway' | 'call_queue' required

Call handler type for phone numbers.

calling_handler_resource_idstring uuid required

Universal Unique Identifier.

call_receive_mode'voice' | 'fax' required

Call receive mode.

call_request_urlstring nullable required

The URL to make a request to when using the laml_webhooks call handler.

call_request_method'GET' | 'POST' required

HTTP method type.

call_fallback_urlstring nullable required

The fallback URL to make a request to when using the laml_webhooks call handler and the call_request_url fails.

call_fallback_method'GET' | 'POST' required

HTTP method type.

call_status_callback_urlstring nullable required

The URL to make status callbacks to when using the laml_webhooks call handler.

call_status_callback_method'GET' | 'POST' required

HTTP method type.

call_laml_application_idstring nullable required

The ID of the LaML Application to use when using the laml_application call handler.

call_dialogflow_agent_idstring nullable required

The ID of the Dialogflow Agent to start when using the dialogflow call handler.

call_relay_topicstring nullable required

A string representing the Relay topic to forward incoming calls to. This is only used (and required) when call_handler is set to relay_topic.

call_relay_topic_status_callback_urlstring nullable required

A string representing a URL to send status change messages to. This is only used (and required) when call_handler is set to relay_topic.

call_relay_script_urlstring nullable required

The URL to make a request to when using the relay_script call handler. The URL must respond with a valid SWML script.

call_relay_contextstring nullable required

The name of the Relay Context to send this call to when using the relay_context call handler.

call_relay_context_status_callback_urlstring nullable required

A string representing a URL to send status change messages to. This is only used (and required) when call_handler is set to relay_context.

call_relay_applicationstring nullable required

The name of the Relay Application to send this call to when using the relay_application call handler.

call_relay_connector_idstring nullable required

The ID of the Relay Connector to send this call to when using the relay_connector call handler.

call_sip_endpoint_idstring uuid required

Universal Unique Identifier.

call_verto_resourcestring nullable required

The name of the Verto Relay Endpoint to send this call to when using the relay_verto_endpoint call handler.

call_video_room_idstring uuid required

Universal Unique Identifier.

message_handler'relay_context' | 'relay_topic' | 'relay_application' | 'laml_webhooks' | 'laml_application' required

Message handler type for phone numbers.

messaging_handler_resource_idstring uuid required

Universal Unique Identifier.

message_request_urlstring nullable required

The URL to make a request to when using the laml_webhooks message handler.

message_request_method'GET' | 'POST' required

HTTP method type.

message_fallback_urlstring nullable required

The fallback URL to make a request to when using the laml_webhooks message handler and the message_request_url fails.

message_fallback_method'GET' | 'POST' required

HTTP method type.

message_laml_application_idstring nullable required

The ID of the LaML Application to use when using the laml_application message handler.

message_relay_topicstring nullable required

The name of the Relay Topic to send this message to when using the relay_topic message handler.

message_relay_contextstring nullable required

The name of the Relay Context to send this message to when using the relay_context message handler.

country_codestring nullable required

The ISO 3166-1 alpha-2 country code of the phone number.

Example response

{
  "number": "+15558675309",
  "name": "Jenny",
  "call_relay_topic": "office",
  "call_relay_topic_status_callback_url": "https://myapplication/handle_relay_callbacks",
  "call_relay_script_url": "https://example.signalwire.com/relay-bins/60e2ba7b-366e-44de-84e3-0c76cfccf1cc",
  "call_relay_context": "my_relay_app",
  "call_relay_context_status_callback_url": "https://myapplication/handle_relay_callbacks",
  "call_relay_application": "my_relay_app",
  "message_relay_context": "my_relay_app",
  "country_code": "US"
}