# Create a sandbox number (test mode)

`POST https://api.morevoice.ai/v1/phone_numbers`

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

Authenticate with a secret API key: `Authorization: Bearer $MOREVOICE_API_KEY`.

Operation ID: `phone_numbers_create`.

## Parameters

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `MoreVoice-Version` | `string` | no | The API version to use for this request. Defaults to the version the API key is pinned to. |
| `Idempotency-Key` | `string` | no | A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice. |

## Request body

Optional, `application/json`.

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

Example:

```json
{
  "assistant_id": "asst_4Gk2LmN9pQ4rS6tV8wX0yZ",
  "label": "Support line (test)"
}
```

## Responses

### 201 Created

Created Returns `PhoneNumber`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The number's ID (stable). |
| `object` | `"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:

```json
{
  "connection_id": "conn_2Wq8RfLx0bZt7nKp1VdYhC",
  "country": "IL",
  "created": null,
  "e164": "+97231234567",
  "id": "pn_3TzKk4u7Q0Yx9b2LmN8pQr",
  "inbound": true,
  "inbound_route_id": "rte_5Hn3MpO0qR5sT7uW9xY1zA",
  "label": "Main trunk",
  "livemode": true,
  "object": "phone_number",
  "outbound_caller_id": true,
  "provider": null,
  "source": "connection",
  "status": "active"
}
```

### 400 Bad Request

The request is invalid: a parameter is missing, malformed or unknown, or the version header is unknown. Returns `ErrorEnvelope`.

### 401 Unauthorized

No valid API key was sent. Returns `ErrorEnvelope`.

### 403 Forbidden

The key may not do this (a missing scope, a plan limit, or a compliance block). Returns `ErrorEnvelope`.

### 409 Conflict

The request conflicts with the object's state, or the Idempotency-Key was reused with other parameters. Returns `ErrorEnvelope`.

### 429 Too Many Requests

Too many requests, or no call capacity right now. Retry after the Retry-After delay. Returns `ErrorEnvelope`.

### 500 Internal Server Error

Something went wrong on MoreVoice's side. Retry with the same Idempotency-Key. Returns `ErrorEnvelope`.

## Code samples

**TypeScript**

```ts
import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const phoneNumber = await mv.phoneNumbers.create({
	assistant_id: "asst_4Gk2LmN9pQ4rS6tV8wX0yZ",
	label: "Support line (test)",
});
console.log(phoneNumber);
```

**Python**

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

**cURL**

```sh
curl -X POST https://api.morevoice.ai/v1/phone_numbers \
  -H "Authorization: Bearer $MOREVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "assistant_id": "asst_4Gk2LmN9pQ4rS6tV8wX0yZ",
  "label": "Support line (test)"
}'
```