# Validate name data

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

Foxentry allows you to check the validity and real existence of names and their combinations. At least one parameter is required in the query. You can either write down the name separately or use nameSurname as connected parameter. Pay attention to the query options. Especially validationDepth, which determines how strict the validation should be based on your use case. For example you'd want minimal validationDepth for web forms since you usually don't want to disturb the user too much with error messages and suggestions. 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 |
|---|---|---|
| `name` | string or null | First name. |
| `surname` | string or null | Last name / family name. |
| `nameSurname` | string or null | Name and surname together. |

### request.options

Options that change how the endpoint behaves.

| Field | Type | Description |
|---|---|---|
| `dataScope` | string | Data scope of returned data. In full datascope information like gender, vocative and date of the name days is returned. One of: `basic`, `full`. Default: `"basic"`. |
| `dataSource` | array[string] | Allowed data sources. You can specify the exact data sources that should be used by the validator. This option is not available for the endpoints that do not use any internal databases (e-mails, phone numbers). Default: `["CZ", "SK"]`. |
| `acceptDegrees` | boolean | Allow to enter a title directly into the name, surname or nameSurname input. For example "Ing. Jan Novák" would be considered as valid/invalid nameSurname Default: `false`. |
| `acceptContext` | boolean | Allow to insert context directly into name, surname or nameSurname. For example "Jan Novák ml." or "Jan Novák mladší" would be considered as valid/invalid nameSurname Default: `false`. |
| `validationDepth` | string | Specifies the depth of name validation. In other words how strict the validator should behave. Minimal = all the names are considered valid as long as there are no forbidden characters used or we are 100% sure the name is invalid. Usually the only thing corrected is format. Moderate = something in between the minimal and strict validation. There are more instances of corrections like typos etc. Strict = the most strict validation depth. Missing names in our database are marked as invalid, the scoring for corrections and suggestions is tweaked. One of: `minimal`, `moderate`, `strict`. Default: `"strict"`. |
| `smartMode` | boolean | Allows to correct the name (resultCorrected). If this is disabled, the corrections are given as a suggestion. Default: `true`. |

### 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": {
      "name": "test",
      "surname": "Ing. Petr Novák ml."
    },
    "options": {
      "dataScope": "full",
      "acceptDegrees": true,
      "acceptContext": false,
      "validationDepth": "strict",
      "smartMode": true
    },
    "client": {
      "country": "CZ",
      "location": {
        "lat": 50.0628,
        "lon": 13.9271
      }
    }
  }
}
```

## Responses

- `200` Successful response. Examples: `valid`, `invalid`, `invalidWithCorrection`, `validWithSuggestion`, `validNameSurnameFullDataScope`, `fullDataScope`
- `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