> 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/python/rest/client

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

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

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

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

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

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

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

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

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

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

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

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

[setrelaytopic]: /docs/server-sdks/reference/python/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.phone_numbers` on a [`RestClient`][restclient] instance.

```python {9}
from signalwire.rest import RestClient

client = RestClient(
    project="your-project-id",
    token="your-api-token",
    host="your-space.signalwire.com",
)

available = client.phone_numbers.search(areacode="512")
for number in available.get("data", []):
    print(number["phone_number"])
```

## **Methods**

### Standard CRUD

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

List phone numbers owned by the project.

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

Purchase a phone number.

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

Retrieve details for a specific phone number.

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

Update configuration for a phone number.

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

Release a phone number from the project.

#### [search](/docs/server-sdks/reference/python/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
keyword arguments through to `update` for fields the helper doesn't name explicitly.
Setting a binding auto-materializes the matching Fabric resource on the server.

#### [set\_swml\_webhook](/docs/server-sdks/reference/python/rest/phone-numbers/set-swml-webhook)

Route inbound calls to an SWML webhook URL.

#### [set\_cxml\_webhook](/docs/server-sdks/reference/python/rest/phone-numbers/set-cxml-webhook)

Route inbound calls to a cXML (LAML) webhook.

#### [set\_cxml\_application](/docs/server-sdks/reference/python/rest/phone-numbers/set-cxml-application)

Route inbound calls to an existing cXML application by ID.

#### [set\_ai\_agent](/docs/server-sdks/reference/python/rest/phone-numbers/set-ai-agent)

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

#### [set\_call\_flow](/docs/server-sdks/reference/python/rest/phone-numbers/set-call-flow)

Route inbound calls to a Call Flow by ID.

#### [set\_relay\_application](/docs/server-sdks/reference/python/rest/phone-numbers/set-relay-application)

Route inbound calls to a named Relay application.

#### [set\_relay\_topic](/docs/server-sdks/reference/python/rest/phone-numbers/set-relay-topic)

Route inbound calls to a Relay topic.

## **PhoneCallHandler enum**

For callers passing `call_handler` directly to [`update`][update], the
`PhoneCallHandler` enum provides typed values. Each member is a `str` subclass, so
passing the enum member serializes to the wire value without `.value` indirection.

```python
from signalwire.rest import PhoneCallHandler

client.phone_numbers.update(
    "phone-number-id",
    call_handler=PhoneCallHandler.AI_AGENT,
    call_ai_agent_id="ai-agent-id",
)
```

| Enum 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
> [`set_swml_webhook`][setswml] helper.

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

## Docs

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