Link a resource to a phone number

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.

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](/docs/apis/rest/phone-routes/assign-resource-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](/docs/apis/rest/phone-number-addresses/update-phone-number-address) to re-point it instead. <Warning title="Beta">This API is in beta and may change.</Warning> #### 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](/docs/platform/your-signalwire-api-space).

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)

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.

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.

handler_typeenum

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

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