# Phone numbers: Add a phone number (https://docs.envocal.ai/api-reference/phone-numbers/add-a-phone-number/)

> Registers a number to the tenant so it can be assigned to an agent. Calls to the number must also be routed to the platform by your telephony provider (SIP trunk). Numbers are unique across the platform.

## POST `/v1/tenants/{tenantId}/phone-numbers`

Registers a number to the tenant so it can be assigned to an agent. Calls to the number must also be routed to
the platform by your telephony provider (SIP trunk). Numbers are unique across the platform.

**Required permission:** `phone_numbers:write`

### Parameters

| Name | In | | Type | Description |
| --- | --- | --- | --- | --- |
| `tenantId` | path | required | string | Tenant id, or `current` for the key's own tenant. Must be the key's tenant or one of its sub-tenants. |

### Request body

`application/json`: PhoneNumberCreateDto

| Field | Type | | Description |
| --- | --- | --- | --- |
| `number` | string | required | The number in E.164 format, e.g. `+46812345678`. |

### Responses

**201** — PhoneNumberDto: Created.

| Field | Type | | Description |
| --- | --- | --- | --- |
| `id` | string | required | Phone number id. |
| `number` | string | required | The number in E.164 format, e.g. `+46812345678`. |
| `tenantId` | string | required | Tenant that owns the number. |
| `assignedAgentId` | string | nullable | Agent answering calls to this number, if assigned. |
| `assignedAgentName` | string | nullable | Name of that agent. |

**400**: Not in E.164 format.

**401**: Missing, invalid, revoked or expired API key.

**403**: The key lacks the required permission, or the tenant/resource is outside its reach.

**409**: The number already exists.

**429**: Rate limit exceeded. Retry after the number of seconds in the Retry-After header.

### Example

```bash
curl -X POST "https://api.envocal.ai/v1/tenants/current/phone-numbers" \
  -H "Authorization: Bearer evk_eu_..." \
  -H "Content-Type: application/json" \
  -d '{"number":"string"}'
```