company-v1Updated: 2025-12-12

Enhanced UK Company Data – Director Information Improvements

Overview

We've enhanced how we deliver UK company director information in V1 API responses.

We now source director details as structured data directly from Companies House, the official UK registry. Previously, we extracted this data from documents. This gives you more reliable, consistent information that's easier to integrate.

In line with UK data protection standards, director dates of birth now show month and year only. This provides enhanced privacy protection while maintaining data utility.

Key changes

showDirectorships query parameter

You can now retrieve additional directorship information for UK company directors. This shows you other companies where each director holds positions.

Usage

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"

How it works

  • Default: When you don't specify showDirectorships or set it to false, the directorshipsField array is empty or omitted
  • When enabled: Setting showDirectorships=true populates the directorshipsField array with each director's other company positions
  • Availability: Currently supported for UK companies (ISO code GB) only

Example response

When you use showDirectorships=true, the API populates the directorshipsField array:

{
  "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 directorship includes:

  • companyNumberField – Registration number
  • companyNameField – Company name
  • companyStatusField – Current status (for example, "Active - Accounts Filed")
  • functionField – Position held
  • appointedDateField – When the directorship began
  • nationalityField – Director's nationality

Enumeration value changes

We've updated several enumeration values using Companies House data dictionaries. This improves readability and aligns with the official registry terminology.

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:

  • 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.

Ultimate beneficial owners nature of control (personsOfSignificantControlField[].natureOfControlField[])

Nature of control descriptions are now more detailed and standardized:

Before:

{
  "natureOfControlField": [
    "Has significant influence or control"
  ]
}

After:

{
  "natureOfControlField": [
    "The person has the right to exercise, or actually exercises, significant influence or control over the company."
  ]
}

We map these descriptions from Companies House PSC descriptions. For a complete list, see the Companies House PSC descriptions.

Birthdate format (birthdateField)

The birthdateField now uses ISO-8601 format and supports partial dates when the source doesn't provide a complete birth date.

Before:

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

After:

{
  "birthdateField": "1981-07"
}

Changes:

  • birthdateField uses ISO-8601 format supporting both full dates (YYYY-MM-DD) and partial dates (YYYY-MM). For UK directors, you'll get month and year only (for example, "1981-07").

New fields

Last annual account date

You'll now get the date when the last annual accounts were filed with Companies House:

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

Additional resources