---
title: "Phone Number Validation"
method: GET
path: "/phone_numbers"
tags: ["Phone Numbers"]
---

# Phone Number Validation

`GET /phone_numbers`

Query for and validate phone numbers.

## Query parameters

- `api_key` string
- `query` string, required
- `current_carrier` 'true'
- `tags` string

## Response `200`

Success

- PhoneNumberResponse
  - `code` 2000, required
  - `message` 'Success', required
  - `result` union, required
    - PhoneNumber
      - `valid` true, required
      - `national_format` string, required — Phone number formatted to local standard
      - `international_format` string, required — Phone number formatted to international standard
      - `iso_country` string, required — Country code in 3 letter ISO format
      - `iso_country_2` string, required — Country code in 2 letter ISO format
      - `country` string, required — Full country name
      - `current_carrier` Carrier, nullable, required
        - `network_code` string, nullable, required — The [Mobile Country Code](https://en.wikipedia.org/wiki/Mobile_country_code) for the carrier.
        - `name` string, nullable, required — The full name of the carrier that number is associated with.
        - `country` string, nullable, required — Country that number is associated with. In ISO 3166-1 alpha-2 format.
        - `network_type` 'mobile' | 'landline' | 'landline_premium' | 'landline_tollfree' | 'virtual' | 'unknown' | 'pager' | 'mobile_or_landline' | 'shared_cost' | 'uan' | 'voicemail', nullable, required — Type of network that number is associated with.
      - `original_carrier` Carrier, nullable, required
        - `network_code` string, nullable, required — The [Mobile Country Code](https://en.wikipedia.org/wiki/Mobile_country_code) for the carrier.
        - `name` string, nullable, required — The full name of the carrier that number is associated with.
        - `country` string, nullable, required — Country that number is associated with. In ISO 3166-1 alpha-2 format.
        - `network_type` 'mobile' | 'landline' | 'landline_premium' | 'landline_tollfree' | 'virtual' | 'unknown' | 'pager' | 'mobile_or_landline' | 'shared_cost' | 'uan' | 'voicemail', nullable, required — Type of network that number is associated with.
    - InvalidPhoneNumber
      - `valid` false, required
      - `national_format` 'null', nullable, required — Phone number formatted to local standard
      - `international_format` 'null', nullable, required — Phone number formatted to international standard
      - `iso_country` 'null', nullable, required — Country code in 3 letter ISO format
      - `iso_country_2` 'null', nullable, required — Country code in 2 letter ISO format
      - `country` 'null', nullable, required — Full country name
      - `current_carrier` 'null', nullable — Representation of current phone carrier information like network code, name, country, network type
      - `original_carrier` 'null', nullable — Representation of original phone carrier information like network code, name, country, network type

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `429` — Rate Limit Timeout

## Changes

- **2024-05-14** `1b87cbe3241c` — 1 warning, 1 info
  - deleted the `query` request parameter `Tags`
  - added the new optional `query` request parameter `tags`
- **2023-09-05** `69a98ad9ac33` — 1 info
  - added the non-success response with the status `401`
- **2023-07-06** `a5eed9e99274` — 2 info
  - added the new optional `query` request parameter `Tags`
  - the `query` request parameter `api_key` became optional
- **2023-04-26** `42c322d6d0e5` — 1 breaking, 1 info
  - removed the enum value `true` from the `query` request parameter `current_carrier`
  - added the new enum value `true` to the `query` request parameter `current_carrier`
- **2023-04-25** `e6f3a4b9f164` — 8 warning, 1 info
  - added the new `mobile_or_landline` enum value to the `result/oneOf[subschema #1: Phone Number Object]/current_carrier/network_type` response property for the response status `200`
  - added the new `mobile_or_landline` enum value to the `result/oneOf[subschema #1: Phone Number Object]/original_carrier/network_type` response property for the response status `200`
  - added the new `shared_cost` enum value to the `result/oneOf[subschema #1: Phone Number Object]/current_carrier/network_type` response property for the response status `200`
  - added the new `shared_cost` enum value to the `result/oneOf[subschema #1: Phone Number Object]/original_carrier/network_type` response property for the response status `200`
  - …5 more

[Full history](https://skmtc.dev/ideal-postcodes/apis/api-reference/changes/phone_numbers/get.md)

---

[API](https://skmtc.dev/ideal-postcodes/apis/api-reference.md) · [All operations](https://skmtc.dev/ideal-postcodes/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ideal-postcodes/api-reference/revisions/295dd3238f22/schema)