> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# Phone Numbers

> Search and manage phone numbers, and bind inbound calls to handlers.

[restclient]: /docs/server-sdks/reference/typescript/rest/client

[list]: /docs/server-sdks/reference/typescript/rest/phone-numbers/list

[create]: /docs/server-sdks/reference/typescript/rest/phone-numbers/create

[get]: /docs/server-sdks/reference/typescript/rest/phone-numbers/get

[update]: /docs/server-sdks/reference/typescript/rest/phone-numbers/update

[delete]: /docs/server-sdks/reference/typescript/rest/phone-numbers/delete

[search]: /docs/server-sdks/reference/typescript/rest/phone-numbers/search

[setswml]: /docs/server-sdks/reference/typescript/rest/phone-numbers/set-swml-webhook

[setcxml]: /docs/server-sdks/reference/typescript/rest/phone-numbers/set-cxml-webhook

[setcxmlapp]: /docs/server-sdks/reference/typescript/rest/phone-numbers/set-cxml-application

[setai]: /docs/server-sdks/reference/typescript/rest/phone-numbers/set-ai-agent

[setflow]: /docs/server-sdks/reference/typescript/rest/phone-numbers/set-call-flow

[setrelayapp]: /docs/server-sdks/reference/typescript/rest/phone-numbers/set-relay-application

[setrelaytopic]: /docs/server-sdks/reference/typescript/rest/phone-numbers/set-relay-topic

Search for available phone numbers, purchase them, and manage the numbers in your
SignalWire project. This resource extends the standard CRUD pattern with a `search()`
method for discovering available numbers, uses PUT for updates, and provides typed
helpers for binding inbound calls to a handler (SWML webhook, cXML webhook, AI agent,
call flow, Relay application/topic).

Access via `client.phoneNumbers` on a [`RestClient`][restclient] instance.

> **Info**
>
> **Idiomatic deviation:** `create()` and `update()` accept an untyped body
> object (`Record<string, unknown>`) rather than narrow per-field types. This
> mirrors Python's `**kwargs`-style flexibility. Response payloads follow the
> same typing.

```typescript {9}
import { RestClient } from "@signalwire/sdk";

const client = new RestClient({
  project: "your-project-id",
  token: "your-api-token",
  host: "your-space.signalwire.com"
});

const available = await client.phoneNumbers.search({ areacode: "512" });
for (const number of available.data ?? []) {
    console.log(number.phoneNumber);
}
```

## **Methods**

### Standard CRUD

#### [list](/docs/server-sdks/reference/typescript/rest/phone-numbers/list)

List phone numbers owned by the project.

#### [create](/docs/server-sdks/reference/typescript/rest/phone-numbers/create)

Purchase a phone number.

#### [get](/docs/server-sdks/reference/typescript/rest/phone-numbers/get)

Retrieve details for a specific phone number.

#### [update](/docs/server-sdks/reference/typescript/rest/phone-numbers/update)

Update configuration for a phone number.

#### [delete](/docs/server-sdks/reference/typescript/rest/phone-numbers/delete)

Release a phone number from the project.

#### [search](/docs/server-sdks/reference/typescript/rest/phone-numbers/search)

Search for available phone numbers to purchase.

### Typed Binding Helpers

Each helper is a one-line wrapper over [`update`][update] that sets `call_handler`
to the right value and populates the handler-specific companion field for you.
Pass extra wire-level fields through the `extra` argument (or as additional keys
on the params object) for fields the helper doesn't name explicitly. Setting a
binding auto-materializes the matching Fabric resource on the server.

#### [setSwmlWebhook](/docs/server-sdks/reference/typescript/rest/phone-numbers/set-swml-webhook)

Route inbound calls to an SWML webhook URL.

#### [setCxmlWebhook](/docs/server-sdks/reference/typescript/rest/phone-numbers/set-cxml-webhook)

Route inbound calls to a cXML (LAML) webhook.

#### [setCxmlApplication](/docs/server-sdks/reference/typescript/rest/phone-numbers/set-cxml-application)

Route inbound calls to an existing cXML application by ID.

#### [setAiAgent](/docs/server-sdks/reference/typescript/rest/phone-numbers/set-ai-agent)

Route inbound calls to an AI Agent Fabric resource by ID.

#### [setCallFlow](/docs/server-sdks/reference/typescript/rest/phone-numbers/set-call-flow)

Route inbound calls to a Call Flow by ID.

#### [setRelayApplication](/docs/server-sdks/reference/typescript/rest/phone-numbers/set-relay-application)

Route inbound calls to a named Relay application.

#### [setRelayTopic](/docs/server-sdks/reference/typescript/rest/phone-numbers/set-relay-topic)

Route inbound calls to a Relay topic.

## **PhoneCallHandler**

For callers passing `call_handler` directly to [`update`][update], the
`PhoneCallHandler` const provides typed values. It is a `const`-as-enum
(`as const` object plus a same-named string-union type), so passing a member
serializes to its wire value with full type-checking on the call site.

```typescript
import { PhoneCallHandler } from "@signalwire/sdk";

await client.phoneNumbers.update("phone-number-id", {
  call_handler: PhoneCallHandler.AI_AGENT,
  call_ai_agent_id: "ai-agent-id",
});
```

| Member              | Wire value          | Companion field            | Auto-creates        |
| ------------------- | ------------------- | -------------------------- | ------------------- |
| `RELAY_SCRIPT`      | `relay_script`      | `call_relay_script_url`    | `swml_webhook`      |
| `LAML_WEBHOOKS`     | `laml_webhooks`     | `call_request_url`         | `cxml_webhook`      |
| `LAML_APPLICATION`  | `laml_application`  | `call_laml_application_id` | `cxml_application`  |
| `AI_AGENT`          | `ai_agent`          | `call_ai_agent_id`         | `ai_agent`          |
| `CALL_FLOW`         | `call_flow`         | `call_flow_id`             | `call_flow`         |
| `RELAY_APPLICATION` | `relay_application` | `call_relay_application`   | `relay_application` |
| `RELAY_TOPIC`       | `relay_topic`       | `call_relay_topic`         | (routes via Relay)  |

> **Note**
>
> `LAML_WEBHOOKS` (wire value `laml_webhooks`) produces a **cXML** handler, not a
> generic webhook. For SWML, use `RELAY_SCRIPT` -- or, more conveniently, the
> [`setSwmlWebhook`][setswml] helper.

> Search and manage phone numbers, and bind inbound calls to handlers.

## Docs

- [create](https://signalwire.com/docs/server-sdks/reference/typescript/rest/phone-numbers/create.md): Purchase a phone number.
- [delete](https://signalwire.com/docs/server-sdks/reference/typescript/rest/phone-numbers/delete.md): Release a phone number from the project.
- [get](https://signalwire.com/docs/server-sdks/reference/typescript/rest/phone-numbers/get.md): Retrieve details for a specific phone number.
- [list](https://signalwire.com/docs/server-sdks/reference/typescript/rest/phone-numbers/list.md): List phone numbers owned by the project.
- [search](https://signalwire.com/docs/server-sdks/reference/typescript/rest/phone-numbers/search.md): Search for available phone numbers to purchase.
- [setAiAgent](https://signalwire.com/docs/server-sdks/reference/typescript/rest/phone-numbers/set-ai-agent.md): Route inbound calls to an AI Agent Fabric resource by ID.
- [setCallFlow](https://signalwire.com/docs/server-sdks/reference/typescript/rest/phone-numbers/set-call-flow.md): Route inbound calls to a Call Flow by ID.
- [setCxmlApplication](https://signalwire.com/docs/server-sdks/reference/typescript/rest/phone-numbers/set-cxml-application.md): Route inbound calls to an existing cXML application by ID.
- [setCxmlWebhook](https://signalwire.com/docs/server-sdks/reference/typescript/rest/phone-numbers/set-cxml-webhook.md): Route inbound calls to a cXML (LAML) webhook.
- [setRelayApplication](https://signalwire.com/docs/server-sdks/reference/typescript/rest/phone-numbers/set-relay-application.md): Route inbound calls to a named Relay application.
- [setRelayTopic](https://signalwire.com/docs/server-sdks/reference/typescript/rest/phone-numbers/set-relay-topic.md): Route inbound calls to a Relay topic.
- [setSwmlWebhook](https://signalwire.com/docs/server-sdks/reference/typescript/rest/phone-numbers/set-swml-webhook.md): Route inbound calls to an SWML webhook URL.
- [update](https://signalwire.com/docs/server-sdks/reference/typescript/rest/phone-numbers/update.md): Update configuration for a phone number.