Full Examples

Every call below uses the public base URL. Replace YOUR_KEY_HERE with a key from Authentication, and take YOUR_PRODUCT_SLUG from the bulk product list — bulk endpoints address products by slug, never by numeric ID.

https://api.zelnum.com/api/v1

1. Check the balance

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

Bulk work is pre-deducted at submission, so a submission you cannot afford fails up front rather than halfway through.

2. Submit an array of numbers

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"]
  }'

Returns 202 with a task_id. For email products, drop country entirely.

3. Or submit a file

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"

One number or address per line. The row count comes from the file, so the message differs from an array submission — the rest of the response is identical.

4. Poll the task

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

Poll every 3–5 seconds until status is completed or failed. Watch last_progress_at: a timestamp that stops moving means the task is stuck, not merely slow.

5. Get the download URL

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

Fetch the URL it returns before expires_at — the result file is deleted when the retention window closes.

Need one identifier checked now?

Bulk is for thousands of rows and a wait. For a single number or address and an immediate verdict, use Realtime cURL / SDK examples instead.