# VAT Extraction

> Validate and enrich company data from a VAT number: official business name, legal address, phone numbers, PEC email, and ATECO codes.

## 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, `vatfnx` function `E`, and VAT number to enrich.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `par` | Object | Yes | Country context and extended VAT function. |
| `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**. |
| `par.vatfnx` | String | Yes | VAT-number configuration function. `E` Extended company registry details lookup. Default value: `E` |
| `data` | Object | Yes | Input data to validate |
| `data.vat_number` | Object | Yes | VAT number to query extended company registry for |
| `data.vat_number.cod_description` | String | Yes | VAT number to enrich |

### 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","vatfnx":"E"},"data":{"vat_number":{"cod_description":"01032450072"}}}'
```

## Response

Enriched company profile including business name, tax code, address, phones, emails, activity codes, and quality indicator.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | Object | No | Normalized and enriched validation output data |
| `data.name` | Object | No | Company business name and legal form |
| `data.name.firm_name` | String | No | Company name |
| `data.name.title` | String | No | Company juridical form |
| `data.name.status` | String | No | Company operational status |
| `data.tax_code` | Object | No | Company fiscal code details |
| `data.tax_code.cod_description` | String | No | Tax code description |
| `data.vat_number` | Object | No | Extended VAT registration details |
| `data.vat_number.cod_description` | String | No | VAT number |
| `data.address` | Object | No | Company registered office address details |
| `data.address.standard` | Object | No | Standardized company registered address details |
| `data.address.standard.country` | String | No | Country |
| `data.address.standard.province` | String | No | Province description |
| `data.address.standard.province_code` | String | No | Province abbreviation |
| `data.address.standard.city` | String | No | City name |
| `data.address.standard.zipcode` | String | No | Postal code |
| `data.address.standard.street_type` | String | No | Street type |
| `data.address.standard.street_name` | String | No | Street name |
| `data.address.standard.full_address` | String | No | Full normalized address |
| `data.address.standard.hn` | String | No | House number |
| `data.phones` | Object | No | Associated company phone numbers |
| `data.phones.type` | String | No | Phone type |
| `data.phones.number` | String | No | Phone number |
| `data.emails` | Object | No | Associated company email addresses |
| `data.emails.type` | String | No | Email type |
| `data.emails.email` | String | No | Certified email address (PEC) |
| `data.codes` | Object | No | Economic activity (Ateco) and registry codes |
| `data.codes.type` | String | No | Code type |
| `data.codes.cod_description` | String | No | ATECO economic activity code |
| `quality` | Object | No | Validation quality indicators and score flags |
| `quality.vat_number` | Object | No | Quality indicator result (see https://documentation.egon.com/docs/quality-indicators) |
| `quality.vat_number.flag` | String | No | Quality flag |
| `quality.vat_number.code` | Number | No | Quality result code |
| `quality.vat_number.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**

Company information enriched from VAT number.

```json
{
  "data": {
    "name": {
      "firm_name": "CVA ENERGIE SRL",
      "title": "Societa' A Responsabilita' Limitata",
      "status": "Attiva"
    },
    "tax_code": {
      "cod_description": "01032450072"
    },
    "vat_number": {
      "cod_description": "01032450072"
    },
    "address": {
      "standard": {
        "country": "Italia",
        "province": "Valle D'Aosta/Valle D'Aoste",
        "province_code": "AO",
        "city": "CHATILLON",
        "zipcode": "11024",
        "street_type": "VIA",
        "street_name": "STAZIONE",
        "full_address": "VIA STAZIONE 31, CHATILLON 11024 AO Valle D'Aosta/Valle D'Aoste Italia",
        "hn": "31"
      }
    },
    "phones": [
      {
        "type": "00001",
        "number": "0166822925"
      },
      {
        "type": "00003",
        "number": "0166821032"
      }
    ],
    "emails": [
      {
        "type": "01601",
        "email": "azienda@pec.example.com"
      },
      {
        "type": "01115",
        "email": "info@example.com"
      }
    ],
    "codes": [
      {
        "type": "01600",
        "cod_description": "3514"
      },
      {
        "type": "01116",
        "cod_description": "cvatrading.it"
      },
      {
        "type": "CBILL",
        "cod_description": "CVA ENERGIE S.R.L.#CPVVN#01032450072#002"
      },
      {
        "type": "CBILL",
        "cod_description": "CVA ENERGIE SRL BUSIN. E SMALL BUS. M.L.#93Z76#01032450072#001"
      },
      {
        "type": "CBILL",
        "cod_description": "CVA ENERGIE SRL CLIENTI MERCATO MAGGIOR TUTELA#7G770#01032450072#001"
      },
      {
        "type": "CBILL",
        "cod_description": "CVA ENERGIE SRL CLIENTI RETAIL MERCATO LIBERO#AZKH5#01032450072#001"
      }
    ]
  },
  "quality": {
    "vat_number": {
      "flag": "1",
      "code": 911,
      "description": "CODICE TROVATO: ARRICCHITI DATI DA LIVELLO 2"
    }
  },
  "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"
  }
}
```