Sign in
Phone Number Addresses

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.

<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.

post/api/fabric/phone_number_addresses

Request body

phone_number_idstring uuid

Universal Unique Identifier.

numberstring

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.

resource_idstring uuid required

Universal Unique Identifier.

handler_type'calling' | 'messaging' required

Sets the handler to handle incoming calls or messages.

Example request

{
  "number": "+13105550100"
}

Response

The request has succeeded and a new resource has been created as a result.

idstring uuid required

Universal Unique Identifier.

type'phone' required

The object type. Always phone.

handler_type'calling' | 'messaging' required

Sets the handler to handle incoming calls or messages.

resource_idstring uuid required

Universal Unique Identifier.

namestring required

Name of the phone number address.

phone_numberstring required

The phone number in E.164 format.

phone_number_idstring uuid required

Universal Unique Identifier.

created_atstring date-time required

Date and time when the phone number address was created.

updated_atstring date-time required

Date and time when the phone number address was last updated.

Example response

{
  "type": "phone",
  "name": "main-support-number",
  "phone_number": "+13105550100",
  "created_at": "2024-05-06T12:20:00Z",
  "updated_at": "2024-05-06T12:20:00Z"
}

Changes

Changed in 4 of the 161 revisions of this API.113

Of the 161 revisions, 3 have a changelog that could not be searched.