Ajukan dokumen kepemilikan nomor

Beberapa negara menanyakan siapa pemegang nomor sebelum nomor tersebut dapat membawa lalu lintas. Selama dokumen itu belum diterima dan registrasi nomor belum selesai, nomor dialokasikan kepada Anda dan ditagih, tetapi status-nya bernilai pending_ownership_registration: nomor tidak membawa panggilan suara masuk maupun keluar dan tidak mengirim SMS. Nomor membawa lalu lintas setelah status-nya bernilai active dan ownership.blocked_at-nya bernilai null. Anda mengajukan dokumen dari dasbor atau dengan API, dan kedua cara memakai persyaratan, aturan peninjauan, dan proses registrasi yang sama. ownership.next nomor menyebutkan setiap langkah, termasuk kapan Anda perlu mengajukan pengajuan baru.

Jawaban yang Anda ajukan merupakan pernyataan hukum atas nama bisnis Anda. Setelah diterima, jawaban tersebut diteruskan ke operator atau regulator negara itu atas nama bisnis yang dijelaskan. Karena itu, konfirmasikan jawaban dengan pihak yang bertanggung jawab atasnya sebelum Anda mengajukannya, dan jangan biarkan tugas otomatis mengajukan jawaban yang belum diperiksa siapa pun.

Sebelum memulai

• Untuk mengajukan dari dasbor, peran workspace Anda harus mengizinkan pengeditan detail kepatuhan. Tanpa izin itu, nomor menampilkan status kepemilikannya tetapi tidak menampilkan tombol untuk mengajukan.
• Untuk mengajukan melalui endpoint kepatuhan mandiri, Anda memerlukan kunci API dengan cakupan compliance pada tingkat tulis. Kunci dengan tingkat baca dapat memeriksa persyaratan dan progres peninjauan, tetapi tidak dapat mengajukan. Membaca nomor juga memerlukan cakupan numbers pada tingkat baca. Di pemilih kunci dasbor, compliance ada di bawah Compliance.
• Pengenal nda_ nomor, dari GET /v1/numbers. Temukan nomor dalam daftar Anda menjelaskan cara mencarinya.

Contoh API membaca kunci Anda dari BIRD_API_KEY, host regional-nya dari BIRD_API_URL, dan pengenal nomor dari NUMBER_ID. Setiap langkah berikutnya menyebutkan variabel yang ditetapkannya. Perintah jq mengambil satu field dari respons; baca field tersebut secara manual jika Anda tidak menggunakan jq.

Periksa apakah nomor memerlukan dokumen

Baca nomor dengan GET /v1/numbers/{number_id}:

curl "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Simpan country_code nomor tersebut sebagai COUNTRY_CODE; pembacaan persyaratan dan pengajuan sama-sama memerlukannya:

COUNTRY_CODE=$(curl -s "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
  --header "Authorization: Bearer $BIRD_API_KEY" | jq -r .country_code)

ownership bernilai null jika negara nomor tersebut tidak meminta dokumen apa pun. Nilainya juga null jika kami tidak dapat membaca progres dokumen dan tidak ada blokir yang tercatat pada nomor tersebut; dalam hal ini, baca nomor itu lagi. Jika tidak, isinya:

• status: needs_input berarti ada jawaban yang belum diisi atau perlu diperbaiki, under_review berarti jawaban Anda sedang ditinjau, approval_pending berarti dokumen telah diterima dan pendaftaran masih tertunda; panggilan dan SMS keluar tetap diblokir selama blocked_at terisi. approved berarti pendaftaran telah disetujui, tetapi panggilan dan SMS keluar tetap diblokir selama blocked_at terisi. not_required berarti tidak ada lagi yang diminta. rejected berarti pengajuan telah ditutup atau batas waktu perbaikan telah lewat, sehingga pengajuan tidak lagi menerima perbaikan. Hubungi dukungan agar pengajuan dibuka kembali. unknown berarti status tidak dapat dibaca; baca nomor itu lagi.
• next: langkah-langkah untuk melanjutkan proses dokumen, secara berurutan. Langkah wait berarti saat ini tidak ada yang diminta dari Anda. Baca lagi setelah setiap perubahan.
• submission_id: pengajuan terbaru untuk nomor tersebut, setelah ada pengajuan.
• blocked_at: waktu dimulainya blokir kepemilikan, atau null setelah blokir dicabut. Blokir ini menghentikan panggilan suara masuk dan keluar serta SMS keluar.

Status nomor yang dialokasikan menjelaskan hubungan ownership dengan status milik nomor itu sendiri.

Mengajukan dari dasbor

1. Buka nomor dari halaman Numbers. Baris Ownership menampilkan status dokumen dan langkah berikutnya.
2. Jika statusnya Details needed, pilih Update ownership details. Formulir Prove ownership of this number akan terbuka.
3. Pilih bisnis pemegang nomor, atau isi data bisnis baru, lalu jawab setiap item dan unggah dokumen yang diminta. Untuk item yang menyediakan formulir kosong, unduh formulir tersebut melalui tautannya, lengkapi, lalu unggah kembali.
4. Pilih Submit answers.

Baris Ownership berubah menjadi Under review. Jika peninjau menolak suatu jawaban, baris tersebut kembali ke Details needed: pilih Update ownership details lagi, perbaiki jawaban yang ditampilkan formulir, lalu pilih Update ownership details di akhir formulir untuk mengirimkannya.

Jika negara nomor tersebut belum memiliki formulir, halaman formulir menampilkan Ownership form unavailable. Hubungi dukungan untuk meminta formulir negara tersebut.

Mengajukan melalui API

Untuk mengajukan melalui API, baca apa yang diminta negara tersebut, unggah setiap dokumen, kirim semua jawaban sekaligus, lalu baca nomor tersebut untuk memantau peninjauannya.

Membaca apa yang diminta negara tersebut

Baca persyaratan untuk nomor tersebut dengan GET /v1/compliance/requirements. Atur subject_kind ke number, subject_id ke pengenal nda_ nomor tersebut, dan country_code ke COUNTRY_CODE milik nomor itu sendiri:

curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=number&subject_id=$NUMBER_ID&country_code=$COUNTRY_CODE" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Respons menyebutkan program tempat nomor tersebut didaftarkan, yang mengikuti jenis nomornya; simpan sebagai PROGRAM. Respons juga mencantumkan setiap item yang harus dijawab di fields, sesuai urutan penyajiannya. Untuk setiap kolom:

• key adalah nama yang Anda gunakan untuk mengirim jawabannya.
• data_type menunjukkan cara menjawabnya. Kolom document menerima file yang diunggah; semua jenis lainnya menerima string, sehingga angka dikirim sebagai "1500" dan jawaban ya-atau-tidak sebagai "true". Kolom enum menerima salah satu nilai options miliknya.
• required menunjukkan apakah persetujuan bergantung pada kolom tersebut, dan help_text menjelaskan seperti apa jawaban yang baik.
• max_items ditetapkan pada kolom yang menerima lebih dari satu jawaban.
• template_url menautkan formulir kosong untuk diunduh, diisi, dan diunggah kembali, jika kolom tersebut memilikinya.
• state menunjukkan posisi item: not_supplied sebelum Anda menjawab, lalu supplied, in_review, approved, atau rejected, dengan reason dari peninjau pada item yang ditolak. Jawaban yang sudah diterima nantinya dapat bernilai expired dan perlu diberikan lagi, sedangkan not_applicable menandai item yang tidak berlaku bagi Anda.

submission_id bernilai null sampai Anda mengajukan berkas. needs_input bernilai true selama masih ada item yang menunggu tindakan Anda.

422 dengan E19001 berarti kami belum memiliki formulir kepemilikan untuk negara tersebut. Hubungi dukungan untuk memintanya.

Unggah setiap dokumen

Unggah setiap file yang diminta field document dengan POST /v1/compliance/attachments, sebagai body multipart/form-data dengan byte file di bagian file. Simpan id dari respons, yaitu identifier tca_ lampiran, sebagai ATTACHMENT_ID:

curl --request POST "$BIRD_API_URL/v1/compliance/attachments" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --form "file=@registration-certificate.pdf"

File PNG, JPEG, dan PDF hingga 10 MB diterima, dan jenisnya dibaca dari isi file. Respons 201 mengembalikan lampiran baru. Jika Anda mengunggah file yang sama lagi, respons mengembalikan lampiran pertama dengan 200, sehingga mencoba lagi unggahan tidak membuat duplikat. Lampiran yang tidak dirujuk oleh pengajuan mana pun kedaluwarsa setelah tujuh hari.

download_url lampiran adalah tautan bertanda tangan yang berlaku selama 24 jam sejak Anda mengambil lampiran tersebut. Untuk mendapatkan tautan baru, tampilkan daftar lampiran Anda dengan GET /v1/compliance/attachments, atau unduh byte file langsung dengan GET /v1/compliance/attachments/{attachment_id}.

Kirim semua jawaban

Ajukan jawaban dengan POST /v1/compliance/submissions. Kirim subject_kind dan subject_id, program yang dilaporkan saat membaca persyaratan, serta country_code nomor. Di answers, kirim satu entri untuk setiap field yang required-nya true, dan satu entri untuk setiap field opsional yang jawaban sebenarnya Anda miliki. Jangan sertakan field opsional daripada mengarang nilainya. Field bertipe menerima value, field dokumen menerima attachment_id, dan field dengan max_items menerima values atau attachment_ids. Simpan body sebagai submission.json, dengan nilai Anda menggantikan <NUMBER_ID>, <PROGRAM>, <COUNTRY_CODE>, dan <ATTACHMENT_ID>. Contoh ini menunjukkan tiga jawaban yang diminta formulir:

{
  "subject_kind": "number",
  "subject_id": "<NUMBER_ID>",
  "program": "<PROGRAM>",
  "country_code": "<COUNTRY_CODE>",
  "answers": [
    { "key": "legal_entity_name", "value": "Goldcrest Communications Inc" },
    { "key": "business_registration_number", "value": "90012768" },
    { "key": "business_registration_certificate", "attachment_id": "<ATTACHMENT_ID>" }
  ]
}

Kirim dengan Idempotency-Key. Gunakan ulang kunci tersebut hanya untuk mencoba lagi body yang sama: penolakan dapat disimpan dan diputar ulang, jadi setelah 422, perbaiki body lalu kirim dengan kunci baru. Idempotensi menjelaskan apa yang disimpan.

curl --request POST "$BIRD_API_URL/v1/compliance/submissions" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ownership-$NUMBER_ID" \
  --data-binary @submission.json

Tidak ada draf: permintaan ini langsung mengajukan jawaban untuk ditinjau, jadi permintaan harus memuat setiap jawaban wajib. Jika Anda tidak menyertakan field wajib atau formulir menolak suatu jawaban, Anda menerima 422 dengan E01001 dan satu entri di details per field, yang namanya ada di param, dan tidak ada yang diajukan. Respons 201 mengembalikan pengajuan beserta setiap jawabannya. Simpan id-nya, yaitu identifier csb_ pengajuan, sebagai SUBMISSION_ID.

Bisnis yang dideskripsikan workspace Anda adalah sebuah identitas. Buat identitas di Identity Center pada dasbor atau dengan POST /v1/compliance/identities, dengan mengirim name tampilannya. Pengajuan nomor juga dapat memuat identity inline sebagai pengganti identity_id. identity_id pada respons pengajuan menyebutkan identitas baru, yang dikembalikan POST /v1/compliance/identities sebagai id. Gunakan ulang identitas itu untuk nomor berikutnya daripada membuat identitas lain. Untuk mengajukan atas nama suatu identitas, tambahkan identity_id-nya, dan jawaban yang tersimpan pada identitas itu mengisi jawaban yang tidak Anda sertakan. GET /v1/compliance/identities menampilkan daftar identitas bisnis. Jawaban bernilai tunggal yang Anda ajukan ditulis kembali ke identitas apa pun hasil peninjauannya, sehingga pengajuan berikutnya yang menyebut identitas itu dimulai dari jawaban tersebut. Dokumen dan jawaban bernilai ganda diminta lagi setiap kali. Gunakan satu identitas per bisnis: jika Anda mengajukan untuk beberapa pelanggan akhir, beri setiap pelanggan identitasnya sendiri. Jika tidak, jawaban yang disetujui untuk satu pelanggan akan mengisi jawaban pelanggan lain.

Pantau ownership.next alih-alih mengajukan ulang. Satu nomor memiliki satu pengajuan per versi formulir negaranya, sehingga pengajuan ulang selama pengajuan tersebut masih terbuka dijawab dengan 409 dan E19009: perbaiki pengajuan tersebut, seperti yang dijelaskan di Perbaiki jawaban yang ditolak. Saat kami membuka kembali pengajuan yang sudah ditutup setelah formulir berubah, next meminta pengajuan baru ke POST /v1/compliance/submissions.

Pantau peninjauan

Setiap jawaban ditinjau secara terpisah. Baca nomor tersebut lagi dan periksa ownership.status serta ownership.next, seperti di Periksa apakah nomor memerlukan dokumen. Untuk melihat penilaian setiap jawaban, baca pengajuan dengan GET /v1/compliance/submissions/{submission_id}, atau baca persyaratannya lagi: setiap kolom memuat state dan, jika ditolak, reason.

Saat peninjauan selesai, kami mengirim hasilnya melalui email kepada pemilik organisasi Anda dan orang terakhir yang tercatat mengajukan atau memperbaiki pengajuan, jika ada. Pengajuan pertama dengan kunci API dikirim ke pemilik. Perbaikan berikutnya dengan kunci API tetap menjadikan orang yang tercatat sebelumnya sebagai penerima. Integrasi Anda mengetahui hasilnya dengan membaca ownership.status.

Perbaiki jawaban yang ditolak

Kirim jawaban pengganti ke POST /v1/compliance/submissions/{submission_id}/resupply. Sertakan hanya jawaban yang Anda ganti; jawaban lainnya tetap seperti semula. Ambil submission_id dari ownership nomor tersebut atau dari hasil pembacaan persyaratan:

curl --request POST "$BIRD_API_URL/v1/compliance/submissions/$SUBMISSION_ID/resupply" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ownership-fix-1-$NUMBER_ID" \
  --data '{"answers": [{"key": "business_registration_number", "value": "90012769"}]}'

Respons 200 mengembalikan pengajuan beserta jawaban pengganti Anda, yang kembali ditinjau. Setelah tidak ada lagi jawaban wajib yang ditolak, kedaluwarsa, atau belum diisi, ownership.status nomor tersebut kembali ke under_review. Ganti jawaban yang state-nya rejected, expired, atau not_supplied. Jika kami meminta perbaikan setelah menerima jawaban Anda, jawaban yang editable_for_verifier_repair-nya true juga dapat diganti hingga perbaikan tersebut ditutup. Jawaban dalam status lain, misalnya yang masih ditinjau atau yang diterima di luar perbaikan yang kami minta, dijawab dengan 422 dan E19003. Dokumen pengganti adalah unggahan baru: unggah dokumen tersebut terlebih dahulu, lalu kirim attachment_id-nya.

Ajukan dokumen bersama pesanan

Jika Anda sudah mengetahui jawabannya saat membeli nomor, kirim jawaban tersebut dalam blok compliance pada pesanan di POST /v1/numbers/orders, dengan bentuk answers yang sama seperti pada pengajuan. Untuk membaca persyaratan negara sebelum Anda memiliki nomor, panggil pembacaan persyaratan tanpa subject_id, dengan COUNTRY_CODE dan NUMBER_TYPE diisi dengan country_code dan number_type nomor di GET /v1/numbers/available:

curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=number&country_code=$COUNTRY_CODE&program=$NUMBER_TYPE" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Pesanan dengan blok compliance menggunakan cakupan numbers yang sudah dimiliki pesanan, pada tingkat tulis.

Setelah diterima, pesanan tetap selesai dalam kondisi apa pun: jika pengajuan dalam blok compliance ditolak, nomor tersebut tetap milik Anda, dan Anda mengajukan dengan POST /v1/compliance/submissions seperti di Kirim semua jawaban. Setelah jawaban diajukan, nomor baru menampilkan under_review beserta submission_id-nya. Beli dan lepaskan nomor membahas pesanan itu sendiri.

Gunakan kembali identitas bisnis

Gunakan GET /v1/compliance/identities/{identity_id} untuk membaca bisnis beserta jawaban yang tersimpan. Jawaban tersimpan dapat mencakup state peninjauan, reason, dan decided_at; nilai yang belum memiliki keputusan peninjauan dapat tidak menyertakan statusnya. Ganti nama bisnis dengan PATCH /v1/compliance/identities/{identity_id}, atau hapus dengan DELETE /v1/compliance/identities/{identity_id}. Operasi baca memerlukan compliance:read; pembuatan, penggantian nama, dan penghapusan memerlukan compliance:write.

Untuk memverifikasi bisnis itu sendiri, buat identitasnya terlebih dahulu. Baca persyaratan dengan subject_kind=identity, pengenal cid_ identitas tersebut sebagai subject_id, program=business, dan country_code=ZZ. Ajukan dokumen untuk identitas yang sama. Identitas inline pada pengajuan nomor tidak menggantikan alur verifikasi identitas ini.

Peninjauan menggunakan detail bisnis, kontak yang dinyatakan, dan bukti verifikasi yang Anda ajukan. Mengajukan melalui kunci API atau dashboard tidak membentuk hubungan bisnis yang berbeda. Pastikan detail kontak akurat dan berikan bukti yang diminta formulir.

Ajukan untuk pengirim SMS sebagai gantinya

Dokumen pengirim SMS menggunakan permintaan persyaratan, lampiran, pengajuan, dan koreksi yang sama, dengan registrasi pengirim sebagai subjeknya. Mendaftarkan pengirim SMS melalui API menjelaskan cara memperoleh registrasi tersebut dan memeriksa harganya terlebih dahulu.

Jika permintaan ditolak

Kesalahan menjelaskan isi respons kesalahan beserta remediation-nya.

Langkah berikutnya

• Ikhtisar nomor
• Membeli dan melepaskan nomor
• Mengelola nomor telepon Anda
• Migrasi dari Telserv ke Bird