Realtime Single Check

POST/v1/realtime/check/phone

Synchronously check one phone number. A request may select multiple realtime products; use realtime product IDs, never batch product slugs.

Idempotency required

Idempotency-Key is required. Retrying the same request with the same key does not charge twice; changing the payload returns 409. Reused results have cached=true; failed or unknown results are not cached as facts.

Parameters

Field	Type	Required	Description
identifier	string	Yes	One E.164 phone number, for example +8613800138000.
country	string	No	Optional for a complete E.164 number; a national number requires a matching ISO country code.
product_ids	array<int>	Yes	An array of 1 to 10 realtime product IDs.

Response Example

{
  "request_id": "8c1e4f91-7bd8-4d7e-a3ae-3d7e5b0c6c11",
  "identifier": "+8613800138000",
  "status": "succeeded",
  "request_status": "completed",
  "total_reserved": 0.004000,
  "total_charged": 0.004000,
  "total_refunded": 0.000000,
  "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
    }
  ]
}

cURL Example

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

Billing & Semantics

• Billing: each product uses its snapshotted per-check price, including cache hits. Only valid and invalid results are charged; unknown, timeout and busy items are refunded. total_reserved = total_charged + total_refunded; charged_amount is the net charge.
• Partial success: a partially successful combo returns HTTP 200 with status=partial_succeeded; all failed returns status=failed. Inspect each billing_status and error_code instead of relying on HTTP 200 alone.
• Replay: Idempotency-Key is limited to 191 bytes and scoped to the user. After a timeout or HTTP 500, retry the original content with the original key. In-flight replays return 409/request_in_progress. Logs and replay results are retained for 30 days by default.

HTTP Error Handling

HTTP	code	Meaning / action
400	invalid_realtime_request / idempotency_key_required	Fix the number, products or request key; no prepayment.
401 / 403	unauthorized / account_banned / realtime_disabled	Check the key, account status and realtime access; no prepayment.
402	insufficient_balance	Insufficient balance; no combo item starts.
409	request_in_progress / idempotency_conflict	Retry an in-flight request after Retry-After; a conflicting payload cannot reuse the key.
429	realtime_rate_limited	Wait for Retry-After; no prepayment.
503	realtime_route_unavailable / realtime_fact_cache_unavailable / realtime_rate_limiter_unavailable	The route, cache or limiter is unavailable; no prepayment. Retry later.
500	internal_error	The outcome is uncertain. Retry with the original key; do not blindly submit a new key.

Item error_code values identify provider, channel-capacity, deadline, cache or concurrency-protection failures. Failed items are not charged.