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.

Search results

Legal form enumeration

Legal form values in search results now use full descriptive text:

Before:

{
  "legalFormField": "ltd"
}

After:

{
  "legalFormField": "Limited Liability Company"
}

Lite profile changes

We've made several improvements to the Lite Profile response for UK companies.

Cleaner response structure

Nullable fields are now removed from the Lite profile response, making the data cleaner and easier to process.

Status normalization

The normalized status field now uses title case for consistency:

Before:

{
  "statusField": {
    "normalizedField": "INACTIVE"
  }
}

After:

{
  "statusField": {
    "normalizedField": "Inactive"
  }
}

Registration date and number fields

The registrationDateField is now populated with the same date as the foundation date, and registrationNumberField is populated with the company number:

{
  "companyProfileField": {
    "registrationDateField": "2020-01-15",
    "registrationNumberField": "12345678",
    "foundationDateField": "2020-01-15"
  }
}

Retrieval location field removed

The retrievalLocationField has been removed from responses as it was not providing meaningful data.

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").

Enhanced profile improvements

Registration number field

The registrationNumberField is now populated in the Enhanced Profile response:

{
  "companyProfileField": {
    "registrationNumberField": "12345678"
  }
}

Director number field

The directorNumberField is now populated for each director:

{
  "directorsField": [
    {
      "directorNumberField": "123456780002",
      "nameField": "John Bloggs"
    }
  ]
}

Cleaner director address response

Nullable director address fields are now removed from the Enhanced Profile response, making the data cleaner and easier to process.

Capital type code field

The capital array now includes a typeCodeField:

{
  "capitalField": [
    {
      "typeCodeField": "ORDINARY",
      "shareClassField": "Ordinary",
      "totalSharesCountField": "100"
    }
  ]
}

allInfoField removed

The allInfoField has been removed from responses as it was redundant.

Ultimate and immediate parent

The directorsField array now includes ultimate and immediate parent company information. Parent entries are identified by their titleField value:

{
  "directorAndShareDetailsField": {
    "directorsField": [
      {
        "directorNumberField": "98765432",
        "titleField": "Ultimate Parent",
        "nameField": "PARENT HOLDINGS PLC",
        "address1Field": "100 Example Street, London",
        "address2Field": "GB"
      },
      {
        "directorNumberField": "11223344",
        "titleField": "Immediate Parent",
        "nameField": "INTERMEDIATE HOLDINGS LTD",
        "address1Field": "50 Business Park, Manchester",
        "address2Field": "GB"
      }
    ]
  }
}

Parent entries include:

• directorNumberField – Registration number of the parent company
• titleField – Either "Ultimate Parent" or "Immediate Parent"
• nameField – Parent company name
• address1Field – Registered address
• address2Field – Country code

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"
  }
}

Shareholder changes

We've improved how shareholder information is returned in the Enhanced Profile.

Percentage format

The percentageField now uses a consistent decimal format:

Before:

{
  "percentageField": "50"
}

After:

{
  "percentageField": "50.00"
}

Shareholder type values

The shareholderTypeField now uses descriptive values instead of abbreviations:

Before:

{
  "shareholderTypeField": "P"
}

After:

{
  "shareholderTypeField": "Person"
}

Mappings:

• P → Person
• C → Corporation

Share class field

The shareClassField is now populated:

{
  "shareholdersField": [
    {
      "shareClassField": "Ordinary",
      "shareholderTypeField": "Person",
      "percentageField": "50.00"
    }
  ]
}

Nominal value format

The nominalValueField now uses a consistent decimal format:

Before:

{
  "nominalValueField": "1"
}

After:

{
  "nominalValueField": "1.0"
}

totalSharesField removed

The totalSharesField has been removed to eliminate duplication. Use totalSharesCountField instead, which provides the same information.

Additional resources

• Company V1 API Reference
• Enhanced Profile Documentation
• Companies House Official Website