Referensi

NumDetect Referensi API

Setiap endpoint berbagi satu kunci API dan satu saldo.

Item	Nilai
URL dasar	https://numdetect.com
Header autentikasi	X-API-Key: sk_your_api_key
Amplop respons	{ code, msg, data }

Harga tidak dicantumkan di sini; setiap produk ditagihkan per pemeriksaan yang berhasil. Lihat harga

Autentikasi

Gunakan kunci API yang dibuat di Pengaturan dan kirimkan bersama setiap permintaan.

Header autentikasi

X-API-Key: sk_your_api_key

Jaga kerahasiaan kunci API AndaSelalu panggil endpoint ini dari server Anda. Siapa pun yang memegang kunci dapat menghabiskan saldo Anda.

Pemeriksaan asinkron

POST/api/v1/bulk-tasksGET/api/v1/bulk-tasks/{id}

Unggah file dan langsung dapatkan ID tugas, lalu periksa ID tersebut sampai berhasil. Respons yang berhasil membawa result_url, tautan unduhan hasil. Hanya ada dua tindakan: kirim dan periksa. Lakukan polling tidak lebih sering dari sekali setiap 30 detik.

Parameter

Kolom	Tipe	Deskripsi
`service_type`	string	Kode produk massal, salah satu produk yang tercantum di bawah.
`country`	string	Kode ISO 3166-1 seperti `US`. Wajib untuk tugas nomor: setiap nomor harus menyertakan kode negaranya dan berasal dari negara ini (nomor yang tidak memenuhi akan dikecualikan dan tidak ditagihkan); juga menentukan perutean. Dalam multipart, field ini harus berada sebelum `file`.
`file`	file	File `.txt` atau `.csv` dengan satu pengenal per baris, hingga `max_file_bytes` (default 20MB).
`Idempotency-Key`	header	Opsional, hingga 128 karakter. Mengirim ulang kunci yang sama mengembalikan tugas asli alih-alih membuat tugas kedua.

Produk dalam grup ini

Validasi Nomor Teleponnumber_validation_batchDaftar yang bersih adalah awal dari kampanye berikutnya. Periksa sinyal validitas dan aktivasi untuk menemukan data yang layak ditinjau, lalu masukkan hasil terstruktur ke dalam pembersihan daftar, pembaruan CRM, dan pemeriksaan sebelum menjangkau pelanggan, sehingga setiap tindakan dimulai dengan data yang lebih jelas.Halaman produk
Aktivitas Nomornumber_activity_batchAwali tindak lanjut berikutnya dengan sinyal aktivitas. Temukan aktivitas terbaru di seluruh daftar nomor, pisahkan data yang tidak aktif dari nomor yang layak ditinjau, dan gunakan hasilnya untuk merencanakan reaktivasi, segmentasi, dan prioritas penjangkauan.Halaman produk
Pengguna Bernilai Tingginumber_high_value_batchTemukan data yang paling layak ditinjau terlebih dahulu. Gabungkan karakteristik perangkat kelas atas dengan aktivitas jaringan terbaru untuk mengembalikan sinyal calon pengguna bernilai tinggi true/false guna memprioritaskan layanan, keanggotaan, dan kampanye; ini adalah sinyal deteksi, bukan bukti pendapatan atau pembelian.Halaman produk
Aktif E-commercenumber_ecommerce_batchMulai kampanye perdagangan berikutnya dengan audiens yang lebih terfokus. Temukan sinyal aktivitas e-commerce yang tersedia, bentuk segmen audiens dan remarketing di sekitar data yang layak ditinjau, dan jaga batasannya tetap jelas: hasil ini bukan catatan pesanan, niat beli, atau aktivitas platform.Halaman produk
Pencarian operator globalcarrier_batchUbah daftar nomor telepon menjadi konteks yang siap untuk routing. Tambahkan operator, operator dasar, jenis saluran, negara, wilayah, dan kota ke data internasional, lalu gunakan hasil yang diperkaya untuk routing, analisis regional, segmentasi, dan pembaruan CRM.Halaman produk

Validasi Nomor Telepon

number_validation_batchtelepon500–500.000 per tugas

Daftar yang bersih adalah awal dari kampanye berikutnya. Periksa sinyal validitas dan aktivasi untuk menemukan data yang layak ditinjau, lalu masukkan hasil terstruktur ke dalam pembersihan daftar, pembaruan CRM, dan pemeriksaan sebelum menjangkau pelanggan, sehingga setiap tindakan dimulai dengan data yang lebih jelas.

Kirim tugas

POST/api/v1/bulk-tasks

Permintaan

curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=number_validation_batch \
  -F country=US \
  -F file=@numbers.txt

Respons

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_validation_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Periksa tugas

GET/api/v1/bulk-tasks/{id}

Permintaan

curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respons

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_validation_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Kolom hasil

Kolom	contoh:	Deskripsi
`identifier`	17253100591	Nomor yang dikirim dalam bentuk angka polos dengan kode negara, tanpa tanda plus atau spasi (mis. 17253100591), sekaligus kunci stabil untuk mencocokkan hasil dengan data pelanggan, prospek, atau CRM. Simpan untuk menelusuri daftar sumber dan menuliskan hasil kembali secara massal; kolom ini saja tidak membuktikan bahwa nomor dapat dihubungi.
`activated`	true	Sinyal aktivasi yang dikembalikan oleh pemeriksaan ini. Gunakan untuk menemukan data yang layak ditinjau sebelum menjangkau pelanggan, mengatur antrean pembersihan, dan mendukung segmentasi CRM; kombinasikan dengan data persetujuan, sumber, dan interaksi alih-alih menganggapnya sebagai jaminan tersambung atau terkirim. Nilainya true atau false.

Aktivitas Nomor

number_activity_batchtelepon500–500.000 per tugas

Awali tindak lanjut berikutnya dengan sinyal aktivitas. Temukan aktivitas terbaru di seluruh daftar nomor, pisahkan data yang tidak aktif dari nomor yang layak ditinjau, dan gunakan hasilnya untuk merencanakan reaktivasi, segmentasi, dan prioritas penjangkauan.

Kirim tugas

POST/api/v1/bulk-tasks

Permintaan

curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=number_activity_batch \
  -F country=US \
  -F file=@numbers.txt

Respons

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_activity_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Periksa tugas

GET/api/v1/bulk-tasks/{id}

Permintaan

curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respons

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_activity_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Kolom hasil

Kolom	contoh:	Deskripsi
`identifier`	17253100591	Nomor yang dikirim dalam bentuk angka polos dengan kode negara, tanpa tanda plus atau spasi (mis. 17253100591), digunakan untuk menuliskan hasil aktivitas kembali ke daftar, data pelanggan, atau prospek. Kolom ini hanya untuk pencocokan dan penelusuran; tidak mencakup waktu aktivitas, frekuensi, atau detail interaksi.
`activated`	true	Sinyal aktivitas yang tersedia yang dapat membantu tim memprioritaskan peninjauan, membuat label audiens, dan merencanakan ritme reaktivasi. Ini bukan jumlah hari aktif, frekuensi, atau waktu pengamatan tertentu; sinyal yang hilang tidak berarti seseorang tidak akan pernah merespons. Nilainya true atau false.

Pengguna Bernilai Tinggi

number_high_value_batchtelepon500–500.000 per tugas

Temukan data yang paling layak ditinjau terlebih dahulu. Gabungkan karakteristik perangkat kelas atas dengan aktivitas jaringan terbaru untuk mengembalikan sinyal calon pengguna bernilai tinggi true/false guna memprioritaskan layanan, keanggotaan, dan kampanye; ini adalah sinyal deteksi, bukan bukti pendapatan atau pembelian.

Kirim tugas

POST/api/v1/bulk-tasks

Permintaan

curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=number_high_value_batch \
  -F country=US \
  -F file=@numbers.txt

Respons

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_high_value_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Periksa tugas

GET/api/v1/bulk-tasks/{id}

Permintaan

curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respons

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_high_value_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Kolom hasil

Kolom	contoh:	Deskripsi
`identifier`	17253100591	Nomor yang dikirim dalam bentuk angka polos dengan kode negara (mis. 12017200001), digunakan untuk mencocokkan sinyal bernilai tinggi kembali ke data yang diunggah dan menelusurinya melalui CRM atau antrean peninjauan. Kolom ini tidak memberikan identitas, model perangkat, atau data profil pribadi lainnya.
`activated`	true	Sinyal pendukung true/false yang diturunkan dari karakteristik perangkat kelas atas dan aktivitas jaringan terbaru. Sinyal ini dapat membantu tim keanggotaan, layanan, dan pemasaran menetapkan prioritas peninjauan, tetapi tidak mengonfirmasi pendapatan, aset, kemampuan membeli, atau pengeluaran yang sebenarnya.

Aktif E-commerce

number_ecommerce_batchtelepon500–500.000 per tugas

Mulai kampanye perdagangan berikutnya dengan audiens yang lebih terfokus. Temukan sinyal aktivitas e-commerce yang tersedia, bentuk segmen audiens dan remarketing di sekitar data yang layak ditinjau, dan jaga batasannya tetap jelas: hasil ini bukan catatan pesanan, niat beli, atau aktivitas platform.

Kirim tugas

POST/api/v1/bulk-tasks

Permintaan

curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=number_ecommerce_batch \
  -F country=US \
  -F file=@numbers.txt

Respons

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_ecommerce_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Periksa tugas

GET/api/v1/bulk-tasks/{id}

Permintaan

curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respons

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_ecommerce_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Kolom hasil

Kolom	contoh:	Deskripsi
`identifier`	17253100591	Nomor yang dikirim dalam bentuk angka polos dengan kode negara, tanpa tanda plus atau spasi (mis. 17253100591), digunakan untuk menghubungkan sinyal aktivitas perdagangan dengan data pelanggan, prospek, atau audiens. Kolom ini memungkinkan tim pemasaran menggabungkan hasil dengan data persetujuan, penjelajahan, pesanan, dan keanggotaan mereka sendiri; kolom ini tidak berisi informasi pesanan atau produk.
`activated`	true	Sinyal aktivitas perdagangan yang tersedia yang dapat memfokuskan peninjauan audiens, persiapan daftar remarketing, dan perencanaan uji konten. Sinyal ini tidak mewakili pesanan, nilai transaksi, niat beli, atau aktivitas platform tertentu. Nilainya true atau false.

Pencarian operator global

carrier_batchtelepon500–500.000 per tugas

Ubah daftar nomor telepon menjadi konteks yang siap untuk routing. Tambahkan operator, operator dasar, jenis saluran, negara, wilayah, dan kota ke data internasional, lalu gunakan hasil yang diperkaya untuk routing, analisis regional, segmentasi, dan pembaruan CRM.

Kirim tugas

POST/api/v1/bulk-tasks

Permintaan

curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=carrier_batch \
  -F country=US \
  -F file=@numbers.txt

Respons

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "carrier_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Periksa tugas

GET/api/v1/bulk-tasks/{id}

Permintaan

curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respons

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "carrier_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Kolom hasil

Kolom	contoh:	Deskripsi
`identifier`	17253100591	Nomor yang dikirim dalam bentuk angka polos dengan kode negara, tanpa tanda plus atau spasi (mis. 17253100591), sekaligus kunci pencocokan untuk menuliskan konteks operator, saluran, dan geografis kembali ke daftar sumber. Simpan kolom sumber Anda sendiri di sampingnya agar tim routing, layanan, dan CRM dapat menelusuri pemeriksaan, menangani duplikat, dan memperbarui data pelanggan atau prospek yang benar. Kolom ini mengidentifikasi data; tidak membuktikan bahwa nomor dapat dijangkau.
`carrier`	T-Mobile	Nama operator yang dikenal pelanggan jika dapat diidentifikasi. Kolom ini dapat memperkaya data CRM, mendukung routing layanan, membantu meninjau komposisi nomor, dan menunjukkan sebaran daftar di antara operator. Gunakan sebagai konteks operasional, bukan bukti keterjangkauan atau penggunaan saat ini. Nilai kosong berarti tidak ada nama yang dapat digunakan yang dikembalikan untuk pemeriksaan ini; itu tidak membuktikan bahwa operator tidak ada.
`underlying_carrier`		Operator jaringan dasar jika dapat diidentifikasi, berguna untuk memahami konteks reseller, operator virtual, dan nomor yang telah dipindahkan (porting). Nilainya bisa berbeda dari operator yang dikenal pelanggan, dan perbedaan itu dapat membantu tim menyelidiki pertanyaan tentang routing atau kepemilikan. Ini bukan status jaringan seluler langsung atau sinyal sambungan real-time.
`number_type`	Fixed Line or Mobile	Jenis saluran yang dikembalikan, seperti mobile, fixed line, atau kategori lain yang dapat diidentifikasi. Gunakan untuk memisahkan data seluler dan telepon tetap, merencanakan routing layanan, memeriksa kesesuaian kanal, dan menambahkan segmen CRM yang berguna. Ini bukan hasil sambungan; simpan nilai kosong atau tidak diketahui untuk ditinjau alih-alih menganggapnya sebagai kegagalan.
`country_code`	US	Kode negara atau wilayah yang dikembalikan untuk mengelompokkan daftar internasional, menerapkan routing dan aturan bisnis tingkat negara, serta menyusun laporan regional. Kode ini menggambarkan konteks penomoran, bukan negara tempat seseorang berada saat ini, lokasi fisik, atau kewarganegaraan. Kasus penggunaan lintas negara dan nomor virtual perlu dicek dengan data pelanggan Anda sendiri.
`region`	CA	Konteks wilayah, negara bagian, atau provinsi jika tersedia. Kolom ini dapat mendukung analisis cakupan pasar, pengelompokan daftar per wilayah, penugasan layanan, dan pelaporan operasional. Nilainya berasal dari konteks nomor dan jaringan, bukan lokasi langsung, sehingga tidak boleh dibaca sebagai area pengguna saat ini; nilai yang hilang atau lintas wilayah memerlukan peninjauan bisnis seperti biasa.
`city`	LOS ANGELES	Konteks tingkat kota jika tersedia. Kolom ini dapat meningkatkan pelaporan regional, mengungkap komposisi daftar, mendukung operasional lokal, dan mengisi kolom CRM yang kosong. Alokasi nomor, portabilitas, nomor virtual, dan perbedaan sumber dapat memengaruhi ketepatan tingkat kota, sehingga keputusan penting perlu dicek dengan data yang diberikan pengguna atau catatan bisnis yang sudah ada.

Saldo

GET/api/v1/balance

Baca saldo akun saat ini dalam mikro USD. Hanya-baca: tidak membuat catatan pemeriksaan dan tidak menagih apa pun.

Saldo

GET/api/v1/balance

Permintaan

curl "https://numdetect.com/api/v1/balance" \
  -H "X-API-Key: sk_your_api_key"

Respons

{
  "code": 0,
  "msg": "ok",
  "data": {
    "balance_micros": 12500000
  }
}

Konkurensi, batas waktu, dan perilaku percobaan ulang

Pengiriman tugas massal diterima sebelum pekerjaan dimulai. Gunakan status tugas yang dikembalikan untuk memutuskan apakah akan terus melakukan polling atau menangani kegagalan.

Kolom	Deskripsi
`5 permintaan berjalan per pengguna`	Pengiriman tugas menggunakan satu slot permintaan. Jika akun tidak memiliki slot yang tersedia, API mengembalikan 42901 dengan Retry-After; tunggu lalu kirim ulang file tersebut.
`Lakukan polling alih-alih menunggu`	Pengiriman tugas langsung memberikan respons. Lakukan polling status tidak lebih dari sekali setiap 30 detik selama tugas diproses.
`Ukuran tugas mengikuti produk`	Setiap produk memiliki ukuran file minimum dan maksimum sendiri, yang ditampilkan di bagian tugas.

Kode error

Kode	Deskripsi
`40000`	Tipe layanan tidak didukung atau field permintaan saling bertentangan
`40001`	Body JSON tidak valid
`40002`	Nomor tidak valid
`40100`	Kunci API tidak ada atau tidak valid
`40200`	Saldo tidak mencukupi
`42200`	Tugas yang dikirim tidak dapat diterima dalam bentuknya saat ini
`42900`	Kuota penggunaan habis, atau terlalu banyak pesanan yang belum selesai
`42901`	Semua slot permintaan sedang terisi; kirim setelah permintaan yang sedang berjalan selesai. Permintaan yang ditolak tidak dikenai biaya dan menyertakan header Retry-After
`50303`	Layanan sedang mencapai kapasitas penuh; tidak dikenai biaya. Tunggu selama detik Retry-After lalu kirim ulang permintaan yang sama
`50400`	Permintaan tidak selesai dalam batas waktunya dan tidak dikenai biaya; coba lagi
`50300`	Pemeliharaan layanan validasi