Phone Number Validation Endpoint

On this page, we’ll dive into the phone number validation endpoint you can use to validate any given phone number and retrieve its carrier and location information.

GET/v1/validate/{number}

Validate Phone Number

This phone validation endpoint provides information about carrier & location information.

Required attributes

  • Name
    number
    Type
    string, path parameter
    Description

    The phone number you want to query (Either: including the country prefix, or without and you specify the country_code).

Optional attributes

  • Name
    country_code
    Type
    string
    Description

    An ISO Alpha 2 Country Code for the phone number (e.g. US). If you specify this parameter you do not need to prepend the country prefix

Possible line_type values

  • landline
  • mobile
  • satellite
  • paging
  • special_services
  • premium_rate
  • toll_free
  • N/A

Invalid numbers

A well-formed but unrecognised number does not produce an error: the API returns HTTP 200 with "valid": false, empty strings for the formatting, country, location and carrier fields, and "line_type": "N/A".

Always check the valid field of the response, not the HTTP status code. A 422 status is only returned for malformed input, e.g. an empty number (invalid_number) or an unknown country_code (invalid_country_code) — see Request Status Codes.

Request

GET
/v1/validate/{number}
curl -G https://api.numlookupapi.com/v1/validate/+14158586273 \
    -H "apikey: YOUR-API-KEY"

Full Response

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

Response for an unrecognised number

{
    "valid": false,
    "number": "14158586273",
    "local_format": "",
    "international_format": "",
    "country_prefix": "",
    "country_code": "",
    "country_name": "",
    "location": "",
    "carrier": "",
    "line_type": "N/A"
}