Phone Number Validation

GET/v1/phone_numbers

Validates a phone number and returns its country, its national and international formats, and the network it was originally assigned to.

Requires an API Key licensed for phone validation.

Every query decrements your lookup balance, including a number that fails to parse and a number reported as invalid.

Query parameters

api_key string optional: API Key

Your unique identifier that allows access to our APIs.

Begins ak_. Available from your dashboard.
Example ak_test
query string: Specifies the phone number to validate. Phone number must include a country code in an acceptable format. For instance, UK phone numbers should be prefixed with +44, 44 or 0044.
current_carrier string optional: When set to true, the API retrieves and populates the current network of the phone number.

This operation can be slow, depending on the network and local conditions.
Enum
"true"
tags string optional: Tags

A comma separated list of tags to query over.

Useful if you want to specify the circumstances in which the request was made.

If you specify multiple tags, the response comprises only requests that satisfy all of them. Searching "foo,bar" queries only requests tagged both "foo" and "bar".
Example foo,bar

Response

result is an object containing phone validation and carrier information.

result one of
- PhoneNumber
  - valid boolean
    Values
    "true"
  - national_format string
    Phone number formatted to local standard
    Example
    020 7112 8019
  - international_format string
    Phone number formatted to international standard
    Example
    442071128019
  - iso_country string
    Country code in 3 letter ISO format
    Example
    GBR
  - iso_country_2 string
    Country code in 2 letter ISO format
    Example
    GB
  - country string
    Full country name
    Example
    United Kingdom
  - current_carrier Carrier
    network_code string
    The Mobile Country Code for the carrier.
    Example
    234
    name string
    The full name of the carrier that number is associated with.
    Example
    BT Group
    country string
    Country that number is associated with. In ISO 3166-1 alpha-2 format.
    Example
    GB
    network_type string
    Type of network that number is associated with.
    Values
    11 possible values
    "mobile"
    "landline"
    "landline_premium"
    "landline_tollfree"
    "virtual"
    "unknown"
    "pager"
    "mobile_or_landline"
    "shared_cost"
    "uan"
    "voicemail"
  - original_carrier Carrier
    network_code string
    The Mobile Country Code for the carrier.
    Example
    234
    name string
    The full name of the carrier that number is associated with.
    Example
    BT Group
    country string
    Country that number is associated with. In ISO 3166-1 alpha-2 format.
    Example
    GB
    network_type string
    Type of network that number is associated with.
    Values
    11 possible values
    "mobile"
    "landline"
    "landline_premium"
    "landline_tollfree"
    "virtual"
    "unknown"
    "pager"
    "mobile_or_landline"
    "shared_cost"
    "uan"
    "voicemail"
- InvalidPhoneNumber
  - valid boolean
    Values
    "false"
  - national_format string
    Phone number formatted to local standard
    Values
    "null"
  - international_format string
    Phone number formatted to international standard
    Values
    "null"
  - iso_country string
    Country code in 3 letter ISO format
    Values
    "null"
  - iso_country_2 string
    Country code in 2 letter ISO format
    Values
    "null"
  - country string
    Full country name
    Values
    "null"
  - current_carrier string optional
    Representation of current phone carrier information like network code, name, country, network type
    Values
    "null"
  - original_carrier string optional
    Representation of original phone carrier information like network code, name, country, network type
    Values
    "null"

The result sits inside the standard { result, code, message } envelope — see the API reference for the wrapper format.

Request

https://api.addresszen.com/v1/phone_numbers?api_key=ak_test&query=02071128019

curl -G 'https://api.addresszen.com/v1/phone_numbers' \
  -d 'api_key=ak_test' \
  -d 'query=02071128019'

const response = await fetch(
  'https://api.addresszen.com/v1/phone_numbers?' +
  new URLSearchParams({
    api_key: 'ak_test',
    query: '02071128019',
  })
);

const { result } = await response.json();

import requests

response = requests.get(
    "https://api.addresszen.com/v1/phone_numbers",
    params={
        "api_key": "ak_test",
        "query": "02071128019",
    },
)
result = response.json()["result"]

require "net/http"
require "json"

uri = URI("https://api.addresszen.com/v1/phone_numbers")
uri.query = URI.encode_www_form(api_key: "ak_test", query: "02071128019")
result = JSON.parse(Net::HTTP.get(uri))["result"]

<?php
$response = file_get_contents(
  "https://api.addresszen.com/v1/phone_numbers?" .
  http_build_query([
    "api_key" => "ak_test",
    "query" => "02071128019",
  ])
);
$result = json_decode($response, true)["result"];

Response

200 OK
400 Bad Request

{
  "result": {
    "valid": true,
    "national_format": "020 7112 8019",
    "international_format": "+44 20 7112 8019",
    "iso_country": "GBR",
    "iso_country_2": "GB",
    "country": "United Kingdom",
    "current_carrier": {
      "network_code": null,
      "name": "Invomo Ltd",
      "country": "GB",
      "network_type": "landline"
    },
    "original_carrier": {
      "network_code": null,
      "name": "Invomo Ltd",
      "country": "GB",
      "network_type": "landline"
    }
  },
  "code": 2000,
  "message": "Success"
}

response.json
{
  "code": 4000,
  "message": "Invalid Request"
}

Query parameters​

Response​

Query parameters

Response