Skip to navigation
Resource ManagementPhone Number Addresses

Link a resource to a phone number

Beta
View as MarkdownOpen in Claude

Links a resource to an unassigned channel of a phone number you own, so inbound calls or messages to that number reach the resource. Reference the number by phone_number_id or by its E.164 number, and pick the channel with handler_type. The address for that channel already exists, so this operation sets its resource rather than creating a new address, and it never purchases a number. Assign Resource to phone route does the same from the resource’s side.

A 422 response names the problem in its code:

  • missing_required_parameter: resource_id or handler_type is blank, or neither phone_number_id nor number was provided.
  • invalid_parameter: handler_type is not calling or messaging.
  • provided_id_is_unrecognized: the number is not owned by your project, or resource_id is not a resource in it.
  • invalid_resource_type: the resource can’t handle the chosen channel.
  • already_assigned: the channel already has a resource. Use Update the resource for a phone number to re-point it instead.
Beta
This API is in beta and may change.

Permissions

The API token used to authenticate must have the following scope(s) enabled to make a successful request: Calling, Fax, Messaging, or Video.

Learn more about API scopes.

Authentication

AuthorizationBasic

SignalWire Basic Authentication using Project ID and API Token.

The client sends HTTP requests with the Authorization header containing the word Basic followed by a space and a base64-encoded string of project_id:token. The project ID will be used as the username and the API token as the password.

Example:

Authorization: Basic base64(project_id:token)

Request

This endpoint expects an object.
resource_idstringRequiredformat: "uuid"

ID of the resource that should handle the channel. Must be a resource in your project of a type that can handle the chosen channel — for example, only messaging-capable resources can handle messaging.

handler_typeenumRequired

The channel to link the resource to: calling for inbound calls or messaging for inbound messages. The channel must not already have a resource assigned.

Allowed values:
phone_number_idstringOptionalformat: "uuid"

ID of a phone number your project owns. Provide this or number.

numberstringOptional

A phone number your project owns, in E.164 format. Other common formats are accepted and normalized to E.164. Provide this or phone_number_id.

Response

The request has succeeded and a new resource has been created as a result.
idstringformat: "uuid"
Unique identifier for the phone number address.
typeenum

The object type. Always phone.

Allowed values:
handler_typeenum

The channel this address represents: calling for inbound calls or messaging for inbound messages. A phone number has one address per channel.

Allowed values:
resource_idstring or nullformat: "uuid"

ID of the resource that handles this channel. null when no resource is assigned.

namestring
Name of the phone number address.
phone_numberstring
The phone number in E.164 format.
phone_number_idstringformat: "uuid"
ID of the phone number this address belongs to.
created_atdatetime
Date and time when the phone number address was created.
updated_atdatetime
Date and time when the phone number address was last updated.

Errors

400
Bad Request Error
401
Unauthorized Error
422
Unprocessable Entity Error
500
Internal Server Error