Phone Number Validator API

Description

Validate a phonenr in accordance with internationally accepted standards. This endpoint will also try to gather as much metadata as possible about the origin country and the carrier.

Endpoint

> GET https://api.jsonrepo.com/v1/compute/validator/phonenr

Headers

Field Description
api_key Required Your API Key

Parameters

Field Type Description
phonenr String Required The phone number to validate
region String Optional The phone number's region (case insensitive)
Format: ISO a-2
Example: US

International Prefix & Region:

If you supply the phonenr parameter with an international prefix (ex. +17035555678), the endpoint will parse all the regional information automatically. However, if the number provided is a local one without an international prefix (ex. 7035555678), the region parameter will be required. Failing to provide region information can cause lookup collision and will end up in a failed request.

URL-Encoding

As is the case with all of our endpoints, make sure to URL-encode your parameters properly. Failing to URL-encode an international phonenr will result in an execution error.

Response

A successful request will result in a populated payload field with the expected output.

A failed request will result in an error output as detailed in Error Rules. If the endpoint validation fails due to missing, badly formatted or invalid parameters, the endpoint will return HTTP code 400 along with a message detailing the error.

See the examples section for more information.

A Lorenum.com product

Twitter Discord Email

Request

  • Curl
// Lookup an international `phonenr`

curl -G \
https://api.jsonrepo.com/v1/compute/validator/phonenr \
-H "api_key: {YOUR_API_KEY_HERE}" \
--data-urlencode "phonenr=+17035555678" 

// Lookup a `phonenr` with a specified `region`

curl -G \
https://api.jsonrepo.com/v1/compute/validator/phonenr \
-H "api_key: {YOUR_API_KEY_HERE}" \
--data-urlencode "phonenr=7035555678" \ 
--data-urlencode "region=US"

Success Response

{
    "http_code": 200,
    "http_message": "Ok",
    "message": "Successful execution",
    "payload": {
        "phone_number": {
            "is_valid": true,
            "input": {
                "phonenr": "7035555678",
                "region": "US"
            },
            "geo": {
                "region_code": "US",
                "region_prefix": 1,
                "geocoding": "Virginia"
            },
            "formats": {
                "e164": "+17035555678",
                "national": "(703) 555-5678",
                "international": "+1 703-555-5678"
            },
            "type": "fixed_line_or_mobile",
            "carrier": "Verizon",
            "timezone": [
                "America/New_York"
            ]
        }
    }
}

Error Response Examples

// Request with no `phonenr` parameter

{
    "http_code": 400,
    "http_message": "Bad Request",
    "message": "Malformed request: `phonenr` parameter was not provided.",
    "payload": []
}

// Request with local `phonenr` without a specified `region`

{
    "http_code": 400,
    "http_message": "Bad Request",
    "message": "Malformed request: The provided `phonenr` + `region` combination is unparsable.",
    "payload": []
}