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 menjelaskan nomor tersebut:

Contoh kode
{
  "data": [
    {
      "number": "+447700900123",
      "country_code": "GB",
      "number_type": "mobile",
      "capabilities": ["sms", "voice"],
      "pricing": {
        "setup_price": { "amount": "0.00995", "currency_code": "USD" },
        "recurring_price": { "amount": "0.00995", "currency_code": "USD" },
        "recurring_period": { "unit": "month", "count": 1 },
        "intervals_per_charge": 12
      }
    }
  ],
  "next_cursor": null,
  "prev_cursor": null
}

Setiap hasil juga memuat objek pricing dengan harga untuk organisasi Anda, sebelum pajak dan dalam mata uang penagihan Anda:

  • setup_price dikenakan sekali saat Anda memesan nomor. Biaya terbitan sebesar nol memiliki amount bernilai "0". Field itu sendiri bernilai null jika tidak ada biaya setup, dan juga setiap kali recurring_price bernilai null, karena nomor tersebut tidak dapat dipesan.
  • recurring_price adalah tarif per recurring_period.
  • intervals_per_charge adalah jumlah recurring_period yang tercakup dalam satu tagihan. Tagihan berulang sebelum pajak adalah recurring_price dikalikan intervals_per_charge, dikenakan saat nomor ditetapkan ke workspace Anda dan pada setiap perpanjangan. Untuk pesanan yang menunggu operator, penetapan terjadi saat pesanan selesai. recurring_period satu bulan dengan intervals_per_charge: 12 menagih 12 bulan sekaligus.

Referensi API menampilkan contoh hasil beserta harganya. Hasil pencarian dengan pricing.recurring_price: null tidak memberikan harga berulang. Hubungi tim penjualan untuk mendapatkan harga bagi negara dan jenis nomor tersebut sebelum memesan.

Dasbor dan API menggunakan harga organisasi yang sama, termasuk konversi ke mata uang penagihan Anda. Membaca harga tidak mengunci penawaran harga: perubahan tarif atau nilai tukar sebelum tagihan berikutnya dapat mengubah jumlahnya. Jika pencarian harga gagal, pencarian mengembalikan 503 dengan E14009. Coba lagi pembacaan tersebut dengan exponential backoff; kegagalan pencarian harga tidak pernah berarti nomor itu tidak dikenai biaya.

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 berulang dan nomor berhenti berfungsi untuk Anda. Hanya nomor dedicated yang dapat dilepas, dan nomor yang dilepas tidak langsung kembali dijual.

// Releasing stops the recurring 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. Untuk mempertahankan nomor hingga akhir periode yang sudah Anda bayar, batalkan saja: Mengelola nomor telepon Anda menjelaskan keduanya.

Ketika pesanan ditolak

Empat alasan penolakan mencakup hampir semua pembelian yang 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

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