March 2025

Overview

This update changes how Italian company identifiers are structured in API responses, transitioning from using Codice Fiscale (a non-unique national identifier for companies) to using provincial registry numbers (REA - Repertorio Economico Amministrativo). For developers following best practices by using the search response data for subsequent API calls, this change should be transparent and require no code modifications. However, systems that directly store or process company identifiers will need to be updated to handle the new format.

⚠️ Important note on codice fiscale

The codice fiscale is not unique and may be shared by related companies. For this reason, all profile purchases (Lite and Enhanced) should use the REA identifier from the search response's codeField. The REA number provides a unique identifier for each company. Lite and Enhanced orders using the Codice Fiscale may fail, and filing searches are not supported.

Italy company identifiers

Key changes

• Search Response: Modified the codeField to use the REA number (IT_REA_CD)
• Lite Profile: Updated company identifier fields to reflect the REA identification system
• Enhanced Profile: Adjusted identifier structure to maintain consistency with search and lite profile changes
• API Calls: Updated all API endpoints to use the new REA identifier format

Technical details

Search methods

The Company Search API supports three methods for searching Italian companies:

1. Name Search: Search by company name
2. REA: Search using the REA number (IT_REA_CD)
3. Codice Fiscale: Search using the national tax number (IT_TAX_CD) - may return multiple entity matches

Response field changes

V1 API

The search response fields have been updated to support the new REA identification system:

• codeField: Now contains the REA (IT_REA_CD) format
• registrationNumberField: Now contains the REA (IT_REA_CD) format
• registrationAuthorityCodeField: Contains the province code (e.g., "MI")
• otherIdentifiers: [Future] For Lite and Enhanced only, new array containing standardized secondary identifiers with their type codes

Example responses

Search response

Before:

{
    "companiesField": [{
      "codeField": "12345678901",
      "companyIDField": "123456",
      "nameField": "ACME Trading S.R.L.",
      "registrationAuthorityField": "MILANO",
      "registrationAuthorityCodeField": "MI"
    }]
}

After:

{
    "companiesField": [{
      "codeField": "MI123456",
      "companyIDField": "MI123456",
      "nameField": "ACME Trading S.R.L.",
      "registrationAuthorityField": "MILANO",
      "registrationAuthorityCodeField": "MI",
      "registrationNumberField": "MI123456"
    }]
}

Lite Profile

Before:

{
  "companyProfileField": {
    "codeField": "12345678901",
    "registrationNumberField": "123456",
    "nameField": "ACME Trading S.R.L.",
    "registrationAuthorityField": "MILANO"
  }
}

After:

{
  "companyProfileField": {
    "codeField": "MI123456",
    "nameField": "ACME Trading S.R.L.",
    "registrationAuthorityField": "MILANO",
    "registrationNumberField": "MI123456",
    "otherIdentifiers": [
      { "type": "IT_TAX_CD", "value": "12345678901" }
    ]
  }
}

Enhanced Profile

Before:

{
  "companyProfileField": {
    "codeField": "12345678901",
    "registrationNumberField": "MI123456"
  }
}

After:

{
  "companyProfileField": {
    "codeField": "MI123456",
    "registrationNumberField": "MI123456",
    "otherIdentifiers": [
      { "type": "IT_TAX_CD", "value": "12345678901" }
    ]
  }
}

API call examples

When making subsequent API calls, use the data from the search response:

• Use the codeField value as the company identifier in the URL
• Use the registrationAuthorityCodeField value as the RegAuth query parameter

For example, given this search response:

{
    "companiesField": [{
      "codeField": "MI123456",
      "registrationAuthorityCodeField": "MI",
      "registrationNumberField": "MI123456"
    }]
}

You would construct subsequent API calls using these values:

• codeField ("MI123456") becomes the company identifier in the URL
• registrationAuthorityCodeField ("MI") becomes the RegAuth parameter

Lite Profile

Lite Profile ordering changes from IT_TAX_CD to IT_REA_CD

Before:

https://rest.kyckr.com/lite/profile/IT/12345678901?RegAuth=MI

After:

https://rest.kyckr.com/lite/profile/IT/MI123456?RegAuth=MI

Enhanced Profile

Enhanced Profile ordering changes from IT_TAX_CD to IT_REA_CD

Before:

https://rest.kyckr.com/core/company/profile/IT/12345678901?RegAuth=MI

After:

https://rest.kyckr.com/core/company/profile/IT/MI123456?RegAuth=MI

Filings Search

Filing Search changes from IT_TAX_CD to IT_REA_CD

Before:

https://rest.kyckr.com/core/filing/search/IT/12345678901?RegAuth=MI

After:

https://rest.kyckr.com/core/filing/search/IT/MI123456?RegAuth=MI

Migration guide

⚠️ Required updates

1. Update search result processing to expect REA identifiers in the codeField
2. Modify systems that store company identifiers
3. Update API calls:
   • Use the REA identifier from the search response's codeField for ALL profile purchases
   • Include the RegAuth parameter (while optional for Italian companies, this is recommended practice)
   • IMPORTANT: Do not use Codice Fiscale for profile purchases as it may not uniquely identify a company
4. [Future] Update identifier handling:
   • Use the future otherIdentifiers array to access standardized identifiers
   • Use the appropriate type codes (IT_REA_CD, IT_VAT_CD, IT_TAX_CD) to identify different identifier types
   • Note: The REA number is the primary identifier, with fiscal code and VAT number to be provided in the otherIdentifiers array

⚠️ Impact assessment

• This change primarily affects systems that:
  • Store Italian company identifiers
  • Make direct API calls without using search response data
  • Rely on Codice Fiscale as primary identifiers
  • Use Codice Fiscale for search - this may return multiple entity matches
  • Use Codice Fiscale for profile purchases (must be updated to use REA numbers)
• Systems already using search response data to make subsequent API calls should require minimal changes

Italian province code reference

The following is a complete map of Italian province codes used in the REA number format. Each province has its own Chamber of Commerce (CCIA) that maintains a register of companies within its jurisdiction: