Batch Validation

Validates up to 100 phone numbers in one request and returns the same data as the validation endpoint for each, keyed by the number exactly as you sent it.

Use it to clean contact lists, CRM imports or sign-up backlogs without sending one request per number. To also drop numbers that are disconnected or switched off, add hlr=1: only an HLR lookup tells you whether a number is reachable or was ported (see Live network status (HLR) below).

Billing
Each number counts as one request against your quota; the X-Cost header of the response tells you the total. Identical entries in the same batch are validated and billed once. The same number written differently (e.g. +14158586273 and +1 415 858 6273) counts twice. With hlr=1, each answered HLR lookup adds 20 requests (see Live network status (HLR) below).

POST/v1/validate

Batch Validation

Send the numbers as a JSON array in the request body. For quick tests the same lookup also works as GET /v1/validate?numbers=%2B14158586273,%2B442079460000. A number's leading + counts there whether you send it as is or encoded as %2B.

Required attributes

  • Name
    numbers
    Type
    array
    Description

    1 to 100 phone numbers, each with its country prefix unless you set country_code.

Optional attributes

  • Name
    country_code
    Type
    string
    Description

    An ISO Alpha 2 Country Code (e.g. US). Its country prefix is prepended to every number in the batch that does not start with + or 00; those are already international and are looked up as sent.

  • Name
    hlr
    Type
    boolean, query parameter
    Description

    1 adds the live network status (HLR) to every entry: send POST /v1/validate?hlr=1. Paid plans only. See below.

Response

data maps every number, as sent, to the same object /v1/validate/{number} returns. As there, check each entry’s valid field.

A number that cannot be read at all (for example one without any digits) does not fail the batch: its entry is {"valid": false, "number": "...", "error": "invalid_number"}. An unknown country_code gives every entry "error": "invalid_country_code". Only a malformed request, such as an empty list or more than 100 numbers, returns a 422.

Live network status (HLR)

With hlr=1 every entry gets the same HLR fields as the single lookup, from reachable to hlr_error. Only these fields say whether a number is reachable or was ported: without hlr=1, carrier and line_type come from the numbering plan and keep showing the network that issued the number. The batch’s mobile numbers are looked up together within one time budget; a number that is not answered in time gets "hlr_error": "source_unavailable". Numbers it does not apply to (landlines, invalid numbers) get the fields as null with "hlr_supported": false.

Billing
Paid plans only; on the free plan the batch returns 403 with the error code plan_upgrade_required. Each answered HLR lookup costs 20 requests on top of the number’s one request; unanswered and unsupported numbers cost only their one request. X-Cost tells you the total. Your quota must cover the worst case (every mobile number answered) before any lookup runs; otherwise the batch returns 429 with quota.required.

Request

POST
/v1/validate
curl https://api.numlookupapi.com/v1/validate \
    -H "apikey: YOUR-API-KEY" \
    -H "Content-Type: application/json" \
    -d '{"numbers": ["+14158586273", "+44 20 7946 0000"]}'

Response

{
    "data": {
        "+14158586273": {
            "valid": true,
            "number": "14158586273",
            "local_format": "4158586273",
            "international_format": "+14158586273",
            "country_prefix": "+1",
            "country_code": "US",
            "country_name": "United States of America",
            "location": "Novato",
            "carrier": "AT&T Mobility LLC",
            "line_type": "mobile",
            "e164_format": "+14158586273",
            "national_format": "(415) 858-6273",
            "rfc3966_format": "tel:+1-415-858-6273",
            "possible": true,
            "number_type": "landline_or_mobile",
            "timezones": ["America/Los_Angeles"]
        },
        "+44 20 7946 0000": {
            "valid": true,
            "number": "442079460000",
            "local_format": "02079460000",
            "international_format": "+442079460000",
            "country_prefix": "+44",
            "country_code": "GB",
            "country_name": "United Kingdom",
            "location": "London",
            "carrier": "",
            "line_type": "landline",
            "e164_format": "+442079460000",
            "national_format": "020 7946 0000",
            "rfc3966_format": "tel:+44-20-7946-0000",
            "possible": true,
            "number_type": "landline",
            "timezones": ["Europe/London"]
        }
    }
}

With the live network status (HLR)

curl "https://api.numlookupapi.com/v1/validate?hlr=1" \
    -H "apikey: YOUR-API-KEY" \
    -H "Content-Type: application/json" \
    -d '{"numbers": ["+4915112345678", "+44 20 7946 0000"]}'