# Name

> Validate personal names, sole proprietorships, company names, co-holder names, and family surnames, and return normalized and structured output.

## Endpoint

`POST https://{host}:{port}/Egon/api/norm`

Replace `{host}` and `{port}` with the address of your Egon instance.

## Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | String | Yes | Authentication token sent in the `token` request header. |

## Request

Country context and person or company name string to validate.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `par` | Object | Yes | Country context for name analysis and validation. |
| `par.iso2` | String | No | Country code, ISO 3166-1 alpha-2. One of `iso2` or `iso3` is **required**. |
| `par.iso3` | String | No | Country code, ISO 3166-1 alpha-3. One of `iso2` or `iso3` is **required**. |
| `data` | Object | Yes | Input data to validate |
| `data.name` | Object | Yes |  |
| `data.name.type_ana` | String | No | Name analysis type |
| `data.name.gender` | String | No | Gender |
| `data.name.full_name` | String | No | Full name |
| `data.name.mid_name` | String | No | Middle name |
| `data.name.first_name` | String | No | First name |
| `data.name.title` | String | No | Title |
| `data.name.name_des` | String | No | Name description |
| `data.name.birth_date` | String | No | Date of birth |
| `data.name.birth_province` | String | No | Province of birth |
| `data.name.birth_place` | String | No | Place of birth |

### Example request

```bash
curl -X POST "https://{host}:{port}/Egon/api/norm" \
  -H "token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"par":{"iso3":"ITA"},"data":{"name":{"full_name":"Dottor Mario Rossi"}}}'
```

## Response

Structured name components, recognized gender, separated title/surname/name, and quality indicators.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | Object | No | Normalized and enriched validation output data |
| `data.name` | Object | No | Parsed, validated, and normalized personal name details |
| `data.name.type_ana` | String | No | Customer data type |
| `data.name.gender` | String | No | Gender |
| `data.name.full_name` | String | No | Validated full name |
| `data.name.last_name` | String | No | Separate surname |
| `data.name.mid_name` | String | No | Middle name |
| `data.name.first_name` | String | No | Separate name |
| `data.name.prename` | String | No | Name suffix (e.g. Junior/Senior) |
| `data.name.title` | String | No | Academic or professional title |
| `data.name.firm_type` | String | No | Official juridical specification (e.g. S.R.L., S.P.A.) |
| `data.name.birth_date` | String | No | Date of birth in YYYYMMDD format |
| `data.name.birth_country` | String | No | Country of birth |
| `data.name.birth_province` | String | No | Province of birth |
| `data.name.birth_place` | String | No | City of birth |
| `data.name.name_des` | String | No | Name designator |
| `data.name.status` | String | No | Status |
| `quality` | Object | No | Validation quality indicators and score flags |
| `quality.name` | Object | No | Quality indicators for personal name parsing and demographic verification |
| `quality.name.person` | Object | No | Quality indicator result (see https://documentation.egon.com/docs/quality-indicators) |
| `quality.name.person.flag` | String | No | Quality flag |
| `quality.name.person.code` | Number | No | Quality result code |
| `quality.name.person.description` | String | No | Quality result description |
| `quality.name.birth_date` | Object | No | Quality indicator result (see https://documentation.egon.com/docs/quality-indicators) |
| `quality.name.birth_date.flag` | String | No | Quality flag |
| `quality.name.birth_date.code` | Number | No | Quality result code |
| `quality.name.birth_date.description` | String | No | Quality result description |
| `quality.name.birth_place` | Object | No | Quality indicator result (see https://documentation.egon.com/docs/quality-indicators) |
| `quality.name.birth_place.flag` | String | No | Quality flag |
| `quality.name.birth_place.code` | Number | No | Quality result code |
| `quality.name.birth_place.description` | String | No | Quality result description |
| `system` | Object | No | Request processing status. |
| `system.ret_code` | Number | No | Processing result code. 0 means no blocking error. |
| `system.des_ret_code` | String | No | Human-readable processing result. |

### Example responses

**HTTP 200: Valid response**

Name successfully recognized, titles separated, and structured into first name and surname.

```json
{
  "data": {
    "name": {
      "type_ana": "1",
      "gender": "1",
      "full_name": "ROSSI,MARIO",
      "last_name": "ROSSI",
      "first_name": "MARIO",
      "title": "DOTTORE"
    }
  },
  "quality": {
    "name": {
      "person": {
        "flag": "0",
        "code": 0,
        "description": "Ok"
      }
    }
  },
  "system": {
    "ret_code": 0,
    "des_ret_code": "Ok"
  }
}
```

**HTTP 200: Missing par**

The request is missing the required par object.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "par not found"
  }
}
```

**HTTP 200: Missing iso2 and iso3**

Iso2 or Iso3 field is missing.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "iso2 or iso3 parameter not found"
  }
}
```

**HTTP 200: Invalid iso2**

The iso2 value is not valid.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "iso2 not found"
  }
}
```

**HTTP 200: Invalid iso3**

The iso3 value is not valid.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "iso3 not found"
  }
}
```

**HTTP 200: Missing data**

The request is missing the required data object.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "data not found"
  }
}
```

**HTTP 200: Missing token**

Provide the required authentication token in the token request header.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "token not found"
  }
}
```

**HTTP 200: Invalid token**

The supplied token is invalid, expired, or not authorized for this service.

```json
{
  "system": {
    "ret_code": 1,
    "des_ret_code": "token not valid"
  }
}
```