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"
  }'

Respuesta201

{
  "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.

Cuerpo de la solicitud

number

string

obligatorio

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.

Mostrar parámetros secundarios

compliance.answers

array

obligatorio

Every answer at once, in the same shape POST /v1/compliance/submissions takes. There is no draft to fill in over several calls, so send a complete set.

Mostrar parámetros secundarios

compliance.answers.key

string

obligatorio

The requirement this answers, as given by its key in the requirements read.

compliance.answers.value

string

obligatorio

The answer, for a requirement answered inline. Send every answer as a string whatever its data type, so a number goes as "1500" and a yes-or-no as "true".

compliance.answers.key

string

obligatorio

The requirement this answers, as given by its key in the requirements read.

compliance.answers.attachment_id

string

obligatorio

The uploaded document, for a requirement that takes one. Upload the file as an attachment first, then send the id it returns.

compliance.answers.key

string

obligatorio

The requirement this answers, as given by its key in the requirements read.

compliance.answers.values

array of string

obligatorio

The answers, for a requirement whose max_items is set and which is answered inline. Send each as a string whatever its data type, and send them in the order you mean them to be read. At most max_items of them.

compliance.answers.key

string

obligatorio

The requirement this answers, as given by its key in the requirements read.

compliance.answers.attachment_ids

array of string

obligatorio

The uploaded documents, for a requirement whose max_items is set and which takes documents. Upload each file first and send the ids it returns, in order. At most max_items of them.

compliance.identity_id

string

An existing party this number is held for. It fills in the business details you left out from what that party already holds, and each single-value answer you file about the party is written back onto it for next time, whatever the verdict. Documents and multi-value answers are asked fresh each time. An id belonging to another organization is rejected.

Carga de respuesta

id

string

obligatorio

Identifier of this purchase order.

number

string

obligatorio

The number being acquired, in E.164 format.

country_code

string

obligatorio

ISO 3166-1 alpha-2 country code.

number_type

string

obligatorio

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

obligatorio

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

obligatorio

updated_at

string

obligatorio

Continúa con la documentación, guías y ejemplos de este tema.

Obtener un resumen de implementación

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"
  }'

Respuesta201

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

Create a number order

Cuerpo de la solicitud

Carga de respuesta

Recursos relacionados