Phone Validation Quick Start Guide

Phone Validation verifies phone numbers by checking validity, format, and carrier information to ensure numbers are active and reachable.

Coverage

Global: Validates phone numbers for 237 countries and territories worldwide
Number types: Supports mobile, landline, and VoIP numbers for business and personal use
Carrier information: Returns network operator, country, and porting details
Format standardization: Provides numbers in both international and national formats

Available Endpoints

Phone Validation provides one primary API endpoint:

Individual Validate - Validate a single phone number in real-time

Getting Started

Create an API key if you don’t have one
Choose your request format (international format or with Country parameter)
Make your first request using the endpoint documentation above

Here’s a simple example request for the Individual Validate endpoint:

curl --request GET \
  --url https://api.addressy.com/PhoneNumberValidation/Interactive/Validate/v2.20/json6.ws

import requests

url = "https://api.addressy.com/PhoneNumberValidation/Interactive/Validate/v2.20/json6.ws"

response = requests.get(url)

print(response.json())

const url = 'https://api.addressy.com/PhoneNumberValidation/Interactive/Validate/v2.20/json6.ws';
const options = {method: 'GET', body: undefined};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.addressy.com/PhoneNumberValidation/Interactive/Validate/v2.20/json6.ws",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.addressy.com/PhoneNumberValidation/Interactive/Validate/v2.20/json6.ws"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.addressy.com/PhoneNumberValidation/Interactive/Validate/v2.20/json6.ws")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.addressy.com/PhoneNumberValidation/Interactive/Validate/v2.20/json6.ws")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

What Phone Validation Returns

Phone Validation provides:

Validation status indicating whether the phone number is valid (Yes, No, or Maybe)
Phone number formatted in both international and national formats
Network operator information including carrier name and country
Number type classification (Mobile, Landline, or VoIP)
Optional porting and roaming details for mobile numbers

Response should be in the following format:

{
  "Items": [
    {
      "PhoneNumber": "+441244657333",
      "RequestProcessed": true,
      "IsValid": "Yes",
      "NetworkCode": "",
      "NetworkName": "BT",
      "NetworkCountry": "GB",
      "NationalFormat": "01244 657333",
      "CountryPrefix": 44,
      "NumberType": "Landline"
    }
  ]
}

And you can use this information below to interpret the response fields:

Response Fields

Validation Results

Field	Type	Description
`IsValid`	string	Whether the number is valid: Yes (valid), No (invalid), or Maybe (full validation couldn’t be performed due to temporary cellular network issues)
`RequestProcessed`	boolean	Returns true if the request was successfully processed on the network, false if validation attempt was unsuccessful

Phone Number Formats

Field	Type	Description
`PhoneNumber`	string	The phone number in international format
`NationalFormat`	string	The phone number in domestic network format (useful for dialing within the same country)
`CountryPrefix`	integer	The country prefix that must be prepended when dialing internationally

Network Information

Field	Type	Description
`NetworkCode`	string	The current operator code serving the supplied number
`NetworkName`	string	The name of the current operator serving the supplied number
`NetworkCountry`	string	The country code of the operator
`NumberType`	string	The type of number detected: Mobile, Landline, or VoIP

Mobile-Specific Fields (Optional)

Field	Type	Description
`MccMnc`	string	Mobile country code and mobile network code concatenated
`Ported`	string	Returns True if the number has been ported to another network
`PortedNetworkName`	string	The network name that the mobile number is currently registered with after porting
`PortedNetworkCountry`	string	The country code of the network that the mobile number has been ported to
`Roaming`	string	Returns True if the number is currently roaming in another country
`RoamingNetworkName`	string	The network name that the mobile number is currently registered with while roaming
`RoamingNetworkCountry`	string	The country that the mobile number is currently in while roaming
`OriginalNetworkName`	string	The original network name that the mobile number was registered with
`OriginalNetworkCountry`	string	The original country code that the phone was registered with

Note: Mobile-specific fields (porting and roaming information) are only returned when applicable and available for the queried number.

Request Parameters

Required Parameters

Parameter	Type	Description
`Key`	string	Your API key to authenticate to the service
`Phone`	string	The phone number to validate

Optional Parameters

Parameter	Type	Description
`Country`	string	Two- or three-digit ISO country code (e.g., GB/GBR for UK, US/USA for USA). Required if phone number is not in international format

Request Format Options

Phone Validation accepts numbers in two formats:International format (recommended):

Include country code with + prefix: +441244657333
No Country parameter needed

National format:

Omit country code: 01244657333
Must include Country parameter: Country=GBR

Both formats return identical validation results.

Error Response Fields

When an error occurs, the API returns an error response with the following structure:

Field	Type	Description
`Error`	string	The error ID
`Description`	string	A description of the error
`Cause`	string	The cause of the error
`Resolution`	string	Actions to resolve the error

Common Error Codes

Status Code	Meaning	Common Causes
400	Bad Request	Invalid parameters, malformed phone number, missing required Phone parameter
401	Unauthorized	Invalid or missing API key
403	Forbidden	API key doesn’t have permission for Phone Validation, or daily limit exceeded
500	Internal Server Error	Server-side issue, temporary service disruption

Tip: Check the Resolution field for specific steps to fix the error. For more details on error responses, see Individual Validate in API documentation.

Note: Phone Validation uses a three-step process combining Loqate’s custom libraries with the Home Location Register (HLR) database to verify phone number validity and carrier information.

Try Phone Validation

Test Phone Validation using the Individual Validate Playground to make your first request.

FAQ

Should I use international format or the Country parameter?

Both methods work identically and return the same validation results. However, international format is recommended for simplicity:

International format: Include the country code with + prefix (e.g., +441244657333). No Country parameter needed
National format: Omit the country code (e.g., 01244657333) and include the Country parameter (e.g., Country=GBR)

International format is cleaner and reduces the chance of errors from missing or incorrect Country parameters.

What does 'Maybe' mean in the IsValid field?

An IsValid value of Maybe indicates that full validation couldn’t be performed, typically due to:

Temporary cellular network issues
Failures in the validation procedure on the carrier side

When you receive Maybe, the number format and country code are valid, but the system couldn’t confirm if the specific number is currently active. You may want to retry the validation or treat these numbers cautiously in your workflow.

Can Phone Validation check all types of phone numbers?

Yes, Phone Validation supports all major phone number types:

Mobile: Cellular phone numbers with optional porting and roaming details
Landline: Fixed-line telephone numbers
VoIP: Voice over IP numbers

The service works for both business and personal phone numbers across 237 countries and territories globally.

What information is returned about mobile numbers?

For mobile numbers, Phone Validation returns standard network information plus optional mobile-specific details:

Current network operator and country
Whether the number has been ported to another carrier
Porting details (if applicable)
Roaming status and location (if currently roaming)
Original network registration information

These fields help you understand the number’s current status and carrier, which is useful for routing messages or understanding deliverability.

Overview

Location Solutions

Data Validation

Resources

Phone Validation Quick Start Guide

Coverage

Available Endpoints

Getting Started

What Phone Validation Returns

Validation Results

Phone Number Formats

Network Information

Mobile-Specific Fields (Optional)

Required Parameters

Optional Parameters

Request Format Options

Common Error Codes

Try Phone Validation

FAQ

​Coverage

​Available Endpoints

​Getting Started

​What Phone Validation Returns

​Validation Results

​Phone Number Formats

​Network Information

​Mobile-Specific Fields (Optional)

​Required Parameters

​Optional Parameters

​Request Format Options

​Common Error Codes

​Try Phone Validation

​FAQ

Coverage

Available Endpoints

Getting Started

What Phone Validation Returns

Validation Results

Phone Number Formats

Network Information

Mobile-Specific Fields (Optional)

Required Parameters

Optional Parameters

Request Format Options

Common Error Codes

Try Phone Validation

FAQ