Test mode

Test keys (mv_test_…) give you free, predictable answers so you can build and test every branch of your integration. They never reach a real network and are never billed. They follow the same validation, request limits and request shapes as live keys; daily caps, spend caps and the daily e-mail-pattern rule apply only to live keys. The test numbers and addresses below always return the same result.

The public sandbox key used in the examples on this site is a test key that accepts only these documented values. Any other input returns 403 sandbox_magic_only. A personal test key accepts any number or address.

Which test numbers can I use?

The test numbers come from the +44 7700 900000–900999 range, which the UK regulator reserves for drama and is never assigned to anyone. Live keys refuse the whole +44 7700 9xxxxx block. These answers apply to every yes/no service (WhatsApp, Telegram, Viber, account checks and so on):

Services limited to some countries answer unsupported_country for other numbers. The test numbers above are exempt, so they work with every service. Bulk-only services are refused on POST /v1/lookup in test mode too, just as in live mode.

For sample data, demos and screenshots outside the API, take numbers from ranges regulators reserve for fiction with the free test phone number generator, never random valid numbers.

What do the carrier lookups return in test mode?

network.carrier and network.carrier_us return data rather than yes/no:

As in live mode, a conclusive data answer has registered: true ("data found"). A non-conclusive one has registered: null.

What does spam reputation return in test mode?

number.spam covers all countries except sanctioned ones. Access to it is limited (see the service page): the public sandbox key and accounts without access get 403 service_disabled. With access, the documented numbers return fixed answers:

All spam test data is invented. None of it comes from real reports.

What do HLR and MNP lookups return in test mode?

number.hlr (live network status) and number.mnp (number portability) share the same test numbers. The MNP answer is the porting part of the HLR answer:

As in live mode, unknown and unsupported_country are never billed. Test answers never contain SIM or location identifiers.

Which test e-mail addresses can I use?

The domain is test.mobilevalidate.com. The part before the @ picks the answer for every e-mail service:

Live keys may not use this domain (400 test_number_only, "Test e-mail addresses can only be used with test keys.").

What does a test error look like?

The error test numbers return the real error shape, so you can test your retry and top-up handling:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests (test mode).",
    "status": 429,
    "retryable": true,
    "param": null,
    "doc_url": "https://mobilevalidate.com/docs/errors#rate_limited",
    "request_id": "req_0VWF4BOF195D5GjKfh0P"
  }
}

Test keys are rate limited like live keys (10 requests per second, burst 20). The public sandbox key has its own per-IP limits (30 requests per minute, 1,000 per day). A fast loop can therefore get a real rate_limited answer as well.

With a test key, a pending lookup sends its lookup.completed webhook when the lookup is read again after the 5 seconds (the request's own wait, or a later GET /v1/lookups/{id}). The payload has the same fields as a live one, with "livemode": false. Test jobs finish immediately and send no job webhooks.