API reference

Runs every requested check (see GET /v1/services) for every identifier of the check's input type: phone checks for numbers, e-mail checks for emails. Result rows come back in order: numbers first, then e-mails. The call waits up to wait seconds (default 10) for all answers; if some are still running it answers 202 with status: pending and a next.poll_url (or use a webhook). Checks without real-time support are refused with 403 service_disabled (param checks[i]) — send them in a bulk job. E-mail checks answer only whether an account or mailbox exists — never names, photos or profiles.

Returns a lookup created by POST /v1/lookup, optionally waiting up to wait seconds for pending checks. input is masked on later reads; e164 and email are returned. Lookups expire after the account's retention period (404 not_found afterwards).

Validates and counts a list without storing it, calling a data source or charging: valid, invalid and duplicate rows, cached answers, the maximum possible cost (max_cost) and its breakdown per check and unit price. Checks in parts too small for the bulk price (WhatsApp: fewer than 132 numbers from one country in the job) are priced at the real-time price and listed with reason: small_batch. Bulk-only checks bill each country of the job at least minimum_checks × the bulk price when it returns an answer; countries with fewer numbers are listed with reason: country_minimum and their minimum is included in max_cost. Same body as POST /v1/jobs.

Checks up to 50,000 numbers and e-mail addresses (JSON body, or a CSV upload as multipart/form-data). The maximum possible cost is reserved up front (bulk prices; real-time prices for parts too small for the bulk price, see POST /v1/jobs/estimate); cached, inconclusive, invalid and duplicate rows are released when the job finishes. Poll GET /v1/jobs/{id} (or subscribe to job.completed), then page through GET /v1/jobs/{id}/results or download the whole file. Test-key jobs complete immediately.

Status, progress and cost of a job. wait (0–30 s) holds the request until the job reaches a final status (completed, failed or cancelled) or the time runs out. Keys with jobs:read see their own jobs; jobs:read_all sees every job of the account.

Running job → cancelled: rows not yet sent to a data source are released and never charged; rows already sent finish and are billed as usual. Finished job → its per-row results are deleted now instead of at the end of the retention period (purged_at is set).

One item per row (number or e-mail address) in input order, with every check of the row. Filter by registered / status of one service; page with limit and after = the previous page's next_cursor.

Streams the whole result file, one line per row (numbers, then e-mails) in input order. CSV columns: row_no, input_masked, e164, country, number_status, service, status, registered, business, checked_at, cached, billed (for the row's primary check = first requested check of its kind), then kind, email, email_status, then per service <service>.status, <service>.registered, <service>.<attribute>, <service>.billed (empty for rows of the other kind). NDJSON lines have the same shape as result items.

Balance, reserved amount and today's usage (UTC) of the key's account. Needs account:read.

Request rate, request sizes, the daily identifiers cap and the key's daily spend cap. Daily counters reset at 00:00 UTC. The public sandbox key is limited per client IP address instead: it answers sandbox: true, rate_limit with per: "ip", requests_per_minute and requests_per_day (no requests_per_second/burst), jobs.max_numbers 10 and no daily_numbers.

Checks, conclusive answers, cached answers, billed units and cost for an inclusive UTC date range (at most 366 days), for the key's mode (live or test). Rows past the retention period are no longer counted.

Every endpoint of the account that is not deleted and has the same mode as the key (test keys list test endpoints, live keys live endpoints). Needs webhooks:manage.

Registers a public HTTPS URL (at most 20 per account). The response contains the signing secret — shown only once. The endpoint stays pending_verification until it answers our signed webhook.verification event with a 2xx status. Not available with the public sandbox key.

Changes the URL and/or the subscribed events. A new URL must be verified again (pending_verification).

Nothing is delivered to a deleted endpoint.

Queues a signed webhook.test event to the endpoint (delivered even before verification). Use it to check your signature code.

Without a key: the public catalog. With a key: every check the key's account may use, at the account's prices. Lists active phone and e-mail checks; switched-off checks are not listed.

Issues a personal test key (mv_test_…) for a work e-mail address, protected by a Cloudflare Turnstile token from the form at https://mobilevalidate.com/get-test-key. The key works in test mode with any number (never billed, never reaches a data source), including bulk jobs and test-mode webhooks. It is shown once and never returned again. Each address can receive at most 3 test keys in 30 days; after that the answer is 409 test_key_exists. At most 3 requests per network per day, whatever their result (IPv6 networks count per /64). The request also asks for live access, which we review by hand. No authentication.

No authentication. 200 when the API can reach its database, 503 otherwise.