# Validate phone number

`POST https://api.foxentry.com/phone/validate`

Foxentry allows you to check validity and the existence of phone numbers. It can also give you additional information about the validated phone number based on the validationType option. Please pay attention to the formatNumber option. This option defines the format of number that should be considered as valid. Foxentry validator is able not only to evaluate the validity of the inputed information but it also can fix various typos, errors and missing data. Foxentry can also suggest more suitable alternatives to the data sent in query. Please pay attention to the result, resultCorrected and suggestions in the response. Always check result.proposal in the response for a proposed solution by Foxentry how you should process the response in your form or application.

## Headers

| Header | Value |
|---|---|
| `Api-Version` | `2.1` or `2.0` |
| `Authorization` | `Bearer <your API key>` |
| `Content-Type` | `application/json` |

## Request body

### request.query

Parameters you want to validate or search for.

| Field | Type | Description |
|---|---|---|
| `prefix` | string | Phone number prefix. |
| `number` | string | Phone number. |
| `numberWithPrefix` | string | Phone number with prefix. |

### request.options

Options that change how the endpoint behaves.

| Field | Type | Description |
|---|---|---|
| `validationType` | string | Type of validation. One of: `basic`, `extended`. Default: `"basic"`. |
| `allowedPrefixes` | array[string] | List of allowed prefixes. |
| `preferredPrefixes` | array[string] | Ordered list of preferred prefixes. If phone number is valid with multiple prefixes, the resultCorrected will use the first valid prefix from this list. If not set, the resultCorrected will be null and there will be all valid combinations in the suggestions. |
| `defaultPrefix` | string or null | Deprecated - use preferredPrefixes instead. Default international prefix if not part of the query. This is used for the validator to make more accurate results. |
| `formatNumber` | boolean | Determines whether the formatted phone number (with spaces) should be considered as valid or not. If this option is set to false, a phone number with spaces would be considered as invalid with format error and a correction would be proposed in resultCorrected. If set to true, a phone number with correct use of spaces would be considered as valid and the national format invalid. Default: `false`. |
| `correctionMode` | string | This option determines how automatic corrections are handled. You can choose between full to allow all corrections, format to fix formatting only, suggestion to return corrected data in suggestions, or none for no corrections to be applied. One of: `full`, `format`, `suggestion`, `none`. Default: `"full"`. |

### request.client

Information about your user, to make results more relevant.

| Field | Type | Description |
|---|---|---|
| `ip` | string |  |
| `country` | string | Country code in ISO-3166-1 alpha-2 format. |
| `location.lat` | number | Client's latitude |
| `location.lon` | number | Client's longitude |

### Example

```json
{
  "request": {
    "query": {
      "numberWithPrefix": "+420775111222"
    },
    "options": {
      "validationType": "extended",
      "allowedPrefixes": [
        "+420",
        "+421"
      ],
      "defaultPrefix": "+420",
      "formatNumber": false
    },
    "client": {
      "country": "CZ",
      "location": {
        "lat": 50.0628,
        "lon": 13.9271
      }
    }
  }
}
```

## Responses

- `200` Successful response. Examples: `valid`, `invalid`, `invalidWithCorrection`, `validWithSuggestion`
- `400` Bad Request
- `401` Unauthorized
- `402` Payment Required
- `403` Forbidden
- `404` Not Found
- `405` Method Not Allowed
- `429` Too Many Requests
- `500` Internal Server Error
- `503` Service Unavailable