> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loqate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone Validation Quick Start Guide

> Validate phone numbers in real-time to ensure accurate contact information

**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**](/api-reference/phone-validation/individual-validate) - Validate a single phone number in real-time

## Getting Started

1. [Create an API key](https://docs.loqate.com/loqate-basics/create-an-api-key) if you don't have one
2. Choose your request format (international format or with Country parameter)
3. Make your first request using the endpoint documentation above

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

<CodeGroup>
  ```shell cURL theme={null}
  curl --request GET \
    --url https://api.addressy.com/PhoneNumberValidation/Interactive/Validate/v2.20/json6.ws
  ```

  ```python Python theme={null}
  import requests

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

  response = requests.get(url)

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  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 PHP theme={null}
  <?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;
  }
  ```

  ```go Go theme={null}
  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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://api.addressy.com/PhoneNumberValidation/Interactive/Validate/v2.20/json6.ws")
    .asString();
  ```

  ```ruby Ruby theme={null}
  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
  ```
</CodeGroup>

## 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:

```json theme={null}
{
  "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:

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/api-reference/phone-validation/individual-validate) in API documentation.
  </Accordion>
</AccordionGroup>

**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](/api-reference/phone-validation/individual-validate?playground=open) to make your first request.

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>