<!-- Source: https://docs.vinsi.ai/api-docs/phone-number-create -->
# Create Phone Number

Purchase a phone number (E.164, usually picked from Get Phone Numbers by Area Code) and add it to your organization. Uses 1 phone credit, which is refunded if provisioning fails. Toll-free numbers are not allowed. Returns 400 when you have no phone credits or the number is already in your account, and 409 when it belongs to another organization. Responds 201. Assign an agent afterwards with Update Phone Number.

```http
POST https://dashboard.vinsi.ai/api/phone-numbers
```

## Authentication

Send your API key in the `x-api-key` header. Create keys in the VINSI dashboard under Settings → API Keys.

## Headers

| Name | Type | Required |
|---|---|---|
| Content-Type | string | yes (application/json) |
| x-api-key | string | yes |

## Example request body

```json
{
  "phoneNumber": "+16195550123"
}
```

## Example request

```bash
curl -X POST 'https://dashboard.vinsi.ai/api/phone-numbers' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"phoneNumber":"+16195550123"}'
```

## Example response

```json
{
  "success": true,
  "phoneNumber": {
    "id": "phn_1757964000123_k2j4h5g6f",
    "phoneNumber": "+16195550123",
    "providerId": "2468013579246801357",
    "provider": "telnyx",
    "orderId": "3f1b2c4d-0000-4000-8000-000000000001",
    "orderStatus": "success",
    "livekitTrunkId": "ST_exampleTrunk01",
    "livekitTrunkConfigured": true,
    "dispatchRuleId": null
  }
}
```