--- title: "Italy" url: "https://developer.incode.com/general-reference/italy/" section: "general-reference" group: "eKYB Reference / eKYB Prefill Coverage" version: "v1.1" status: "live" --- # Italy eKYB Prefill in Italy leverages Italy's source of truth to automatically retrieve and populate business information based on a company's CCIAA/NREA number, VAT/Tax Code, or Codice Fiscale, including the business name, registered address, entity type, registration status, directors, shareholders, and additional financial and corporate data, without requiring manual input from the user. ## Source | Country | Source | Description | | --- | --- | --- | | Italy | `IT_KYB_PREFILL` | Returns matching Italian business details from Italy's source of truth for pre-fill. | ## Direct API approach For general integration notes and shared response semantics, see the [eKYB Prefill API Reference](/general-reference/ekyb-prefill-api-reference/). All module configurations and user data can be forwarded directly in the request for performing a Prefill lookup. This overrides existing configuration and data collected about the user. ### Endpoint `POST /omni/externalVerification/ekyb-prefill` ### Request parameters | Parameter | Required | Description | | --- | --- | --- | | plugins | Mandatory | String array. Must be `["ekyb-prefill"]`. Specifies the Prefill flow. | | source | Mandatory | String. Must be `IT_KYB_PREFILL`. Identifies the Prefill source. | | country | Mandatory | String. Two-letter Alpha-2 country code. Must be `IT`. | | taxId | Mandatory | String. Italian business identifier. See Tax ID formats for details. | | businessName | Optional | String. Registered name of the business. When provided, adds `nameMatch` to the response. | | address | Optional | String. Business address as a freeform string. When provided, adds `addressMatch` to the response. | ### Tax ID formats The `taxId` field accepts three Italian business identifier types. Routing between them is determined automatically by the format of the submitted value. | ID Type | Description | Format | Example | | --- | --- | --- | --- | | **CCIAA/NREA** | Chamber of Commerce registration number | 2 letters + 6 or 7 digits | `BR123456`, `VA187262` | | **Partita IVA** (VAT/Tax Code) | Italian VAT identifier | 11 numeric digits. A leading `IT` prefix is stripped automatically before processing. | `02324830740`, `IT08719600960` | | **Codice Fiscale** | Personal tax code for sole traders | 16-character alphanumeric | `CGNMHL70D16A225B` | Inputs that do not match any of the above formats return a 400 error. ### Sample request ```json { "plugins": ["ekyb-prefill"], "source": "IT_KYB_PREFILL", "country": "IT", "taxId": "BR123456", "businessName": "ITALIA VENEZIA ENTERPRISE", "address": "STRADA MILANO STRADA 17, 72014 CISTERNINO BR" } ``` ### Sample response The Prefill response returns business data retrieved directly from the source of truth. Fields are returned as-is from the source. `nameMatch` and `addressMatch` are only present when `businessName` or `address` were submitted in the request. Fields such as `turnover`, `employeeCount`, `shareholders`, `directors`, `creditRating`, and `companySize` may be absent for sole traders and smaller companies — this is expected, not an error. **Example 1 — ITALIA VENEZIA ENTERPRISE (Limited Liability Company)** ```json { "kyb-prefill": [ { "tin": "BR123456", "vatNo": "12345678901", "name": "ITALIA VENEZIA ENTERPRISE - SOCIETA' A RESPONSABILITA' LIMITATA", "nameMatch": "Verified", "address": "STRADA MILANO STRADA 17, 72014 CISTERNINO BR", "city": "CISTERNINO", "postalCode": "72014", "entityType": "LIMITED LIABILITY COMPANY", "registrationStatus": "Active", "creditRating": "C", "creditRatingDescription": "Moderate Risk", "industryDesc": "Non-specialised retail sale", "turnover": { "currency": "EUR", "value": 2298098 }, "employeeCount": "4", "shareholders": [ { "name": "Alessandro Moretti", "percentSharesHeld": 60 } ], "directors": [ { "name": "Giulia Romano", "positionName": "SOLE DIRECTOR" } ] } ] } ``` **Example 2 — RUOTA LIBERA DI CAGNAZZI MICHELE (Sole trader)** ```json { "kyb-prefill": [ { "tin": "BA123456", "vatNo": "12345678901", "name": "RUOTA VENEZIA DI CAGNAZZI MICHELE", "nameMatch": "Verified", "address": "HOUSE 123, STREET ABC, 72014 CISTERNINO BR", "city": "CISTERNINO", "postalCode": "72014", "entityType": "SOLE PROPRIETOR", "registrationStatus": "Active", "registrationDate": "2008-09-22T00:00:00Z", "industryDesc": "Other retail sale of new goods in specialised stores" } ] } ``` ### Response fields | Key | Value | Description | | --- | --- | --- | | tin | CCIAA/NREA number | The Italian Chamber of Commerce registration number as confirmed by the source of truth. | | vatNo | Partita IVA | The 11-digit Italian VAT number as returned from `alternateSummary.vatRegistrationNumber` in the source of truth. This field is reliable for all entity types, including sole traders, regardless of how the search was performed. | | name | Business name | The registered legal name of the business as returned from the source of truth. | | nameMatch | Verified, Approximate Match, Unverified | Match result comparing the submitted `businessName` against the name on file. Only present when `businessName` was submitted in the request. See Name and address match values for details. | | address | Registered address | The primary registered address of the business as returned from the source of truth. | | addressMatch | Verified, Approximate Match, Unverified | Match result comparing the submitted `address` against the registered address on file. Only present when `address` was submitted in the request. See Name and address match values for details. | | city | City | The city of the registered address as returned from the source of truth. | | postalCode | Postal code | The postal code of the registered address as returned from the source of truth. | | entityType | Entity type | The legal form of the business as returned from the source of truth (for example, `LIMITED LIABILITY COMPANY`, `SOLE PROPRIETOR`). Defaults to `Unknown` when not available. | | registrationStatus | Registration status | The current company status as returned from the source of truth (for example, `Active`). Defaults to `Unknown` when not available. | | registrationDate | Date | The date the company was incorporated (`incorporationDate`), as returned from the source of truth. May not be present for all companies. | | creditRating | Credit rating value | The standardized credit rating value (for example, `A`). Defaults to `Unknown` when not available. May not be present for sole traders. | | creditRatingDescription | Credit rating description | A human-readable description of the credit rating (for example, `Very Low Risk`). May not be present for sole traders. | | industryDesc | Industry description | The primary activity description as returned from the source of truth (for example, `Non-specialised retail sale`). | | activityDesc | Activity description | The principal activity description as returned from the source of truth. For Italy, this is typically identical to `industryDesc`. May not be present for all companies. | | turnover | `{currency, value}` object | The latest turnover figure as returned from the source of truth. May not be present for sole traders and smaller companies. | | employeeCount | String | The latest employee count as returned from the source of truth. Always returned as a string. May not be present for sole traders and smaller companies. | | companySize | String | The company size classification as returned from the source of truth (for example, `Small Company`). May not be present for all companies. | | shareholders | Array of `{name, percentSharesHeld}` | Shareholders associated with the business as returned from the source of truth. `percentSharesHeld` is sourced from `quotaPercentage` under `shareCapitalStructureExtra`. May not be present for sole traders. | | directors | Array of `{name, positionName}` | Current directors and officers as returned from the source of truth. `positionName` reflects the primary position title on file. May not be present for sole traders. | ### Name and address match values | Status | Description | | --- | --- | | Verified | Exact match found against registry data. | | Approximate Match | Similar match found; may reflect minor differences in naming or address formatting. | | Unverified | No match found in registry data. | ### Registration status values | Status | Description | | --- | --- | | Active | The company is currently active and registered. | | Inactive | The company registration is dissolved, struck off, or no longer active. | | Unknown | The registration status could not be determined. | ## Error responses For standard HTTP response codes, see the API Error Response page. Italy Prefill returns the following country-specific 400 errors. `taxId` is missing, empty, or does not match a supported Italian identifier format: ```json { "timestamp": 1782851408892, "status": 400, "error": "Bad Request", "message": "taxId must be a valid Italian identifier: CCIAA/NREA (2 letters + 6-7 digits), Partita IVA (11 digits), or Codice Fiscale (16 alphanumeric characters)", "path": "/omni/externalVerification/ekyb-prefill" } ``` Any mandatory field (`plugins`, `source`, `country`, or `taxId`) is missing: ```json { "timestamp": 1782851468367, "status": 400, "error": "Bad Request", "message": "must not be blank", "path": "/omni/externalVerification/ekyb-prefill" } ``` No business match is found for the submitted `taxId`: ```json { "timestamp": 1782851583695, "status": 200, "message": "No business found matching the provided tax ID.", "path": "/omni/externalVerification/ekyb-prefill" } ``` ## Single Session Dashboard results Prefill results are available on the Business tab in [Single Session view](/dashboard-platform-administration/single-session-view/).