Glossary

Terms are defined as the API uses them. Where a word also has a looser everyday meaning, the API’s meaning is the one that applies.

Identifiers and products

Term	Meaning
identifier	The single thing a realtime check is about: one phone number or one email address. A bulk submission carries a list of them.
series	Whether an identifier is a phone or an email. Products, endpoints and requests are all series-specific, and a request may only mix series in the sense that it must not mix them at all.
product	One detection target — a platform, plus the kind of check performed against it. “WhatsApp Number Checker” and “WhatsApp Activity Details” are two different products, even though both concern WhatsApp.
realtime product	A product used through the synchronous endpoints. Addressed by its numeric ID.
bulk product	A product used through the asynchronous endpoints. Addressed by its slug.
ID	The integer that identifies a realtime product, printed as #47 in the catalog. IDs are what product_ids takes.
slug	The string that identifies a bulk product, for example waValid. Slugs are what the product field takes.
mode	realtime or async. A product belongs to exactly one, and the mode decides which endpoints accept it.

IDs and slugs are not interchangeable

A realtime ID never resolves on a bulk endpoint, and a bulk slug never resolves on a realtime one. Mixing them is the single most common integration mistake, and neither side resolves it silently — but they fail differently, because the two sides validate differently:

• product_ids is validated as an array of integers, so a string slug is rejected as 400 invalid_realtime_request before any product lookup happens.
• The bulk product field is looked up by slug, so a realtime product’s slug is found — and then rejected as 422 product_mode_not_supported, because the async endpoints accept async products only.

Verdicts

Term	Meaning
registered	What detection actually answers: is this identifier registered on this platform? It is not a statement about whether the number or address is syntactically valid, reachable, or in service.
valid	Confirmed registered. Charged.
invalid	Confirmed not registered. Charged — a negative answer is still an answer.
unknown	The provider could not resolve it. Not charged; refunded.
cached	The verdict was served from a stored fact rather than by asking a supplier. A cache hit is still charged.
combo	One realtime request, one identifier, and the one-to-ten products it was checked against. A combo can partly succeed — see partial_succeeded.

Money

Term	Meaning
reserve	Take the amount up front before the work runs. Every submission is reserved against the account balance.
settle	Decide an individual item’s final charge once its verdict is known.
refund	Return the reserved amount for an item that produced no usable verdict.
billing_status	Per-item field: charged or refunded. Read this rather than inferring from the HTTP status.
total_reserved	Reserved before the work ran. Always equals total_charged + total_refunded.
charged_amount	Net charge. refunded_amount is the net refund.

Requests and tasks

Term	Meaning
request_id	UUID identifying one realtime submission. Quote it in support requests.
task_id	The token identifying one bulk submission, returned on submit. Also the {token} path parameter of the task endpoints — one value, two names in the documentation.
Idempotency-Key	A caller-supplied header, required on realtime calls, that makes a retry safe: the same key with the same body returns the stored result instead of charging again.
replayed	The response came from a stored result rather than fresh work. replayed on a realtime response, idempotent_replay on a bulk submission. A replay never moves money.
recovery_pending	The bulk task is queued, but its accounting is still being reconciled.

Task counters

Term	Meaning
submitted	Rows you sent.
prefiltered	Rows dropped before detection — malformed lines, for example.
deduped	Duplicate rows removed.
total	Rows actually checked: submitted minus prefiltered minus deduped.
processed	Rows the upstream channel has finished so far.
unknown_unprocessed	Rows that never resolved. These are the ones refunded.

Limits and retention

Term	Meaning
per-key limit	The budget attached to your API key. This is the one to plan against.
per-IP limit	A coarser ceiling shared by every key behind one address. Not an access control.
retention	How long a record survives. Realtime logs and replay results: 30 days. Bulk result files: 7 days.

Related

• Response format — the envelope, and how money and timestamps are encoded
• Error codes — the same vocabulary applied to failures