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

## Example request

**URL**

```http
https://api.ideal-postcodes.co.uk/v1/phone_numbers?api_key=ak_test&query=02071128019
```

**curl**

```bash
curl -G 'https://api.ideal-postcodes.co.uk/v1/phone_numbers' \
  -d 'api_key=ak_test' \
  -d 'query=02071128019'
```

**JavaScript**

```javascript
const response = await fetch(
  'https://api.ideal-postcodes.co.uk/v1/phone_numbers?' +
  new URLSearchParams({
    api_key: 'ak_test',
    query: '02071128019',
  })
);

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

**Python**

```python
import requests

response = requests.get(
    "https://api.ideal-postcodes.co.uk/v1/phone_numbers",
    params={
        "api_key": "ak_test",
        "query": "02071128019",
    },
)
result = response.json()["result"]
```

**Ruby**

```ruby
require "net/http"
require "json"

uri = URI("https://api.ideal-postcodes.co.uk/v1/phone_numbers")
uri.query = URI.encode_www_form(api_key: "ak_test", query: "02071128019")
result = JSON.parse(Net::HTTP.get(uri))["result"]
```

**PHP**

```php
<?php
$response = file_get_contents(
  "https://api.ideal-postcodes.co.uk/v1/phone_numbers?" .
  http_build_query([
    "api_key" => "ak_test",
    "query" => "02071128019",
  ])
);
$result = json_decode($response, true)["result"];
```

## Example response

**200 OK**

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

**400 Bad Request**

response.jsonjson

```json
{
  "code": 4000,
  "message": "Invalid Request"
}
```

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

    * `original_carrier` Carrier

  * InvalidPhoneNumber

    | Field                  | Type            | Description                                                                                                         |
    | ---------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------- |
    | `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](/docs/api/api-reference.md) for the wrapper format.