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.

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.

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. Encode the leading + as %2B in query strings, otherwise it is read as a space and the country prefix is lost.

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) applied to every number that has no country prefix.

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.

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"]
        }
    }
}