---
title: "Mengelola nomor telepon Anda"
description: "Daftar dan temukan nomor yang dialokasikan ke workspace Anda, beri label dengan nama dan referensi Anda sendiri, lihat voice record-nya, dan batalkan atau lepaskan melalui API."
canonical: "https://bird.com/id-id/dokumentasi/guides/numbers/managing-numbers"
---

# Mengelola nomor telepon Anda

Setelah nomor dialokasikan ke workspace Anda, API numbers memungkinkan Anda melihat daftar nomor yang Anda miliki, menemukan satu nomor berdasarkan pengenalnya, memberi label dengan nama dan referensi Anda sendiri, serta membatalkan atau melepaskannya saat tidak diperlukan lagi. Membaca memerlukan kunci API dengan cakupan `numbers` di level read; mengubah, membatalkan, atau melepaskan nomor memerlukan level write.

Halaman [**Numbers**](https://bird.com/dashboard/w/numbers) di dashboard menampilkan nomor yang sama.

## Daftar semua nomor yang Anda miliki

[`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers) mengembalikan nomor yang saat ini dialokasikan ke workspace Anda, terbaru lebih dulu, baik dedicated maupun shared. Setiap halaman memuat 25 nomor kecuali Anda meminta hingga 100 dengan `limit`.

Daftar ini dipaginasi dengan cursor. Kirimkan `next_cursor` dari suatu halaman kembali sebagai `starting_after` untuk membaca halaman berikutnya, dan berhenti saat `next_cursor` bernilai `null`. SDK mengikuti cursor untuk Anda. Contoh di bawah mempersempit daftar ke `country_code: "GB"`; hilangkan filter untuk menelusuri semua nomor yang Anda miliki:

**TypeScript**

```typescript
for await (const allocated of bird.numbers.list({ country_code: "GB" })) {
  console.log(allocated.number, allocated.kind, allocated.status);
}
```

Examples: [TypeScript](/id-id/dokumentasi/guides/numbers/managing-numbers.ts.md) · [Python](/id-id/dokumentasi/guides/numbers/managing-numbers.py.md) · [Go](/id-id/dokumentasi/guides/numbers/managing-numbers.go.md) · [PHP](/id-id/dokumentasi/guides/numbers/managing-numbers.php.md) · [MCP](/id-id/dokumentasi/guides/numbers/managing-numbers.mcp.md) · [cURL](/id-id/dokumentasi/guides/numbers/managing-numbers.curl.md)

Gunakan host regional yang sesuai dengan prefiks `bk_{region}_` kunci Anda: `https://us1.platform.bird.com` atau `https://eu1.platform.bird.com`.

Daftar ini tidak memuat total. Untuk menghitung nomor Anda, telusuri semua halaman hingga akhir dan hitung entri-entrinya. Mengirimkan `include_total` ditolak dengan `422` dan [`E01029`](/docs/api/errors/E01029).

Setiap entri memuat `status` dan `ownership`. Jika suatu negara tidak mewajibkan dokumen kepemilikan, `ownership` bernilai `null`. [Ikhtisar Numbers](/docs/guides/numbers/overview#the-status-of-an-allocated-number) menjelaskan arti setiap status. Untuk mengajukan dokumen kepemilikan yang masih ditunggu suatu nomor, lihat [Mengajukan dokumen kepemilikan nomor](/docs/guides/numbers/ownership-paperwork).

Setiap entri juga memuat `pricing`, yaitu jumlah yang dibayar organisasi Anda untuk nomor tersebut, sebelum pajak:

- `recurring_price` adalah tarif Anda per `recurring_period`, dalam mata uang yang digunakan untuk menagih nomor tersebut. Itu adalah mata uang penagihan Anda, kecuali langganan nomor dimulai sebelum mata uang penagihan Anda berubah; nomor seperti itu tetap memakai mata uang langganannya, yang disebutkan oleh `currency_code`.
- `intervals_per_charge` adalah jumlah `recurring_period` yang ditagih satu perpanjangan. Biaya berulang sebelum pajak adalah `recurring_price` dikalikan `intervals_per_charge`. Harga tetap untuk nomor tersebut mencakup seluruh periodenya, sehingga `intervals_per_charge` bernilai `1`.

`pricing` bernilai `null` untuk nomor `shared` dan untuk nomor tanpa langganan aktif. Jika langganan nomor tidak memiliki harga yang berlaku, harganya bernilai `null` dengan `pricing.error: null`; [hubungi tim penjualan](/contact-sales) agar nomor tersebut diberi harga. Jika harga tidak dapat dibaca, `pricing.error` berisi [`E14009`](/docs/api/errors/E14009) dan harganya bernilai `null`. Coba lagi [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) dengan exponential backoff. Nomor tersebut tetap tersedia untuk dikelola; jangan mengulangi pembaruan atau pembatalan yang sudah selesai untuk menyegarkan harganya.

Dashboard dan API menggunakan resolusi harga yang sama. Harga tetap mempertahankan ketentuannya yang ada; selain itu, yang ditampilkan adalah tarif saat ini, yang dapat berubah sebelum perpanjangan. Resolusi ini tidak melaporkan harga yang dikenakan oleh pesanan sebelumnya. Nomor dengan `releases_at` yang terisi mempertahankan `pricing`-nya hingga dilepas, dan tidak ada perpanjangan setelahnya.

## Temukan nomor dalam daftar Anda

Filter daftar saling digabungkan, jadi filter negara atau kemampuan tetap berlaku bersama filter lainnya.

`number` mencari satu nomor apa pun format yang Anda gunakan. `+31612345678` dan `0031612345678` mengarah ke nomor yang sama. Format nasional seperti `0612345678` hanya dapat ditemukan jika `country_code` menyebutkan negaranya:

```bash
curl "https://us1.platform.bird.com/v1/numbers?number=0612345678&country_code=NL" \
  -H "Authorization: Bearer bk_us1_..."
```

Jika Anda memasukkan nomor lengkap, atau format nasional beserta `country_code`-nya, tanpa filter lain, array `data` yang kosong berarti nomor tersebut tidak dialokasikan ke workspace Anda, termasuk nomor yang sudah Anda lepas. Format nasional tanpa `country_code`, misalnya `0612345678` saja, juga mengembalikan daftar kosong, jadi hasil tersebut tidak membuktikan bahwa nomor itu bukan milik Anda.

`search` mencocokkan sebagian nomor, nama, atau referensinya, tanpa membedakan huruf besar-kecil. `reference` mengembalikan nomor dengan referensi yang persis sama, dengan membedakan huruf besar-kecil:

```bash
curl "https://us1.platform.bird.com/v1/numbers?reference=STORE-042" \
  -H "Authorization: Bearer bk_us1_..."
```

`prefix` mengembalikan nomor yang diawali digit yang Anda berikan, dan arti digit tersebut bergantung pada `country_code`:

- Dengan `country_code`, digit yang dicocokkan adalah digit nasional, tepat setelah kode panggil. `prefix=6&country_code=NL` mengembalikan nomor Belanda yang diawali `+31 6`.
- Tanpa `country_code`, digit dicocokkan dari awal nomor lengkap. `prefix=6` saja mengembalikan nomor yang kode panggilnya diawali 6, seperti nomor `+61` Australia, sehingga tidak menemukan nomor ponsel Belanda Anda. Filter ini juga mencocokkan short code yang diawali digit tersebut.

## Beri nama nomor dan atur referensi Anda

Setiap nomor membawa dua label milik Anda. `name` membedakan nomor-nomor Anda, misalnya `Support line`. `reference` menyimpan pengidentifikasi dari catatan Anda sendiri, seperti id pelanggan atau toko, dan tidak harus unik. Keduanya berlaku untuk nomor dedicated maupun shared dan maksimal 100 karakter.

Atur keduanya dengan [`PATCH /v1/numbers/{number_id}`](/docs/api/reference/update-workspace-number). Field yang tidak Anda sertakan mempertahankan nilainya saat ini, dan field yang Anda kirim sebagai `null` akan dikosongkan. Spasi di awal dan akhir dihapus secara otomatis.

**TypeScript**

```typescript
const allocated = await bird.numbers.update("nda_01krdgeqcxet5s7t44vh8rt9mg", {
  name: "Support line",
  reference: "STORE-042",
});
console.log(allocated.name, allocated.reference);
```

Examples: [TypeScript](/id-id/dokumentasi/guides/numbers/managing-numbers.ts.md) · [Python](/id-id/dokumentasi/guides/numbers/managing-numbers.py.md) · [Go](/id-id/dokumentasi/guides/numbers/managing-numbers.go.md) · [PHP](/id-id/dokumentasi/guides/numbers/managing-numbers.php.md) · [MCP](/id-id/dokumentasi/guides/numbers/managing-numbers.mcp.md) · [cURL](/id-id/dokumentasi/guides/numbers/managing-numbers.curl.md)

Responsnya adalah `200` dengan nomor yang telah diperbarui. Untuk menghapus referensi dan mempertahankan nama, kirim referensi sebagai `null` dan jangan sertakan nama:

```bash
curl -X PATCH "https://us1.platform.bird.com/v1/numbers/nda_01krdgeqcxet5s7t44vh8rt9mg" \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{"reference": null}'
```

Untuk menetapkan referensi saat Anda membeli nomor, sertakan `reference` pada [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order). Pesanan yang harus menunggu operator tetap menyimpan referensi hingga nomor dialokasikan, dan nomor tersebut membawanya sejak saat itu.

## Menemukan voice record yang merutekan nomor

Nomor yang memiliki voice punya dua identifier. `id` pada `GET /v1/numbers` diawali dengan `nda_` untuk nomor dedicated dan `nal_` untuk nomor shared, dan operasi numbers menerimanya. Operasi voice, termasuk yang mengatur tujuan panggilan masuk, menerima voice record nomor tersebut, yang `id`-nya diawali dengan `vnu_`. Mengirim id `nda_` atau `nal_` ke operasi voice ditolak dengan `422`.

Untuk berpindah dari satu ke yang lain, cari voice numbers berdasarkan nomor telepon. Ini memerlukan cakupan `voice_management` di level read:

```bash
curl "https://us1.platform.bird.com/v1/voice/numbers?search=%2B31612345678" \
  -H "Authorization: Bearer bk_us1_..."
```

`id` pada entri tersebut adalah identifier `vnu_`, dan `provider.number_id`-nya adalah identifier `nda_` atau `nal_` dari nomor yang sama. [Menerima panggilan](/docs/guides/voice/receiving-calls) menunjukkan cara merutekan nomor dari sana.

Voice record memiliki `name` tersendiri. Memberi nama nomor dengan `PATCH /v1/numbers/{number_id}` tidak mengubah nama voice record, dan sebaliknya.

## Melepas nomor

Anda dapat mengembalikan nomor dedicated dengan dua cara:

- **Di akhir periode yang telah Anda bayar.** [`DELETE /v1/numbers/{number_id}`](/docs/api/reference/cancel-workspace-number) menghentikan perpanjangan nomor. Nomor tetap berfungsi hingga periode penagihan saat ini berakhir, lalu dilepas. Respons `202` mengembalikan nomor dengan `releases_at` disetel ke waktu tersebut, dan permintaan ulang mengembalikan `releases_at` yang sama. Pembatalan tidak dapat dibatalkan. Nomor tanpa langganan di belakangnya, misalnya nomor yang dialokasikan kepada Anda tanpa biaya, langsung dilepas, dan responsnya adalah `200` dengan `status` nomor disetel ke `released`.
- **Sekarang.** [`POST /v1/numbers/{number_id}/release`](/docs/api/reference/release-workspace-number) melepas nomor segera, termasuk nomor yang sudah dijadwalkan untuk dibatalkan. Sisa periode saat ini tidak dikembalikan. [Membeli dan melepas nomor](/docs/guides/numbers/buying-numbers#release-a-number) menunjukkan panggilan tersebut di setiap SDK.

Selama pembayaran perpanjangan untuk nomor tersebut tertunggak, kedua permintaan menjawab `409` hingga dibayar.

Opsi pelepasan mana pun yang Anda pilih, kirim permintaan dengan `Idempotency-Key` agar percobaan ulang aman: kunci yang sama memutar ulang respons pertama dengan header `Idempotency-Replay: true`, sedangkan permintaan baru untuk nomor yang sudah dilepas menjawab `404` dengan [`E01008`](/docs/api/errors/E01008). [Idempotency](/docs/guides/idempotency) menjelaskan berapa lama kunci disimpan.

Selama pembatalan terjadwal belum berlaku, nomor tetap terbaca seperti biasa dan membawa `releases_at`. Setelah pelepasan:

- Nomor berhenti berfungsi untuk Anda, dan langganannya tidak diperpanjang.
- `GET /v1/numbers/{number_id}` dan voice record nomor tersebut menjawab `404`, dan nomor tersebut keluar dari `GET /v1/numbers`.
- Pesanan nomor tetap ada di [`GET /v1/numbers/orders`](/docs/api/reference/list-numbers-orders), dan `number_id`-nya sekarang menjawab `404`.
- Nomor masuk ke masa tunggu 30 hari sebelum dapat kembali dijual, sehingga Anda tidak bisa langsung membeli kembali nomor yang sama.

## Langkah selanjutnya

- [Menerima panggilan](/docs/guides/voice/receiving-calls) merutekan nomor ke trunk SIP, penerusan, atau urutan.
- [Membeli dan melepas nomor](/docs/guides/numbers/buying-numbers) memandu proses pembelian melalui API.
- [Referensi API Numbers](/docs/api/reference/list-workspace-numbers) mendokumentasikan setiap operasi dan field.

## Related resources

- [What is a virtual phone number (VMN)?](/explained/numbers/what-is-a-virtual-phone-number) (answer)
- [SMS numbers](/sms-api/features/numbers) (product)
- [Number types](/docs/guides/numbers/number-types) (docs)

[Get an implementation brief](/learn/workspace?topic=phone-numbers)