numbers

Get a number order

Returns a single number order by id, including its current lifecycle state and, once completed, the number it produced.

get/v1/numbers/orders/{order_id}

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/numbers/orders/{order_id}
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Path parameters

order_idstring required
Example:nor_01krdgeqcxet5s7t44vh8rt9mg

Identifier of the order.

Headers

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.

Response

The order.

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.