Dokumentasi API

Autentikasi

Semua endpoint memerlukan kunci API di header permintaan. The public product catalog does not require authentication.

http

X-API-Key: YOUR_KEY_HERE

Authorization: Bearer YOUR_KEY_HERE

Kunci Anda terdiri dari 51 karakter: awalan zn_ diikuti 48 karakter acak. Kunci yang sebelumnya diterbitkan dengan awalan ck_ tetap valid.

Kunci API tersedia di Konsol pada "Pusat API". Kunci dalam teks polos hanya ditampilkan sekali saat dibuat; simpan segera.

Format Respons

Semua endpoint mengembalikan JSON.

Contoh respons realtime

json

{
  "request_id": "8c1e4f91-7bd8-4d7e-a3ae-3d7e5b0c6c11",
  "status": "succeeded",
  "replayed": false,
  "results": []
}

Contoh respons bulk

json

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "message": "Task queued."
}

GET /v1/balance

Dapatkan Saldo

Mengembalikan saldo USD saat ini untuk akun terautentikasi.

Contoh Respons

json

{ "balance": "5.230000" }

GET /v1/products

Daftar Produk

Katalog produk publik; API Key tidak diperlukan. Katalog ini mengembalikan produk realtime dan bulk yang aktif, seri, serta jumlah minimum. Baca sebelum mengirim permintaan.

Contoh Respons

json

{
  "data": [
    {
      "id": 101,
      "slug": "whatsapp-realtime",
      "name": "WhatsApp Number Checker",
      "name_translations": { "zh_CN": "WhatsApp 注册检测" },
      "mode": "realtime",
      "series": "phone",
      "min_phones": 1
    }
  ]
}

GET /v1/api-key

Detail API Key

Mengembalikan metadata API Key akun yang telah diautentikasi. Kunci teks asli tidak pernah dikembalikan.

json

{
  "api_key_id": 42,
  "masked_key": "ck_••••••••••••••••••••••••••••••••••••••••••••••••",
  "last_used": "2026-09-05T10:00:00Z",
  "created_at": "2026-08-01T09:00:00Z"
}

Kunci teks asli hanya ditampilkan sekali saat dibuat atau diputar ulang; endpoint ini hanya mengembalikan nilai yang disamarkan.

Kode Kesalahan

Saat gagal, periksa kode status HTTP dan field message.

Isi Respons Error

json

{
  "code": "insufficient_balance",
  "message": "Insufficient balance for this submission."
}

Error bisnis selalu mengembalikan code yang dapat dibaca mesin agar bisa ditangani secara terprogram. Parameter tidak valid (validasi) dan rute tidak dikenal mengembalikan format standar Laravel: { "message": "...", "errors": { ... } }. Validasi input sebelum mengirim.

Kesalahan

code	HTTP	Deskripsi
unauthorized	401	Kunci API hilang, tidak valid, atau tidak aktif.
account_banned	403	Akun ditangguhkan. Hubungi dukungan.
invalid_realtime_request	400	Permintaan realtime tidak valid (mis. nomor telepon tanpa prefiks internasional + saat country dikosongkan).
idempotency_key_required	400	Permintaan realtime wajib menyertakan header Idempotency-Key.
invalid_idempotency_key	422	Idempotency-Key tidak valid: 1-128 karakter huruf, angka, dan . _ : -
idempotency_conflict	409	Idempotency-Key yang sama digunakan untuk isi permintaan yang berbeda.
request_in_progress	409	Permintaan realtime identik masih diproses. Coba lagi sebentar lagi (Retry-After: 1).
empty_input	422	Berkas yang diunggah tidak berisi baris yang dapat dipakai.
product_not_found	422	Slug produk yang dikirim tidak ada atau tidak aktif.
product_mode_not_supported	422	Endpoint ini tidak menerima mode produk ini (produk realtime tidak untuk endpoint massal).
invalid_country	422	Produk ini tidak mendukung negara yang dikirim.
too_few_numbers	422	Jumlah pengiriman di bawah minimum produk.
too_many_numbers	422	Jumlah pengiriman melebihi maksimum platform.
insufficient_balance	402	Saldo tidak cukup. Isi ulang lalu coba lagi.
realtime_disabled	403	Deteksi realtime belum diaktifkan untuk akun ini.
realtime_rate_limited	429	Batas laju realtime terlampaui. Hormati retry_after.
product_pricing_unavailable	503	Harga produk ini belum dikonfigurasi. Hubungi dukungan.
detection_capacity_unavailable	503	Tidak ada kapasitas deteksi saat ini. Coba lagi nanti.
realtime_route_unavailable	503	Tidak ada rute realtime yang tersedia. Coba lagi nanti.
realtime_fact_cache_unavailable	503	Dependensi realtime sementara tidak tersedia. Coba lagi nanti.
realtime_rate_limiter_unavailable	503	Rate limiter sementara tidak tersedia. Coba lagi nanti.
not_found	404	task_id tidak ada atau milik akun lain.
result_not_ready	422	Tugas belum selesai atau berkas hasilnya belum dibuat.
result_expired	404	Berkas hasil sudah kedaluwarsa, hilang, atau tidak tersedia.
validation_failed	422	Periksa field wajib, format nomor, dan tipe berkas.
internal_error	500	Kesalahan server tak terduga. Aman untuk mencoba ulang dengan Idempotency-Key yang sama.

Batas Laju

Permintaan API dibatasi per kunci API, per grup endpoint:

Endpoint	Batas
GET /v1/products · GET /v1/balance · GET /v1/api-key · GET /v1/tasks/{token} · GET /v1/tasks/{token}/result · GET /v1/tasks/{token}/download	60 permintaan / menit per API key (120 / menit per IP)
Endpoint: POST /v1/detect · POST /v1/detect/file · POST /v1/quotes/bulk	10 permintaan / menit per API key (30 / menit per IP)
Endpoint: POST /v1/realtime/quote/{series} · POST /v1/realtime/check/{series} · POST /v1/realtime/detect	Token bucket per API key: burst 60, isi ulang 1/detik (≈60 / menit berkelanjutan); per akun: burst 120, isi ulang 2/detik. Lapisan IP mengizinkan 180 / menit. Setiap respons menyertakan header X-RateLimit-Remaining.

Saat batas terlampaui, API mengembalikan 429 dengan header Retry-After (respons realtime juga menyertakan field retry_after). Hentikan permintaan selama jumlah detik yang disebutkan, lalu lanjutkan dengan exponential backoff.

POST /v1/realtime/check/{series}

Pemeriksaan satu identitas secara realtime

Periksa satu nomor telepon atau alamat email secara sinkron. Satu permintaan dapat memilih beberapa produk realtime dari seri yang sama berdasarkan ID; jangan gunakan slug produk massal.

Idempotency-Key wajib. Mengulang permintaan yang sama dengan kunci yang sama tidak menagih dua kali; perubahan isi menghasilkan 409. cached=true berarti hasil digunakan kembali.

Parameter

Kolom	Tipe	Wajib	Deskripsi
series	path	Ya	Seri: phone atau email; harus sama dengan seri produk realtime yang dipilih.
identifier	string	Ya	Satu identitas: nomor E.164 atau alamat email yang valid.
country	string	Tidak	Hanya untuk telepon: opsional untuk E.164 lengkap; nomor lokal membutuhkan kode negara ISO yang sesuai. Kosongkan untuk email.
product_ids	array<int>	Ya	Daftar 1 sampai 10 ID produk realtime.

Contoh Respons

json

{
  "request_id": "8c1e4f91-7bd8-4d7e-a3ae-3d7e5b0c6c11",
  "identifier": "+8613800138000",
  "series": "phone",
  "status": "succeeded",
  "request_status": "completed",
  "total_reserved": 0.004000,
  "total_charged": 0.004000,
  "total_refunded": 0.000000,
  "charged_amount": 0.004000,
  "refunded_amount": 0.000000,
  "replayed": false,
  "results": [
    {
      "product_id": 101,
      "product": "whatsapp-realtime",
      "result": "valid",
      "cached": false,
      "billing_status": "charged",
      "charged_amount": 0.004000,
      "refunded_amount": 0.000000,
      "checked_at": "2026-09-05T10:00:00Z",
      "error_code": null
    }
  ]
}

Contoh cURL

bash

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/phone" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"+8613800138000","country":"CN","product_ids":[101,102]}'

bash

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/email" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"[email protected]","country":null,"product_ids":[201]}'

Setiap produk memakai harga per pemeriksaan yang dikunci untuk permintaan, termasuk hasil cache. valid dan invalid ditagih; unknown, timeout, dan item sibuk dikembalikan.

Kombinasi yang berhasil sebagian mengembalikan HTTP 200 dengan status=partial_succeeded; semua gagal memakai status=failed. Periksa billing_status dan error_code tiap item.

Idempotency-Key maksimal 191 byte dan berlaku per pengguna. Setelah timeout atau error 500, ulangi isi asli dengan kunci asli. Hasil disimpan 30 hari secara default.

HTTP	code	Arti / tindakan
400	invalid_realtime_request / idempotency_key_required	Perbaiki nomor, produk, atau kunci; tidak ada biaya yang dicadangkan.
401 / 403	unauthorized / account_banned / realtime_disabled	Periksa kunci, status akun, dan akses realtime; tidak ada biaya yang dicadangkan.
402	insufficient_balance	Saldo tidak cukup; tidak ada item yang dijalankan.
409	request_in_progress / idempotency_conflict	Ulangi sesuai Retry-After; isi berbeda tidak dapat memakai kunci yang sama.
429	realtime_rate_limited	Tunggu sesuai Retry-After; tidak ada biaya yang dicadangkan.
503	realtime_route_unavailable / realtime_fact_cache_unavailable / realtime_rate_limiter_unavailable	Rute, cache, atau pembatas tidak tersedia; coba lagi nanti.
500	internal_error	Hasil belum pasti. Ulangi dengan kunci asli dan jangan membuat kunci baru.

error_code menunjukkan kegagalan penyedia, kapasitas kanal, tenggat, cache, atau perlindungan konkurensi. Item gagal tidak ditagih.

Endpoint kompatibilitas POST /v1/realtime/detect dipertahankan sementara untuk klien lama. Integrasi baru harus menggunakan /v1/realtime/check/phone atau /v1/realtime/check/email.

Daftar Produk · Tunggal (realtime)

Produk realtime dipilih berdasarkan ID produk dan seri; jangan gunakan slug produk bulk.

Nama produk	Series	Identitas panggilan	Jumlah minimum
Pemeriksaan Nomor Amazon	`phone`	`#53`	1
Pemeriksaan Email Amazon	`email`	`#54`	1
Pemeriksaan Nomor Apple ID	`phone`	`#57`	1
Pemeriksaan Email Apple ID	`email`	`#58`	1
Pemeriksaan Nomor BAND	`phone`	`#60`	1
Pemeriksaan Nomor Facebook	`phone`	`#51`	1
Pemeriksaan Email Facebook	`email`	`#52`	1
Pemeriksaan Nomor Instagram	`phone`	`#48`	1
Pemeriksaan Email Instagram	`email`	`#49`	1
Pemeriksaan Nomor Microsoft	`phone`	`#59`	1
Pemeriksaan Nomor Telegram	`phone`	`#50`	1
Pemeriksaan Nomor Viber	`phone`	`#55`	1
Pemeriksaan Nomor WhatsApp	`phone`	`#47`	1
Pemeriksaan Nomor Telepon di X	`phone`	`#61`	1

POST /v1/detect

Kirim Pemeriksaan (Array)

Kirim array nomor telepon atau email untuk pemeriksaan massal asinkron. Biaya ditahan dan item yang tidak diproses dikembalikan.

Jumlah minimum ditentukan produk dan maksimum platform adalah 2.000.000. Abaikan country untuk email; wajib untuk telepon.

HTTP 202 Accepted

Parameter

Kolom	Tipe	Wajib	Deskripsi
product	string	Ya	Slug produk. Lihat daftar produk.
country	string	Wajib untuk nomor telepon; kosongkan untuk email	Kode negara ISO 3166-1 dua huruf. Wajib untuk telepon; abaikan untuk email.
phones	array	Ya	Array telepon atau email; produk menentukan minimum dan maksimum adalah 2.000.000.

Contoh Respons

json

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "idempotent_replay": false,
  "message": "Task queued. Poll GET /api/v1/tasks/xKj9aP3qLm7v for progress.",
  "recovery_pending": false,
  "summary": {
    "total": 5000,
    "cost_deducted": 0.500000
  }
}

POST /v1/detect/file

Kirim Pemeriksaan (Unggah Berkas)

Unggah TXT atau CSV untuk pemeriksaan massal, satu telepon atau email per baris, maksimal 50 MB.

HTTP 202 Accepted

Parameter

Content-Type: multipart/form-data

Kolom	Tipe	Wajib	Deskripsi
product	string	Ya	Slug produk
country	string	Wajib untuk nomor telepon; kosongkan untuk email	Kode negara ISO untuk telepon; abaikan untuk email.
file	file	Ya	File TXT atau CSV, satu telepon atau email per baris, maksimal 50 MB.

Contoh Respons

json

{
  "mode": "async",
  "task_id": "qH5rZ7Lp3Wm9",
  "idempotent_replay": false,
  "message": "File queued (10000 numbers). Poll GET /api/v1/tasks/qH5rZ7Lp3Wm9 for progress.",
  "recovery_pending": false,
  "summary": {
    "total": 10000,
    "cost_deducted": 1.000000
  }
}

GET /v1/tasks/{token}

Status Tugas

Polling tugas hingga status completed atau failed. Interval direkomendasikan: 3–5 detik.

Contoh Respons

json

{
  "task_id": "xKj9aP3qLm7v",
  "status": "completed",
  "progress": 100,
  "product": "YOUR_PRODUCT_SLUG",
  "country": "CN",
  "submitted": 5000,
  "prefiltered": 0,
  "deduped": 0,
  "total": 5000,
  "processed": 5000,
  "valid": 3800,
  "invalid": 1200,
  "unknown": 0,
  "unknown_processed": 0,
  "unknown_unprocessed": 0,
  "stage": "completed",
  "stage_seconds": 12,
  "last_progress_at": "2026-09-05T10:00:12+00:00",
  "failure_message": null,
  "cost_deducted": "0.500000",
  "cost_refunded": "0.000000",
  "result_available": true,
  "result_expires_at": "2026-05-02T10:00:00+00:00",
  "created_at": "2026-05-01T10:00:00+00:00"
}

Status Tugas

status	Deskripsi
pending	Masuk antrean, menunggu resource.
processing	Pemeriksaan sedang berjalan.
completed	Selesai. Hasil siap diunduh.
failed	Eksekusi gagal.

GET /v1/tasks/{token}/result

URL Unduhan

Setelah selesai, ambil URL unduh untuk berkas hasil. Berkas disimpan selama 7 hari secara default (dikontrol oleh setting result_retention_days).

Contoh Respons

json

{
  "task_id": "xKj9aP3qLm7v",
  "download_url": "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v/download",
  "expires_at": "2026-05-02T10:00:00+00:00",
  "summary": {
    "submitted": 5000,
    "prefiltered": 0,
    "deduped": 0,
    "total": 5000,
    "valid": 3800,
    "invalid": 1200,
    "unknown": 0,
    "unknown_processed": 0,
    "unknown_unprocessed": 0
  }
}

GET /v1/tasks/{token}/download

Unduh hasil

Mengunduh berkas hasil tugas yang selesai selama masih dalam masa penyimpanan.

Contoh Respons

Content-Type: application/zip (or text/csv for a single result).

Endpoint ini mengirim berkas, bukan JSON. Mengembalikan 404/422 jika tugas belum siap, kedaluwarsa, tidak tersedia, atau milik akun lain.

Daftar Produk · Massal (asinkron)

Gunakan nilai slug di field product saat mengajukan tugas.

Nama produk	Identitas panggilan	Jumlah minimum
Pemeriksaan Nomor Amazon	`amazonValid`	500
Pemeriksaan Email Amazon	`amazonEmailValid`	1000
Pemeriksaan Nomor Apple ID	`appleidValid`	2000
Pemeriksaan Email Apple ID	`appleidEmailValid`	1000
Pemeriksaan Nomor BAND	`bandValid`	500
Pemeriksaan Nomor Binance	`binanceValid`	2000
Pemeriksaan Email Binance	`binanceEmailValid`	2000
Pemeriksaan Nomor CoinW	`coinwValid`	2000
Pemeriksaan Email CoinW	`coinwEmailValid`	2000
Pemeriksaan Nomor Facebook	`fbValid`	500
Pemeriksaan Email Facebook	`fbEmailValid`	1000
Pemeriksaan Nomor HTX	`htxValid`	1000
Pemeriksaan Email HTX	`htxEmailValid`	2000
Pemeriksaan Nomor iMessage	`imessageValid`	2000
Pemeriksaan Nomor Instagram	`insValid`	500
Pemeriksaan Email Instagram	`insEmailValid`	1000
Pemeriksaan Nomor KuCoin	`kucoinValid`	1000
Pemeriksaan Email KuCoin	`kucoinEmailValid`	2000
Usia & Gender LINE	`lineGender`	2000
Pemeriksaan Nomor LINE	`lineValid`	2000
Profil Lengkap Linkedin	`linkedinGender`	2000
Pemeriksaan Nomor Linkedin	`linkedinValid`	2000
Pemeriksaan Nomor Microsoft	`microsoftValid`	500
Pemeriksaan Dukungan RCS	`rcsValid`	1000
Pemeriksaan Nomor Signal	`signalValid`	2000
Pemeriksaan Nomor Snapchat	`snapchatValid`	500
Profil Lengkap Telegram	`tgGender`	500
Pemeriksaan Nomor Telegram	`tgValid`	1000
Pemeriksaan Aktivitas Telegram	`tgActive`	500
Pencarian Username TikTok	`tiktokUsername`	2000
Pemeriksaan Nomor Viber	`viberValid`	1000
Pemeriksaan Aktivitas Viber	`viberActive`	1000
Profil Lengkap WhatsApp	`waGender`	1000
Pemeriksaan Nomor WhatsApp	`waValid`	1000
Detail Aktivitas WhatsApp	`waActive`	500
Pemeriksaan Nomor Telepon di X	`twitterValid`	2000
Pemeriksaan Email X	`twitterEmailValid`	2000
Usia & Gender Zalo	`zaloGender`	500
Pemeriksaan Nomor Zalo	`zaloValid`	2000
Filter Aktivitas Internet	`live-activity-filter`	2000
Pemeriksaan Status Nomor	`phone-status-check`	2000
Cek Nyala/Mati Ponsel	`phone-onoff-check`	1500
Deteksi Model Ponsel	`phone-model-detection`	500
Pencarian HLR	`hlr-lookup`	2000

Contoh Lengkap

Salin dan jalankan contoh cURL ini — ganti YOUR_KEY_HERE dan parameter.

1. Lihat saldo

bash

curl -X GET "https://api.zelnum.com/api/v1/balance" \
  -H "X-API-Key: YOUR_KEY_HERE"

2. Kirim pemeriksaan

bash

curl -X POST "https://api.zelnum.com/api/v1/detect" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "YOUR_PRODUCT_SLUG",
    "country": "CN",
    "phones": ["+8613800138000", "+8613900139000"]
  }'

3. Unggah berkas

bash

curl -X POST "https://api.zelnum.com/api/v1/detect/file" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -F "product=YOUR_PRODUCT_SLUG" \
  -F "country=CN" \
  -F "file=@/path/to/numbers.txt"

4. Cek status tugas

bash

curl -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v" \
  -H "X-API-Key: YOUR_KEY_HERE"

5. Ambil URL unduhan

bash

curl -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v/result" \
  -H "X-API-Key: YOUR_KEY_HERE"