MobileValidate API documentation
Developer docs for the MobileValidate API: check phone numbers and e-mail addresses in real time or in bulk jobs, with test mode, webhooks and SDKs.
The MobileValidate API checks phone numbers and e-mail addresses against a catalog of services. These include messaging-app registration, carrier and line type, spam reputation, and account and mailbox checks. One request can run several checks. Each check returns registered: true, false or null (unknown), or a short list of data attributes. You're not charged for inconclusive results.
How is the API organised?
It has three ways in, plus account endpoints:
| Surface | Endpoint | Use it for |
|---|---|---|
| Real-time lookups | POST /v1/lookup, GET /v1/lookups/{id} | 1–100 numbers and/or e-mails; the request waits up to 30 s for answers |
| Bulk jobs | POST /v1/jobs/estimate, POST /v1/jobs, GET /v1/jobs/{id}, …/results, …/download | Up to 50,000 identifiers per job, including services offered in bulk only |
| Webhooks | /v1/webhook_endpoints | Signed notifications when lookups and jobs finish |
| Account | GET /v1/account, /v1/limits, /v1/usage, /v1/services | Balance, limits, usage and the service catalog for your key |
The base URL is https://api.mobilevalidate.com/v1. Requests and responses are JSON (UTF-8), timestamps are RFC 3339 in UTC, and money is a decimal string such as {"amount": "0.0012", "currency": "USD"}. Phone numbers and e-mail addresses go only in POST bodies, never in URLs or headers.
What does every answer contain?
Every identifier gets one result per requested service. The results sit in a checks map keyed by service code, such as checks["telegram.registered"]. Each result has the same fields:
| Field | Meaning |
|---|---|
status | completed, pending, unknown, unsupported_country or failed |
registered | true / false for a conclusive answer, null otherwise |
attributes | Service-specific data (e.g. line_type, carrier, risk_level), or null |
confidence, confidence_score | high / medium / low and a 0–1 score for conclusive answers |
checked_at, cached, age_seconds | When the answer was obtained and whether it came from your account's cache |
billed | Whether this check was charged |
reason | Why an answer is not conclusive (e.g. UPSTREAM_TIMEOUT, UNSUPPORTED_COUNTRY) |
false is only ever a conclusive negative. Anything uncertain is null, and uncertain results are free.
Where should I start?
- Follow the quickstart. It uses the public sandbox key, takes about 30 seconds and costs nothing.
- Read authentication to understand the three key types and IP allowlists.
- Use the test mode numbers and addresses to build every branch of your integration (registered, not registered, unknown, pending, errors).
- Choose real-time lookups or bulk jobs, and add webhooks if you don't want to poll.
- Handle errors and read the rate limits and anti-abuse rules before going live.
The services reference lists every check code, and the API reference every endpoint. The SDK, CLI and MCP server wrap the same API.
What does the API never return?
The checks answer whether an account or mailbox exists, or give network and reputation facts about a number. They never return names, photos, profile data, report texts or location. Roaming is shown only as a country. Checking numbers one after another in sequence, or checking lists of made-up addresses, is refused. Everyone whose number or e-mail address is checked can object through the opt-out form.
Frequently asked questions
Do I need an account to try the API?
No. Every example in these docs uses the public sandbox key, which answers the documented test numbers and e-mail addresses for free. For your own data you need a personal test key, and live keys come with an approved access request. Test keys are free, never billed and never reach a real network.
Which base URL do I use?
All endpoints live under https://api.mobilevalidate.com/v1. Send JSON over HTTPS with your key in the Authorization header.
Is there a machine-readable specification?
Yes. The OpenAPI 3.1 file is published at /openapi.yaml (the API also serves it at /v1/openapi.yaml), and /docs/api-reference renders it as an interactive reference.