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

# Phone Validation API

> Abstract's Phone Number Validation and Verification API is a fast, lightweight, modern, and RESTful JSON API for determining the validity and other details of phone numbers from over 190 countries.

It's very simple to use: you only need to submit your API key and a phone number, and the API will respond as assessment of its validity, as well as additional details like the carrier details, line type, region and city details, and more.

## Getting started

### REST

The Phone Number Validation and Verification API, like all of Abstract's APIs, is organized around REST. It is designed to use predictable, resource-oriented URL's and to use HTTP status codes to indicate errors.

### HTTPS

The Phone Number Validation and Verification API requires all communications to be secured TLS 1.2 or greater.

### API Versions

All of Abstract's API are versioned. The Phone Number Validation and Verification API is currently on Version 1.

### Your API Key

Your API key is your unique authentication key to be used to access Abstract's Phone Number Validation and Verification API. Note that each of Abstract's API has a unique API key, so you will need different keys to access the Phone Number Validation and Verification and Email Validation APIs, for example. To authenticate your requests, you will need to append your API key to the base URL.

### Base URL

```
https://phonevalidation.abstractapi.com/v1/
```

### Validation endpoint

Abstract's Phone Number Validation and Verification API simply requires your unique API key and the phone number you'd like to check:

```
https://phonevalidation.abstractapi.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& phone = 14154582468
```

This was a successful request, so the valid phone number and details associated with it are returned below:

<ResponseExample>
  ```json theme={null}
  {
    "phone": "14152007986",
    "valid": true,
    "format": {
      "international": "+14152007986",
      "local": "(415) 200-7986"
    },
    "country": {
      "code": "US",
      "name": "United States",
      "prefix": "+1"
    },
    "location": "California",
    "type": "mobile",
    "carrier": "T-Mobile USA, Inc."
  }
  ```
</ResponseExample>

### Request parameters

<ParamField query="api_key" type="String" required>
  Your unique API key. Note that each user has unique API keys *for each of
  Abstract's APIs*, so your Phone Validation API key will not work for your IP
  Geolocation API, for example.
</ParamField>

<ParamField query="phone" type="String" required>
  The phone number to validate and verify.
</ParamField>

<ParamField query="country" type="String">
  The country's ISO code. Add this parameter to indicate the phone number's country, and the API will append the corresponding country code to its analysis. For instance, add country=US to indicate that the phone number is from the United States.
</ParamField>

### Response parameters

The API response is returned in a universal and lightweight [JSON format](https://www.json.org/json-en.html).

<ResponseField name="phone" type="String">
  The phone number submitted for validation and verification.
</ResponseField>

<ResponseField name="valid" type="Boolean">
  Is true if the phone number submitted is valid.
</ResponseField>

<ResponseField name="format" type="Object">
  The object containing the `international` and `local` formats of the submitted
  number
</ResponseField>

<ResponseField name="format.international" type="String">
  The international format of the submitted phone number. This means appending
  the phone number's country code and a "+" at the beginning.
</ResponseField>

<ResponseField name="format.local" type="String">
  The local or national format of the submitted phone number. For example, it
  removes any international formatting, such as "+1" in the case of the US.
</ResponseField>

<ResponseField name="country" type="Object">
  The object containing details of the phone number's country
</ResponseField>

<ResponseField name="country.code" type="String">
  The country's two letter [ISO 3166-1 alpha-2
  code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
</ResponseField>

<ResponseField name="country.name" type="String">
  The name of the country in which the phone number is registered.
</ResponseField>

<ResponseField name="country.prefix" type="String">
  The country's [calling code
  prefix](https://en.wikipedia.org/wiki/List_of_country_calling_codes).
</ResponseField>

<ResponseField name="location" type="String">
  As much location details as are available from our data. This can include the
  region, state / province, and in some cases down to the city.
</ResponseField>

<ResponseField name="type" type="String">
  The type of phone number. The possible values are: `Landline`, `Mobile`,
  `Satellite`, `Premium`, `Paging`, `Special`, `Toll_Free`, and `Unknown`.
</ResponseField>

<ResponseField name="carrier" type="String">
  The carrier that the number is registered with.
</ResponseField>

## Bulk upload (CSV)

Here are some best practices when bulk uploading a CSV file:

* Ensure the first column contains the phone numbers to be analyzed.
* Remove any empty rows from the file.
* Include only one phone number per row.
* The maximum file size permitted is 50,000 rows.

## Response and error codes

Whenever you make a request that fails for some reason, an error is returned also in the JSON format. The errors include an error code and description, which you can find in detail below.

| Code | Type                  | Details                                                                                                                                                     |
| ---- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200  | OK                    | Everything worked as expected.                                                                                                                              |
| 400  | Bad request           | Bad request.                                                                                                                                                |
| 401  | Unauthorized          | The request was unacceptable. Typically due to the API key missing or incorrect.                                                                            |
| 422  | Quota reached         | The request was aborted due to insufficient API credits. (Free plans)                                                                                       |
| 429  | Too many requests     | The request was aborted due to the number of allowed requests per second being reached. This happens on free plans as requests are limited to 1 per second. |
| 500  | Internal server error | The request could not be completed due to an error on the server side.                                                                                      |
| 503  | Service unavailable   | The server was unavailable.                                                                                                                                 |

## Code samples and libraries

Please see the top of this page for code samples for these languages and more. If we're missing a code sample, or if you'd like to contribute a code sample or library in exchange for free credits, email us at: [team@abstractapi.com](mailto:team@abstractapi.com)

## Other notes

A note on metered billing: Each individual phone number you submit counts as a credit used. Credits are also counted per request, not per successful response. So if you submit a request for the (invalid) phone number "kasj8929hs", that still counts as 1 credit.