Create a number order

POST

/v1/numbers/orders

const order = await bird.numbers.orders.create({ number: "+447700900201" });
// Most orders finish inside the request. One that has to wait on a carrier
// comes back without a number_id. Poll it until it is completed or failed.
if (order.status === "completed") {
  console.log("held as", order.number_id);
} else {
  console.log("still", order.status, "; poll", order.id);
}

order = client.numbers.orders.create(number="+447700900201")
# Most orders finish inside the request. One that has to wait on a carrier
# comes back without a number_id. Poll it until completed or failed.
if order.status == "completed":
    print("held as", order.number_id)
else:
    print("still", order.status, "; poll", order.id)

order, err := client.Numbers.Orders.Create(context.Background(), bird.NumbersOrdersCreateParams{
	Number: "+447700900201",
})
if err != nil {
	log.Fatal(err)
}
// An order that has to wait on a carrier comes back without a NumberId.
// Poll it until it is completed or failed.
fmt.Println(order.Status, order.Id)

$order = $bird->numbers->orders->create(
    (new NumbersOrderCreate())->setNumber('+447700900201'),
);
// Most orders finish inside the request. One that has to wait on a carrier
// comes back without a number_id. Poll it until it is completed or failed.
if ($order->getStatus() === 'completed') {
    echo 'held as ', $order->getNumberId(), "\n";
} else {
    echo 'still ', $order->getStatus(), '; poll ', $order->getId(), "\n";
}

curl -X POST "https://us1.platform.bird.com/v1/numbers/orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+18005550100"
  }'

Response201

{
  "id": "nor_01krdgeqcxet5s7t44vh8rt9mg",
  "country_code": "US",
  "number_type": "mobile",
  "status": "charging",
  "number_id": "nda_01krdgeqcxet5s7t44vh8rt9mg"
}

Orders a number for your workspace and starts its monthly charge. 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 the workspace has not completed the identity verification required to acquire a sender. Complete it, then retry.

Request Payload

number

string

आवश्यक

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

Response Payload

string

आवश्यक

Identifier of this purchase order.

number

string

आवश्यक

The number being acquired, in E.164 format.

country_code

string

आवश्यक

number_type

string

आवश्यक

Physical type of the number being acquired.

status

string

आवश्यक

number_id

nullable string

Identifier of the number this order produced, set when status is completed. Pass it as number_id to GET /v1/numbers/{number_id} or DELETE /v1/numbers/{number_id}. null until the order completes.

failure_reason

nullable string

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

nullable string

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

created_at

string

आवश्यक

updated_at

string

आवश्यक

const order = await bird.numbers.orders.create({ number: "+447700900201" });
// Most orders finish inside the request. One that has to wait on a carrier
// comes back without a number_id. Poll it until it is completed or failed.
if (order.status === "completed") {
  console.log("held as", order.number_id);
} else {
  console.log("still", order.status, "; poll", order.id);
}

order = client.numbers.orders.create(number="+447700900201")
# Most orders finish inside the request. One that has to wait on a carrier
# comes back without a number_id. Poll it until completed or failed.
if order.status == "completed":
    print("held as", order.number_id)
else:
    print("still", order.status, "; poll", order.id)

order, err := client.Numbers.Orders.Create(context.Background(), bird.NumbersOrdersCreateParams{
	Number: "+447700900201",
})
if err != nil {
	log.Fatal(err)
}
// An order that has to wait on a carrier comes back without a NumberId.
// Poll it until it is completed or failed.
fmt.Println(order.Status, order.Id)

$order = $bird->numbers->orders->create(
    (new NumbersOrderCreate())->setNumber('+447700900201'),
);
// Most orders finish inside the request. One that has to wait on a carrier
// comes back without a number_id. Poll it until it is completed or failed.
if ($order->getStatus() === 'completed') {
    echo 'held as ', $order->getNumberId(), "\n";
} else {
    echo 'still ', $order->getStatus(), '; poll ', $order->getId(), "\n";
}

curl -X POST "https://us1.platform.bird.com/v1/numbers/orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+18005550100"
  }'

Response201

{
  "id": "nor_01krdgeqcxet5s7t44vh8rt9mg",
  "country_code": "US",
  "number_type": "mobile",
  "status": "charging",
  "number_id": "nda_01krdgeqcxet5s7t44vh8rt9mg"
}