numbers

Create a number order

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.

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

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Request body

numberstring required

The number to acquire, in E.164 format, as returned by GET /v1/numbers/available.

referencestring

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.

Example request

{
  "number": "+18005550100",
  "reference": "STORE-042"
}

Response

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

idstring required
numberstring required

The number being acquired, in E.164 format.

country_codestring required

ISO 3166-1 alpha-2 country code.

number_typestring 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.

statusstring 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_idstring
failure_reasonstring 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_atstring date-time nullable

When the purchase completed and the number became owned (status completed). null for orders still in progress or failed.

created_atstring date-time required
updated_atstring date-time required

Example response

{
  "id": "nor_01krdgeqcxet5s7t44vh8rt9mg",
  "country_code": "US",
  "number_id": "nda_01krdgeqcxet5s7t44vh8rt9mg"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.