# client.phone_numbers

> The phone_numbers methods of the morevoice Python SDK: Phone numbers on your account.

Phone numbers on your account. These methods are on `client.phone_numbers`, where `client` is a `MoreVoice` client (see [the Python SDK](https://docs.morevoice.ai/sdk/python/#connect)). On `AsyncMoreVoice` the same methods are awaited. Each one returns the response object and raises an exception when the API answers with an error.

## `create()`

**Create a sandbox number (test mode).** With a test key: allocates a sandbox number (`source: sandbox`) in the +972 50 999 range, at no cost and with no carrier, at most 5 per organisation. Dial it with `POST /v1/test_helpers/inbound_calls`. A sandbox number never receives real calls. With a live key the endpoint is not available yet (buy numbers in the dashboard).

```python
# client.phone_numbers
def create(self, body: _m.PhoneNumberCreateParamsInput | Mapping[str, Any] | Unset = UNSET, *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.PhoneNumber
```

`client.phone_numbers.create()` · `await async_client.phone_numbers.create()` · `POST /phone_numbers` · [API reference](https://docs.morevoice.ai/api/operations/phone_numbers_create/)

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `assistant_id` | `string` | no | Inbound test calls to the number reach this assistant. |
| `flow_id` | `string` | no | Inbound test calls to the number run this published flow. |
| `inbound_route_id` | `string` | no | Inbound test calls to the number follow this inbound route. |
| `label` | `string` | no | A name for the number, shown in lists. |

### Returns

`PhoneNumber`:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The number's ID (stable). |
| `object` | `"phone_number"` | Always `phone_number`. |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `e164` | `string` | The number in E.164. |
| `country` | `string \| null` | ISO 3166-1 alpha-2, when known. |
| `source` | `"provisioned" \| "connection" \| "sandbox"` | `provisioned`: bought through the platform. `connection`: a number of your own SIP connection (its caller IDs and the numbers your inbound routes match). `sandbox`: a test-mode number. |
| `provider` | `string \| null` | The carrier of a provisioned number; null for your own connections. |
| `status` | `string` | `active`; provisioned numbers can also be `pending`, `pending_kyc`, `porting_in`, `suspended`, `releasing` or `released`. |
| `connection_id` | `string \| null` | `conn_…` ID. |
| `inbound_route_id` | `string \| null` | `rte_…` ID. |
| `label` | `string \| null` | — |
| `inbound` | `boolean` | Calls to the number are answered here (a route or connection matches it). |
| `outbound_caller_id` | `boolean` | The number can be presented as caller ID on outbound calls. |
| `created` | `string \| null` | When the number was added (null for numbers derived from a connection). |

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

phone_number = client.phone_numbers.create({
    "assistant_id": "asst_4Gk2LmN9pQ4rS6tV8wX0yZ",
    "label": "Support line (test)",
})
print(phone_number)
```

## `delete()`

**Release a sandbox number (test mode).** With a test key: releases a sandbox number. With a live key the endpoint is not available yet.

```python
# client.phone_numbers
def delete(self, id: str, *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.DeletedPhoneNumber
```

`client.phone_numbers.delete()` · `await async_client.phone_numbers.delete()` · `DELETE /phone_numbers/{id}` · [API reference](https://docs.morevoice.ai/api/operations/phone_numbers_delete/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A phone number ID (`pn_…`). |

### Returns

`DeletedPhoneNumber`:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The released number's ID. |
| `object` | `"phone_number"` | Always `phone_number`. |
| `deleted` | `true` | — |

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

deleted_phone_number = client.phone_numbers.delete("pn_7Hk2Lm9Qp")
print(deleted_phone_number)
```

## `list()`

**List phone numbers.** Numbers bought through the platform, then the numbers of your own SIP connections (their caller IDs and the numbers your inbound routes match exactly). Test-mode keys list sandbox numbers.

```python
# client.phone_numbers
def list(self, *, limit: int | Unset = 20, starting_after: str | Unset = UNSET, ending_before: str | Unset = UNSET, more_voice_version: str | Unset = UNSET) -> AsyncPage[_m.PhoneNumber]
```

`client.phone_numbers.list()` · `await async_client.phone_numbers.list()` · `GET /phone_numbers` · [API reference](https://docs.morevoice.ai/api/operations/phone_numbers_list/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer` | no | How many objects to return, 1–100 (default 20). |
| `starting_after` | `string` | no | A cursor (`next_cursor`) or object ID: return the objects after it (older). |
| `ending_before` | `string` | no | A cursor or object ID: return the objects before it (newer). |

### Returns

A page of results (`PhoneNumberList`): `data`, `has_more` and `next_cursor`.

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

for phone_number in client.phone_numbers.list():
    print(phone_number)
```

## `retrieve()`

**Retrieve a phone number.** Returns a phone number: its E.164 form, where it comes from (`source`: a number of one of your SIP connections, a number provisioned through the platform, or a test-mode sandbox number), whether it answers inbound calls (and the route that answers them) and whether it can be the caller ID of outbound calls.

```python
# client.phone_numbers
def retrieve(self, id: str, *, more_voice_version: str | Unset = UNSET) -> _m.PhoneNumber
```

`client.phone_numbers.retrieve()` · `await async_client.phone_numbers.retrieve()` · `GET /phone_numbers/{id}` · [API reference](https://docs.morevoice.ai/api/operations/phone_numbers_retrieve/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A phone number ID (`pn_…`). |

### Returns

`PhoneNumber`:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The number's ID (stable). |
| `object` | `"phone_number"` | Always `phone_number`. |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `e164` | `string` | The number in E.164. |
| `country` | `string \| null` | ISO 3166-1 alpha-2, when known. |
| `source` | `"provisioned" \| "connection" \| "sandbox"` | `provisioned`: bought through the platform. `connection`: a number of your own SIP connection (its caller IDs and the numbers your inbound routes match). `sandbox`: a test-mode number. |
| `provider` | `string \| null` | The carrier of a provisioned number; null for your own connections. |
| `status` | `string` | `active`; provisioned numbers can also be `pending`, `pending_kyc`, `porting_in`, `suspended`, `releasing` or `released`. |
| `connection_id` | `string \| null` | `conn_…` ID. |
| `inbound_route_id` | `string \| null` | `rte_…` ID. |
| `label` | `string \| null` | — |
| `inbound` | `boolean` | Calls to the number are answered here (a route or connection matches it). |
| `outbound_caller_id` | `boolean` | The number can be presented as caller ID on outbound calls. |
| `created` | `string \| null` | When the number was added (null for numbers derived from a connection). |

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

phone_number = client.phone_numbers.retrieve("pn_7Hk2Lm9Qp")
print(phone_number)
```