Dokumentasi API API v1

Autentikasi

Buat kunci di halaman API keys, lalu ganti placeholder di bawah di terminal Anda sendiri. Contoh-contoh ini hanya teks; menyalinnya tidak mengirim apa pun.

# API origin: https://api.numdetect.com
export NUMDETECT_API_KEY='YOUR_API_KEY'

• Kirim Authorization: Bearer <key> pada setiap permintaan. Permintaan JSON juga memerlukan Content-Type: application/json. Tidak perlu cookie, header CSRF, atau header Origin.
• Sebuah kunci dapat membaca produk, menjalankan cek satuan dan massal, membaca hasilnya, dan membaca riwayat saldo Anda. Pengaturan akun, kunci, dan isi saldo hanya dikelola di dasbor setelah masuk.
• Anda dapat membuat hingga 10 kunci, misalnya satu per sistem, dan menghapus yang mana pun seketika.

Simpan kunci di lingkungan server Anda. Jangan menaruh kunci di URL, tangkapan layar, log bersama, atau file sumber yang di-commit.

Produk

Baca katalog terkini sebelum memilih ID produk. Responsnya mencantumkan setiap produk yang dijual beserta jenis input, harga, minimum massal, dan negara yang didukung.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/products" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

single dan bulk menunjukkan apakah produk tersedia saat ini untuk jenis cek tersebut. countries berisi ["*"] untuk semua negara, daftar kode negara, atau kosong untuk produk e-mail. Harga dalam USD micros per cek.

Cek satuan

POST /api/v1/checks menerima satu nomor telepon atau satu alamat e-mail dan daftar ID produk. Permintaan menunggu hingga setiap produk menjawab (sekitar 45 detik) dan mengembalikan cek yang telah selesai.

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/checks" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"phone":"+12025550147","products":["whatsapp","telegram"]}'

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/checks" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","products":["apple_email","spotify_email"]}'

Tulis nomor telepon dengan kode negara +. Untuk nomor tanpa kode negara, tambahkan "country": "GB" (kode negara ISO) ke permintaan.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/checks/$CHECK_ID" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/checks?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

Cek massal

POST /api/v1/bulk-jobs mengunggah file sebagai multipart form data. File dibagi menjadi satu daftar per negara, dan setiap negara diperiksa oleh setiap produk yang Anda pilih.

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/bulk-jobs" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "[email protected]" \
  -F "products=whatsapp,telegram" \
  -F "input_kind=phone" \
  -F "max_cost=50000000" \
  -F "column=0" \
  -F "header=true"

• file: CSV UTF-8 atau teks biasa, hingga 100 MB dan 1.000.000 baris. Kolom lain dipertahankan dan dikembalikan dalam file hasil.
• input_kind adalah phone atau email. column adalah kolom berindeks-0 yang berisi nomor (default 0); header=true melewati baris pertama.
• country (opsional) dipakai untuk nomor telepon yang ditulis tanpa kode negara. Nomor yang diawali + atau 00 tetap memakai negaranya sendiri.
• max_cost adalah jumlah terbanyak yang Anda setujui untuk dibayar, dalam USD micros. Tugas ditolak, dan tidak ada yang ditagih, jika biayanya akan lebih tinggi atau saldo Anda kurang.

Status dan hasil massal

Baca tugas hingga status adalah completed, failed, atau cancelled. Daftar besar dapat memakan waktu, jadi lakukan polling setiap satu atau dua menit, atau gunakan webhook.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

Unduh file hasil

Saat result_ready adalah true, GET /result mengembalikan tautan unduhan yang berlaku 10 menit. Tautan itu sendiri tidak memerlukan kunci. Minta tautan baru setiap kali Anda perlu mengunduh lagi.

url=$(curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID/result" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" | jq -r .url)
curl --fail --silent --show-error --output result.csv "$url"

result.csv mempertahankan setiap baris asli dalam urutan aslinya dan menambahkan numdetect_status (valid, duplicate, atau invalid), numdetect_country, dan satu kolom per produk dengan yes, no, unknown, unsupported, failed, atau cancelled.

Batalkan tugas yang sedang berjalan

Negara yang belum diperiksa dihentikan, dan dana yang ditahan untuknya kembali ke saldo Anda.

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID/cancel" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

Webhook

Atur URL webhook di halaman pengaturan akun agar diberi tahu saat tugas massal selesai. Kami mengirim satu HTTPS POST per tugas yang selesai:

{
  "type": "bulk_job.finished",
  "data": {
    "id": "10000000-0000-4000-8000-000000000003",
    "status": "completed",
    "total_rows": 1000,
    "valid_rows": 982,
    "charged": 245500,
    "completed_at": "2026-11-11T08:30:00Z"
  }
}

Setiap permintaan membawa header webhook-id, webhook-timestamp, dan webhook-signature. Tanda tangannya adalah v1, diikuti HMAC-SHA256 berformat Base64 dari "<webhook-id>.<webhook-timestamp>.<body>", memakai signing secret Anda (whsec_…, Base64 setelah awalan). Bandingkan sebelum memercayai isi permintaan.

Jawab dengan status 2xx apa pun. Pengiriman yang gagal dicoba ulang beberapa kali, berjarak beberapa menit. Perlakukan webhook-id sebagai unik, karena pengiriman ulang dapat tiba dua kali.

Biaya dan saldo

Cek satuan ditagih sesuai harganya untuk setiap produk yang memberi jawaban pasti. Jawaban unknown dan failed gratis.

Tugas massal menahan biayanya saat Anda mengirimnya: untuk setiap negara dan produk, max(nomor valid, minimum massal produk) × harga massal. Daftar yang selesai ditagih penuh, termasuk baris unknown. Daftar yang gagal atau dibatalkan dikembalikan ke saldo Anda. Baris duplikat dan tidak valid, serta negara yang tidak didukung sebuah produk, gratis.

Jumlah berupa USD micros bilangan bulat: 1 USD = 1.000.000 micros.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/balance-logs?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

POST /checks dan POST /bulk-jobs memerlukan header Idempotency-Key (hingga 128 karakter). Gunakan kunci baru untuk setiap permintaan baru. Jika respons hilang, kirim permintaan yang sama dengan kunci yang sama: Anda mendapat hasil pertama, bukan tagihan kedua.

Error

Error memakai {error: {code, message, request_id}}. Cocokkan code yang stabil, bukan message, dan sertakan request_id saat menghubungi dukungan.

Dapatkan API key AndaCek massalPengaturan webhookPenagihan