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("allocated 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("allocated 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 'allocated as ', $order->getNumberId(), "\n";
} else {
    echo 'still ', $order->getStatus(), '; poll ', $order->getId(), "\n";
}

bird numbers orders create --number +18005550100 --reference STORE-042

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

Respons201

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

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.

Sending a compliance block uses the order's existing numbers scope at write level.

Payload Permintaan

number

string

wajib

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.

compliance

object

Ownership paperwork for a number being ordered, where its country requires any. Optional always: the order completes and the number is yours either way, and supplying this only decides whether it can carry traffic sooner. Read GET /v1/compliance/requirements for the number to learn what is asked for, or file it after the order with POST /v1/compliance/submissions. Filing this cannot fail your order: if it is refused, the number is still yours and you can file again. The answers are a legal representation filed under the name of the business they describe. Sending this block uses the order's existing numbers scope at write level.

Tampilkan parameter turunan

Payload Respons

id

string

wajib

Identifier of this purchase order.

number

string

wajib

The number being acquired, in E.164 format.

country_code

string

wajib

ISO 3166-1 alpha-2 country code.

number_type

string

wajib

Physical type of the number being acquired.

Possible values (may grow over time): mobile, local, national, short_code, short_code_fteu, toll_free

status

string

wajib

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.

Possible values (may grow over time): charging, ordering, pending, completed, failed

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

wajib

updated_at

string

wajib

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.

Dapatkan ringkasan implementasi

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("allocated 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("allocated 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 'allocated as ', $order->getNumberId(), "\n";
} else {
    echo 'still ', $order->getStatus(), '; poll ', $order->getId(), "\n";
}

bird numbers orders create --number +18005550100 --reference STORE-042

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

Respons201

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

Create a number order

Payload Permintaan

Payload Respons

Sumber daya terkait