Summary
Provision a US local number for an inbox 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.
Request
{
"area_code": "415"
}Response
HTTP 201. Sample values illustrate the schema.
{
"object": "phone_number",
"id": "inb_example",
"account_id": "acc_example",
"e164": "+14155550100",
"provider": "string",
"provider_sid": "string",
"number_type": "string",
"capabilities": [
"string"
],
"status": "pending",
"outbound": "string",
"created_at": "2026-10-18T12:00:00.000Z"
}Errors
- HTTP 409 owner_required
- HTTP 409 inbox_has_number
- HTTP 402 plan_limit_exceeded
- HTTP 409 provision_limit
- HTTP 409 number_cooldown
- HTTP 403 inbox_paused
- HTTP 503 sms_billing_failed
- HTTP 404 not_found
- HTTP 404 inbox_not_found
- HTTP 409 phone_number_exists
Idempotency
Idempotency-Key is 1 to 256 characters of letters, digits, and - . _ ~. The same key and the same request within 24 hours returns the original response with HTTP 200 and Idempotent-Replayed: true. A different request is HTTP 409 idempotency_key_conflict. A second call while the first is running is HTTP 409 idempotency_request_in_progress. An empty or invalid key is HTTP 400 invalid_idempotency_key. client_id is checked first when both are set.