# Validate and format a phone number

> Canonical documentation: https://www.genderapi.io/docs-phone-validation-formatter-api

Canonical HTML: https://www.genderapi.io/docs-phone-validation-formatter-api

Last reviewed: 2026-09-14

## Request

POST https://api.genderapi.io/api/phone

Use Bearer authentication from trusted server-side code. Provide address context when a national number does not include an international calling code.

| Field | Type | Requirement | Description |
| --- | --- | --- | --- |
| number | string | Required | See OpenAPI schema. |
| address | string | Optional | See OpenAPI schema. |

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

```json
{
  "number": "+1 212 867 5309",
  "address": "US"
}
```

## Response

Check isValid and isPossible separately, and use E.164 output for normalized storage.

| Field | Type | Description |
| --- | --- | --- |
| status | boolean | Returned response field. |
| remaining_credits | integer | Returned response field. |
| expires | integer | Returned response field. |
| duration | string | Returned response field. |
| regionCode | string | ISO 3166-1 alpha-2 country code used as regional context. |
| countryCode | integer | Returned response field. |
| country | string | Returned response field. |
| national | string | Returned response field. |
| international | string | Returned response field. |
| e164 | string | Returned response field. |
| isValid | boolean | Returned response field. |
| isPossible | boolean | Returned response field. |
| numberType | string | Returned response field. |
| nationalSignificantNumber | string | Returned response field. |
| rawInput | string | Returned response field. |
| isGeographical | boolean | Returned response field. |
| areaCode | string | Returned response field. |
| location | string | Returned response field. |

```json
{
  "status": true,
  "remaining_credits": 15709,
  "expires": 0,
  "duration": "18ms",
  "e164": "+12128675309",
  "isValid": true
}
```

## Errors and usage

Confirm current usage accounting in account and pricing documentation.

- [Error codes](https://www.genderapi.io/docs-error-codes)
- [Authentication](https://www.genderapi.io/docs-authentication)
- [OpenAPI JSON](https://www.genderapi.io/openapi/openapi.json)