---
title: "Create a number order"
method: POST
path: "/v1/numbers/orders"
tags: ["numbers"]
---

# Create a number order

`POST /v1/numbers/orders`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/numbers/orders`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

Orders a number for your workspace and starts its recurring charge. The available number's
`pricing` is the current price, not a quote: the order resolves the price again when it
charges, so a price published in between applies. Pass a
number from `GET /v1/numbers/available`. Whether the number is already in
inventory or acquired from a supplier, the response contains an order.

Most orders complete immediately and return `201` with `status` of
`completed` and `number_id` populated. Read the number with
`GET /v1/numbers/{number_id}`. An order that cannot complete in the request
returns `202`; poll `GET /v1/numbers/orders/{order_id}` until it is
`completed` or `failed`.

A `412` means required identity verification is incomplete or organization
eligibility prevents the purchase. Follow the error's recovery guidance:
complete missing verification, or contact support about an eligibility review
or denial. An eligibility assessment still in progress returns `503`; retry later.

## Headers

- `Idempotency-Key` string
- `X-Workspace-Id` string
- `X-Organization-Id` string

## Request body

- NumbersOrderCreate
  - `number` string, required: The number to acquire, in E.164 format, as returned by `GET /v1/numbers/available`.
  - `reference` string: Your own reference to set on the number when this purchase completes. Leading and trailing whitespace is removed. A pending order keeps the reference until the number is allocated.

## Response `201`

The order completed and the number is now allocated to your workspace. Its status is completed, with number and number_id populated.

- NumbersOrder
  - `id` string, required
  - `number` string, required: The number being acquired, in E.164 format.
  - `country_code` string, required: ISO 3166-1 alpha-2 country code.
  - `number_type` string, required: Physical type of a phone number. New number types may be added over time, so treat unrecognized values as supported types rather than errors.
  - `status` string, required: Lifecycle state of a number purchase order: - `charging`: Securing funds. - `ordering`: Placing the order with the carrier. - `pending`: The carrier accepted the order and is provisioning the number. - `completed`: Your workspace owns the number. - `failed`: The purchase did not complete. A setup fee already charged is non-refundable. Contact support about a failed order.
  - `number_id` string
  - `failure_reason` string, nullable: Human-readable reason the purchase failed. `null` unless status is failed. An order can fail some time after it was created, so `updated_at` tells you when the failure was recorded rather than when the order was placed.
  - `completed_at` string, date-time, nullable: When the purchase completed and the number became owned (status completed). `null` for orders still in progress or failed.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `202`: The order was accepted but could not complete in this request. Poll it for completion.
- `400`: Bad request
- `401`: Authentication required
- `402`: Insufficient balance
- `403`: Insufficient permissions
- `404`: Resource not found
- `409`: Resource conflict
- `412`: Precondition failed
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)