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.

#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 the US, Canada and Germany. In test mode the whole +44 7700 9xxxxx range is also allowed, so the documented numbers work:

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

#What about live network status (HLR)?

number.hlr is coming soon. While it is switched off, test keys get 403 service_disabled just like live keys. When it launches, the test numbers will answer: …001 reachable (mcc_mnc: "23415", country: "GB"), …002 unreachable, …003 unknown, …004 pending then reachable, …005 unsupported country, …006 reachable and ported: true.

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