Membeli dan melepas nomor
Membeli nomor membutuhkan dua panggilan: cari nomor yang dijual di suatu negara, lalu pesan yang Anda inginkan. Semua langkah di sini memerlukan kunci API dengan scope numbers, dan pembelian pertama dalam organisasi memerlukan verifikasi identitas.
Cari di suatu negara
Pencarian selalu dibatasi pada satu negara, jadi country_code wajib diisi. Persempit lebih lanjut dengan number_type, capabilities, atau prefix dari digit nasional.
// The search is always country-scoped, so country_code is required.
const page = await bird.numbers.available.list({
country_code: "GB",
capabilities: ["sms", "voice"],
});
for (const candidate of page.data) {
console.log(candidate.number, candidate.number_type);
}# The search is always country-scoped, so country_code is required.
page = client.numbers.available.list(country_code="GB", capabilities=["sms", "voice"])
for candidate in page.data:
print(candidate.number, candidate.number_type)for candidate, err := range client.Numbers.Available.List(context.Background(), bird.NumbersAvailableListParams{
CountryCode: "GB",
Capabilities: []string{"sms", "voice"},
}) {
if err != nil {
log.Fatal(err)
}
fmt.Println(candidate.Number, candidate.NumberType)
}// The search is always country-scoped, so country_code is required.
$page = $bird->numbers->available->list([
'country_code' => 'GB',
'capabilities' => ['sms', 'voice'],
]);
foreach ($page as $candidate) {
echo $candidate->getNumber(), ' ', $candidate->getNumberType(), "\n";
}curl "https://us1.platform.bird.com/v1/numbers/available?country_code=GB" \
-H "Authorization: Bearer bk_us1_..."Gunakan host regional yang sesuai dengan prefiks bk_{region}_ kunci Anda: https://us1.platform.bird.com atau https://eu1.platform.bird.com.
Setiap hasil hanya berisi informasi yang Anda butuhkan untuk memilih satu nomor:
Contoh kode
{
"data": [
{
"number": "+447700900123",
"country_code": "GB",
"number_type": "mobile",
"capabilities": ["sms", "voice"]
}
],
"next_cursor": null,
"prev_cursor": null
}Inventaris kami sendiri ditampilkan lebih dulu dan dipaginasi seperti biasa. Halaman terakhir dapat menyertakan nomor yang ditawarkan langsung oleh operator, sehingga nomor yang baru saja tercantum mungkin sudah tidak tersedia saat Anda memesannya.
Untuk memastikan nomor masih tersedia sebelum memesannya, baca kembali dengan GET /v1/numbers/available/{number}. 404 berarti nomor tersebut saat ini tidak tersedia untuk dijual, baik karena operator menariknya maupun inventaris kami sudah mencadangkannya. Pengecekan ulang ini menggunakan batas laju numbers_availability yang sama dengan pencarian, jadi cek ulang hanya kandidat yang akan Anda pesan, bukan semua hasil.
Pesan nomor
Kirimkan nomor dari hasil pencarian ke POST /v1/numbers/orders. Untuk perlindungan percobaan ulang, lihat Idempotensi.
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";
}curl -X POST "https://us1.platform.bird.com/v1/numbers/orders" \
-H "Authorization: Bearer bk_us1_..." \
-H "Content-Type: application/json" \
-d '{"number": "+447700900123"}'Sebagian besar pesanan selesai dalam permintaan dan menjawab 201 dengan nomor yang sudah menjadi milik Anda:
Contoh kode
{
"id": "nor_01m0da22b0e39anhzyhtw3gzdg",
"number": "+447700900123",
"country_code": "GB",
"number_type": "mobile",
"status": "completed",
"number_id": "nda_7eqywfwzxwa1za9n8wp7e1xkr8",
"failure_reason": null,
"completed_at": "2026-08-19T15:25:56.479320Z",
"created_at": "2026-08-19T15:25:56.448051Z",
"updated_at": "2026-08-19T15:25:56.479320Z"
}number_id adalah handle untuk semua langkah selanjutnya: membaca nomor dan melepasnya.
Polling pesanan yang belum selesai
Pesanan yang harus menunggu operator menjawab 202, dengan number_id masih null. Baca kembali hingga status bernilai completed atau failed.
const order = await bird.numbers.orders.get("nor_01krdgeqcxet5s7t44vh8rt9mg");
// failure_reason says what went wrong, and only ever on a failed order.
console.log(order.status, order.failure_reason ?? "");order = client.numbers.orders.get("nor_01krdgeqcxet5s7t44vh8rt9mg")
# failure_reason says what went wrong, and only ever on a failed order.
print(order.status, order.failure_reason or "")order, err := client.Numbers.Orders.Get(context.Background(), "nor_01krdgeqcxet5s7t44vh8rt9mg")
if err != nil {
log.Fatal(err)
}
// FailureReason says what went wrong, and only ever on a failed order.
fmt.Println(order.Status)$order = $bird->numbers->orders->get('nor_01krdgeqcxet5s7t44vh8rt9mg');
// failure_reason says what went wrong, and only ever on a failed order.
echo $order->getStatus(), ' ', $order->getFailureReason() ?? '', "\n";curl "https://us1.platform.bird.com/v1/numbers/orders/nor_01m0da22b0e39anhzyhtw3gzdg" \
-H "Authorization: Bearer bk_us1_..."Pesanan melewati charging, ordering, dan pending sebelum selesai. Pada failed, failure_reason menjelaskan kesalahan yang terjadi secara ringkas. Biaya setup yang sudah ditagih tidak dikembalikan, sehingga pesanan gagal bisa menyisakan tagihan; hubungi dukungan jika ini terjadi.
Lepas nomor
Melepas nomor menghentikan tagihan bulanan dan nomor berhenti berfungsi untuk Anda. Hanya nomor dedicated yang dapat dilepas, dan nomor yang dilepas tidak langsung kembali dijual.
// Releasing stops the monthly charge and the number stops working for you.
// Only a dedicated number can be released; a shared one answers E14002.
await bird.numbers.release("nda_01krdgeqcxet5s7t44vh8rt9mg");# Releasing stops the monthly charge and the number stops working for you.
# Only a dedicated number can be released; a shared one answers E14002.
client.numbers.release("nda_01krdgeqcxet5s7t44vh8rt9mg")// Only a dedicated number can be released; a shared one answers E14002.
if err := client.Numbers.Release(context.Background(), "nda_01krdgeqcxet5s7t44vh8rt9mg"); err != nil {
log.Fatal(err)
}// Releasing stops the monthly charge and the number stops working for you.
// Only a dedicated number can be released; a shared one answers E14002.
$bird->numbers->release('nda_01krdgeqcxet5s7t44vh8rt9mg');curl -X DELETE "https://us1.platform.bird.com/v1/numbers/nda_7eqywfwzxwa1za9n8wp7e1xkr8" \
-H "Authorization: Bearer bk_us1_..."Pelepasan yang berhasil menjawab 204 tanpa body.
Ketika pesanan ditolak
Empat penolakan mencakup hampir semua pembelian gagal.
402 dengan E03000 berarti saldo wallet tidak cukup untuk nomor tersebut. Isi ulang dan pesan lagi. Tidak ada pesanan yang dibuat, jadi tidak ada yang ditagih.
412 berarti organisasi belum menyelesaikan verifikasi identitas yang diperlukan untuk pembelian pertama. Selesaikan verifikasi, lalu coba lagi.
409 dengan E14000 berarti nomor tersebut sudah tidak tersedia saat Anda memilihnya. Cari lagi dan pilih nomor lain.
409 dengan E14001 berarti terlalu banyak pesanan Anda yang masih berjalan. Tunggu salah satu selesai, lalu pesan lagi.
Langkah selanjutnya
- Ikhtisar Numbers menjelaskan arti setiap field pada sebuah nomor.
- Referensi API Numbers mendokumentasikan setiap operasi dan field.
- Idempotency menjelaskan bagaimana key membuat pesanan yang dicoba ulang tetap aman.
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.