# 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.

Canonical: https://mobilevalidate.com/docs · Last updated: 2026-09-25

![A terminal sends an API request and a JSON response returns true, false and null values.](https://mobilevalidate.com/images/api-request-and-json-response.svg)

*One REST call. Every answer is true, false or null (unknown).*


Machine-readable: [Key facts (JSON)](https://mobilevalidate.com/facts.json) · [OpenAPI spec](https://mobilevalidate.com/openapi.yaml)

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?

1. Follow the [quickstart](/docs/quickstart). It uses the public sandbox key, takes about 30 seconds and costs nothing.
2. Read [authentication](/docs/authentication) to understand the three key types and IP allowlists.
3. Use the [test mode](/docs/test-mode) numbers and addresses to build every branch of your integration (registered, not registered, unknown, pending, errors).
4. Choose [real-time lookups](/docs/lookups) or [bulk jobs](/docs/bulk-jobs), and add [webhooks](/docs/webhooks) if you don't want to poll.
5. Handle [errors](/docs/errors) and read the [rate limits and anti-abuse rules](/docs/rate-limits-and-abuse) before going live.

The [services reference](/docs/services) lists every check code, and the [API reference](/docs/api-reference) every endpoint. The [SDK](/docs/sdk), [CLI](/docs/cli) and [MCP server](/docs/mcp) 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](/opt-out).

## 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.