company-v1Updated: 2025-11-13

Enhanced UK Company Data – Director Information Improvements

Overview

This update enhances how UK company director information is delivered in V1 API responses. Director details are now sourced as structured data directly from Companies House, the official UK registry, rather than from documents. This change provides standardized, machine-readable information for better data quality and integration. Additionally, in line with UK data protection standards, director date of birth information now shows month and year only, providing enhanced privacy protection while maintaining data utility.

Technical details

Director information improvements

showDirectorships query parameter

The Enhanced Profile endpoint now supports an optional showDirectorships query parameter for UK companies (ISO code GB). When set to true, this parameter includes additional directorship information for each director, showing other companies where the director holds positions.

Usage

To retrieve director information including their other directorships, add the showDirectorships=true query parameter to your Enhanced Profile request:

# Enhanced Profile with directorships (V1)
curl -X GET "https://rest.kyckr.com/core/company/profile/GB/12345678?showDirectorships=true" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Accept: application/json"

Behavior

  • Default: When showDirectorships is not specified or set to false, the directorshipsField array for each director will be empty or omitted
  • When enabled: Setting showDirectorships=true populates the directorshipsField array for each director with their other company positions
  • Jurisdiction support: Currently supported for UK companies (ISO code GB) only

Example response

When showDirectorships=true is used, the directorshipsField array is populated for each director:

{
  "companyProfileField": {
    "directorAndShareDetailsField": {
      "directorsField": [
        {
          "directorNumberField": "123456780002",
          "titleField": "director",
          "nameField": "John Bloggs",
          "address1Field": "123 Example Street",
          "address2Field": "London",
          "address3Field": "",
          "postcodeField": "EC1A 1BB",
          "address4Field": "United Kingdom",
          "birthdateField": "1981-07",
          "nationalityField": "British",
          "directorshipsField": [
            {
              "companyNumberField": "12345678",
              "companyNameField": "EXAMPLE COMPANY LIMITED",
              "companyStatusField": "Active - Accounts Filed",
              "functionField": "director",
              "appointedDateField": "2023-07-17",
              "nationalityField": "British"
            },
            {
              "companyNumberField": "87654321",
              "companyNameField": "EXAMPLE SUBSIDIARY LIMITED",
              "companyStatusField": "Active - Accounts Filed",
              "functionField": "director",
              "appointedDateField": "2021-05-10",
              "nationalityField": "British"
            }
          ]
        }
      ]
    }
  }
}

Directorships array structure

Each entry in the directorshipsField array contains:

  • companyNumberField: The company registration number where the directorship is held
  • companyNameField: The name of the company where the directorship is held
  • companyStatusField: The current status of the company (e.g., "Active - Accounts Filed")
  • functionField: The position/role held (typically "director")
  • appointedDateField: When the directorship began (date format)
  • nationalityField: The nationality of the director in this directorship

Enumeration value changes

Several enumeration values have changed using Companies House data dictionaries to improve readability.

Legal Form (legalFormField)

Legal form values now use full descriptive text instead of abbreviated codes:

Before:

{
  "legalFormField": "private-unlimited"
}

After:

{
  "legalFormField": "Private unlimited company"
}

Common legal form mappings include:

  • private-unlimited → "Private unlimited company"
  • ltd → "Private limited company"
  • plc → "Public limited company"
  • llp → "Limited liability partnership"
  • old-public-company → "Old public company"

For a complete list of legal form enumerations, see the Companies House API enumerations.

Director Title (titleField)

Before:

{
  "titleField": "Company Secretary"
}

After:

{
  "titleField": "Secretary"
}

For a complete list of officer role enumerations, see the Companies House API enumerations.

Birthdate Format Changes (birthdateField)

The birthdate field format has changed to comply with UK data protection standards and ISO 8601 requirements:

Before:

{
  "birthdateField": "01/07/1981"
}

After:

{
  "birthdateField": "1981-07"
}

The format changed from DD/MM/YYYY (e.g., "15/07/1981") to YYYY-MM (e.g., "1981-07"), showing only year and month in ISO 8601 compliant format. This normalization is applied when Companies House provides only month and year information (e.g., "7 1981"), ensuring consistent, machine-readable date formats.

New and enhanced fields

This update introduces several new fields and enhancements to the Enhanced Profile response for UK companies:

Last Annual Account Date

The lastAnnualAccountDateField provides the date when the last annual accounts were filed with Companies House:

{
  "companyProfileField": {
    "lastAnnualAccountDateField": "2024-12-31"
  }
}

Additional resources