---
title: "Provision a phone number"
method: POST
path: "/v1/phone-numbers"
tags: ["phone-numbers"]
---

# Provision a phone number

`POST /v1/phone-numbers`

## Request

- Base URL: `https://api.mailfixture.com`
- URL: `https://api.mailfixture.com/v1/phone-numbers`
- Auth: HTTP bearer

Provisions a dedicated US number — no request body, US local is the only offering. Paid plans only. Numbers start `pending` and flip to `active` once the provider confirms (usually seconds). Creation shares the burst-10 creation bucket with inboxes.

## Response `201`

Number ordered.

- PhoneNumber
  - `created_at` string, date-time, required
  - `id` string, uuid, required
  - `phone_number` string, required: E.164, e.g. +15551234567.
  - `release_after` string, date-time, nullable, required: Scheduled auto-release after a plan downgrade put the account over its number cap; null when not scheduled. Cleared if the account comes back within cap.
  - `status` 'pending' | 'active', required: `pending` until the provider confirms the order.

## Other responses

- `401`: Missing bearer token, malformed key, or unknown/revoked/invalid API key.
- `403`: Account frozen, phone numbers require a paid plan (the free cap is 0), or the plan's number cap is reached (solo 1, team 3, scale 10).
- `429`: Per-key rate limit exceeded. `Retry-After` says when the next request will be admitted; the RateLimit headers name the bucket that refused (`requests` or `creates`) with `r=0`.
- `500`: Unexpected server error. `detail` is null — internals are never leaked.
- `503`: SMS is not configured on this deployment, or provisioning failed at the provider — safe to retry.

---

[API](https://skmtc.dev/mailfixture/apis/mailfixture-api.md) · [All operations](https://skmtc.dev/mailfixture/apis/mailfixture-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailfixture/apis/mailfixture-api/revisions/4ddefe29f6f6?raw)