Number verification

Verify a number (HLR)

POSThttps://api.smsedge.com/v1/verify/number-hlr/

Asks the mobile network (HLR lookup) if a number is active, and returns the result and its cost.

An HLR lookup costs money. The price depends on the country and is in hlr.cost.

  1. Send the request. The first response usually has "stage": "waiting", because the network answers some seconds later.
  2. Send the same request again after a few seconds. Repeat until stage is finished or failed.
  • You pay once for each number in each 24 hours. Repeat calls for the same number in that time are free.
  • A result is kept for 60 days. After that, the next call makes a new lookup.
  • hlr.status is good (active), bad (not active) or unknown.
  • raw_response is the answer from the HLR provider. Its fields change with the provider.

Body params (form)

  • numberstringrequired

    Phone number in international or local format.

  • country_idstringoptional

    SMSEdge country ID or ISO 3166-1 alpha-2 code. Send it for numbers in local format.

Responses

  • 200The lookup is finished, or it is still in progress (stage waiting).
  • 400The number is missing or not valid, or the country is not known.
  • 404HLR lookups are not available for this country, or the lookup could not start.
curl -X POST "https://api.smsedge.com/v1/verify/number-hlr/" \
  -H "X-API-KEY: YOUR_API_KEY" \
  --data-urlencode "number=447700900123"
[
  {
    "success": true,
    "data": {
      "normalized_number": "447700900123",
      "national_number": "7700900123",
      "country_id": 225,
      "country_name": "United Kingdom",
      "hlr": {
        "status": "good",
        "operator": "EE",
        "raw_response": {
          "msisdn": "447700900123",
          "status": "delivered",
          "ported": false
        },
        "stage": "finished",
        "cost": 0.004
      }
    },
    "errors": [],
    "response": {
      "code": 200,
      "description": "OK",
      "date": "2026-11-16 14:41:00"
    },
    "api": {
      "version": "v1",
      "module": "verify",
      "function": "number-hlr"
    },
    "user": {
      "id": 12345
    }
  }
]

All requests need your API key in the X-API-KEY header. See Authentication.