---
title: "Provision a US local number for an inbox"
method: POST
path: "/api/v1/inboxes/{id}/phone-number"
tags: ["SMS"]
---

# Provision a US local number for an inbox

`POST /api/v1/inboxes/{id}/phone-number`

## Request

- Base URL: `https://cooperemail.com`
- URL: `https://cooperemail.com/api/v1/inboxes/{id}/phone-number`
- Auth: HTTP bearer

Requires inbox_update. A verified owner is required (HTTP 409 owner_required). One active number per inbox (HTTP 409 inbox_has_number). Free includes 0 numbers and returns HTTP 402 plan_limit_exceeded. Starter can hold up to 3. Pro includes 3 and caps at 25. A number past the included ones is $3/month and includes 100 segments. The same account can provision at most 3 numbers per 24 hours (HTTP 409 provision_limit) and waits 30 days before provisioning an E.164 it released (HTTP 409 number_cooldown). A paused inbox is HTTP 403 inbox_paused. With COOPER_SMS_BILLING=stripe, a billable number is added to the Stripe subscription (prorated) before Cooper buys it. If Stripe refuses, nothing is bought and the call returns HTTP 503 sms_billing_failed. billing.status is included or billed. Without that setting, billing.status is stub and this route does not call Stripe. Releasing later lowers the subscription quantity when billing is on. A grandfathered account is treated as Free for numbers unless it has a Starter or Pro subscription while SMS billing is on. Operators are not capped and are not billed. Idempotency-Key replays the same number. HTTP 404 not_found when SMS is off.

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- object: One of area_code or phone_number is required.
  - `area_code` string: 3-digit US area code.
  - `phone_number` string: E.164 US or Canada number.

## Response `200`

Idempotency-Key replay of the same request.

## Other responses

- `201`: Provisioned number, including billing.
- `402`: plan_limit_exceeded. Includes upgrade_url.
- `403`: inbox_paused
- `404`: not_found or inbox_not_found
- `409`: owner_required, inbox_has_number, provision_limit, number_cooldown, or phone_number_exists
- `503`: sms_billing_failed. Nothing was purchased.

---

[API](https://skmtc.dev/cooperemail/apis/cooper-email-api.md) · [All operations](https://skmtc.dev/cooperemail/apis/cooper-email-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cooperemail/apis/cooper-email-api/revisions/6d800a7b3e33?raw)