Realtime Detection
Realtime detection answers one question about one identifier, immediately: is this phone number — or this email address — registered on a given platform?
The engine is the same one the console uses. It accepts a phone number or an email address, checks it against one to ten realtime products, and returns a verdict per product.
When to use it
Section titled “When to use it”| You have | Use |
|---|---|
| One identifier, or a handful, and you need the answer now | Realtime |
| Thousands of identifiers, and you can wait | Bulk detection |
Typical realtime cases are form validation at signup or checkout, one-off lookups inside an internal tool, and a small number of checks inside a workflow that is already running. Bulk is built for files and large arrays: it is asynchronous, priced per row checked, and finished tasks are downloadable.
Two series, one contract
Section titled “Two series, one contract”The series is carried in the path, and it must agree with the products you select:
| Series | Endpoint | identifier |
|---|---|---|
| Phone | POST /v1/realtime/check/phone | E.164 number, for example +8613800138000 |
POST /v1/realtime/check/email | Email address, for example user@example.com |
A request cannot mix series: selecting a phone product and an email product in the same call is rejected. country is optional for a complete E.164 number, and it must be omitted for email.
How one call is counted
Section titled “How one call is counted”One call takes one identifier and one to ten products:
- one
request_idfor the call - one entry per product in
results - one charge per entry
Because every entry is billed on its own, a call can succeed for some products and fail for others. That is reported as status: partial_succeeded, and each entry carries its own billing_status — read those instead of trusting HTTP 200 alone.
The pages in this section
Section titled “The pages in this section”- Phone realtime check — the phone endpoint in full
- Email realtime check — the email endpoint in full
- Realtime products — the live list of products you can select, and how to read an ID off it
- Idempotency & retries — why
Idempotency-Keyis required, and how retries behave - Billing & refunds — what is charged, what is refunded, and when
- cURL / SDK examples — copy-paste calls for the common cases
Before you make the first call
Section titled “Before you make the first call”- Have an API key — see Authentication.
- Read the product IDs you intend to use off Realtime products.
- Send a unique
Idempotency-Keywith every call; it is required, not optional.