---
title: "Link a resource to a phone number"
method: POST
path: "/api/fabric/phone_number_addresses"
tags: ["Phone Number Addresses"]
---

# Link a resource to a phone number

`POST /api/fabric/phone_number_addresses`

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

## Request body

- PhoneNumberAddressCreateRequest
  - `phone_number_id` string, uuid — Universal Unique Identifier.
  - `number` string — 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_id` string, uuid, required — Universal Unique Identifier.
  - `handler_type` 'calling' | 'messaging', required — Sets the handler to handle incoming `calls` or `messages`.

## Response `201`

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

- PhoneNumberAddress
  - `id` string, 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_id` string, uuid, required — Universal Unique Identifier.
  - `name` string, required — Name of the phone number address.
  - `phone_number` string, required — The phone number in E.164 format.
  - `phone_number_id` string, uuid, required — Universal Unique Identifier.
  - `created_at` string, date-time, required — Date and time when the phone number address was created.
  - `updated_at` string, date-time, required — Date and time when the phone number address was last updated.

## Other responses

- `400` — The request is invalid.
- `401` — Access is unauthorized.
- `422` — The request contains invalid parameters. See errors for details.
- `500` — An internal server error occurred.

## Changes

> 161 revisions in range; 3 could not be searched.

- **2026-09-15** `7506aebc9ef3` — 1 info
  - endpoint added
- **2026-09-15** `f0464a93a362` — 1 breaking
  - api path removed without deprecation
- **2026-09-15** `525afaa1e832` — 1 warning, 1 info
  - added the new `phone` enum value to the `type` response property for the response status `201`
  - removed the `phone_number_address` enum value from the `type` response property for the response status `201`
- **2026-09-15** `e35eaf5d474d` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/signalwire/apis/signalwire-rest-api/changes/api/fabric/phone_number_addresses/post.md)

---

[API](https://skmtc.dev/signalwire/apis/signalwire-rest-api.md) · [All operations](https://skmtc.dev/signalwire/apis/signalwire-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/signalwire/apis/signalwire-rest-api/revisions/20ee0f568ece?raw)