Sign inGet Started

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);
}
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);
}
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 ?? "");
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");
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