> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kyckr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enhanced UK Company Data – Director Information Improvements

> UK company director information now sourced directly from Companies House with improved V2 data quality, directorships lookup, and privacy-compliant birthdate handling.

## Overview

We've enhanced how we deliver UK company director information in both V1 and V2 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:**

```json theme={null}
{
  "legalForm": {
    "original": "ltd"
  }
}
```

**After:**

```json theme={null}
{
  "legalForm": {
    "original": "Limited Liability Company"
  }
}
```

### Start date mapping

Search results now include the company's start date:

```json theme={null}
{
  "companies": [
    {
      "name": "EXAMPLE LIMITED",
      "startDate": {
        "original": "2020-01-15",
        "normalized": "2020-01-15"
      }
    }
  ]
}
```

## Filing search (documents) pagination

For GB companies, the Documents endpoint returns a list of available filings from Companies House:

```
GET https://api.kyckr.com/v2/companies/GB|MDA0NDU3OTA=/documents
```

The response may include a **continuationKey** (a base64-style opaque value). When present, there are more filings than fit in one page (e.g. the first 100).

To fetch the next page, call the same endpoint and pass the returned value as the **continuationKey** query parameter:

```
GET https://api.kyckr.com/v2/companies/GB|MDA0NDU3OTA=/documents?continuationKey=eyJJdGVtc1BlclBhZ2UiOjEwMCwiU3RhcnRJbmRleCI6MTAwfQ==
```

Each response returns a different set of filings (the next page). Repeat the request with the new `continuationKey` from each response until the response no longer includes a `continuationKey` (or it is null or empty), indicating all pages have been retrieved.

Use the exact field name **continuationKey** in both the response and the query parameter.

## Lite profile changes

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

### Classification scheme

The `classificationScheme` field is now populated in the activities array:

```json theme={null}
{
  "data": {
    "activities": [
      {
        "code": "64191",
        "description": "Banks",
        "classificationScheme": "SIC07"
      }
    ]
  }
}
```

### Legal form normalization

Legal form values now use proper capitalization:

**Before:**

```json theme={null}
{
  "legalForm": {
    "original": "ltd"
  }
}
```

**After:**

```json theme={null}
{
  "legalForm": {
    "original": "limited liability company"
  }
}
```

### Legal status normalization

Legal status values now use title case:

**Before:**

```json theme={null}
{
  "status": {
    "normalized": "dissolved"
  }
}
```

**After:**

```json theme={null}
{
  "status": {
    "normalized": "Dissolved"
  }
}
```

## 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:

```bash theme={null}
# Enhanced Profile with directorships (V2)
curl -X GET "https://api.kyckr.com/v2/companies/GB|MTEyMzQ1Ng==/enhanced?showDirectorships=true" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

#### How it works

* **Default**: When you don't specify `showDirectorships` or set it to `false`, the `directorships` array is empty or omitted
* **When enabled**: Setting `showDirectorships=true` populates the `directorships` 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 `directorships` array:

```json theme={null}
{
  "data": {
    "representatives": {
      "individuals": [
        {
          "role": {
            "original": "director"
          },
          "startDate": {
            "original": "2023-07-17",
            "normalized": "2023-07-17"
          },
          "birthdate": {
            "original": "7 1981",
            "normalized": "1981-07"
          },
          "nationality": "British",
          "name": "John Bloggs",
          "placeOfResidence": {
            "fullAddress": "123 Example Street, London, EC1A 1BB",
            "buildingName": "123 Example Street",
            "municipality": "London",
            "postcode": "EC1A 1BB"
          },
          "type": "Person",
          "directorships": [
            {
              "companyNumber": "12345678",
              "companyName": "EXAMPLE COMPANY LIMITED",
              "role": "director",
              "startDate": {
                "original": "2023-07-17",
                "normalized": "2023-07-17"
              },
              "isActive": true
            },
            {
              "companyNumber": "87654321",
              "companyName": "EXAMPLE SUBSIDIARY LIMITED",
              "role": "director",
              "startDate": {
                "original": "2021-05-10",
                "normalized": "2021-05-10"
              },
              "isActive": true
            }
          ]
        }
      ]
    }
  }
}
```

#### Directorships array structure

Each directorship includes:

* `companyNumber` – Registration number
* `companyName` – Company name
* `role` – Position held
* `startDate` – When the directorship began
* `endDate` – When it ended (if applicable)
* `isActive` – Whether the directorship is currently active

### Bug fix – Individual company secretaries mapping

We've fixed how individual company secretaries appear in the response. They now appear correctly in the `representatives.individuals` array with `type: "Person"`.

#### Example

```json theme={null}
{
  "data": {
    "representatives": {
      "individuals": [
        {
          "role": {
            "original": "secretary"
          },
          "startDate": {
            "original": "2024-10-18",
            "normalized": "2024-10-18"
          },
          "isActive": true,
          "type": "Person",
          "idNumber": "123456780001",
          "name": "Jane Smith",
          "placeOfResidence": {
            "fullAddress": "456 Example Road, London, WC1A 1AA",
            "buildingName": "456 Example Road",
            "streetName": "London",
            "postcode": "WC1A 1AA"
          }
        }
      ]
    }
  }
}
```

### 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 (`legalForm.original`)

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

**Before:**

```json theme={null}
{
  "legalForm": {
    "original": "private-unlimited"
  }
}
```

**After:**

```json theme={null}
{
  "legalForm": {
    "original": "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](https://github.com/companieshouse/api-enumerations/blob/master/constants.yml).

#### Representative role (`representatives.individuals[].role.original`)

**Before:**

```json theme={null}
{
  "role": {
    "original": "Company Secretary"
  }
}
```

**After:**

```json theme={null}
{
  "role": {
    "original": "Secretary"
  }
}
```

For a complete list of officer role enumerations, see the [Companies House API enumerations](https://github.com/companieshouse/api-enumerations/blob/master/constants.yml).

#### Ultimate beneficial owners nature of control (`ultimateBeneficialOwners.individuals[].natureOfControl[]`)

Nature of control descriptions are now more detailed and standardized:

**Before:**

```json theme={null}
{
  "natureOfControl": [
    "Has significant influence or control"
  ]
}
```

**After:**

```json theme={null}
{
  "natureOfControl": [
    "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](https://github.com/companieshouse/api-enumerations/blob/master/psc_descriptions.yml).

#### Birthdate format (`representatives.individuals[].birthdate`)

We've updated how we handle birthdates to support partial dates when the source doesn't provide a complete birth date.

The `normalized` field uses ISO-8601 format and supports both full dates (YYYY-MM-DD) and partial dates (YYYY-MM) when only month and year are available.

**Before:**

```json theme={null}
{
  "birthdate": {
    "original": "7 1981",
    "normalized": "1981-07-01"
  }
}
```

**After:**

```json theme={null}
{
  "birthdate": {
    "original": "7 1981",
    "normalized": "1981-07"
  }
}
```

Changes:

* **`birthdate.original`** – Format from Companies House (for example, `"7 1981"` for month and year only)
* **`birthdate.normalized`** – Now supports ISO-8601 format with precision matching the registry source. 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:

```json theme={null}
{
  "data": {
    "lastAnnualAccountDate": {
      "original": "2024-12-31",
      "normalized": "2024-12-31"
    }
  }
}
```

#### Activity classification scheme

The `activities` array now includes a `classificationScheme` field. This tells you which classification system the activity code uses (for example, SIC07, NACE, or NAICS):

```json theme={null}
{
  "data": {
    "activities": [
      {
        "code": "64191",
        "description": "Banks",
        "classificationScheme": "SIC07",
        "type": "Primary"
      }
    ]
  }
}
```

#### Capital shareholdings voting rights

Share capital now includes voting rights information:

```json theme={null}
{
  "data": {
    "capital": [
      {
        "classCode": "ORDINARY",
        "classDescription": "ORDINARY",
        "shareholdings": [
          {
            "percentage": "100.00",
            "votingRights": "Yes"
          }
        ]
      }
    ]
  }
}
```

#### Ultimate beneficial owners kind

Corporate beneficial owners now include a `kind` field that indicates the type of beneficial ownership entity:

```json theme={null}
{
  "data": {
    "ultimateBeneficialOwners": {
      "corporations": [
        {
          "kind": "corporate-entity-person-with-significant-control",
          "natureOfControl": [
            "The person holds, directly or indirectly, more than 75% of the shares in the company.",
            "The person holds, directly or indirectly, more than 75% of the voting rights in the company."
          ],
          "name": "EXAMPLE HOLDINGS PLC"
        }
      ]
    }
  }
}
```

#### Unit nominal value

The capital array now includes `unitNominalValue`:

```json theme={null}
{
  "data": {
    "capital": [
      {
        "classCode": "ORDINARY",
        "classDescription": "ORDINARY",
        "unitNominalValue": "1.00",
        "shareholdings": [
          {
            "percentage": "100.00",
            "votingRights": "Yes"
          }
        ]
      }
    ]
  }
}
```

#### Ultimate and immediate parent

The `representatives.corporations` array now includes ultimate parent and immediate parent information. Parent entries are identified by their `role.original` value:

```json theme={null}
{
  "data": {
    "representatives": {
      "corporations": [
        {
          "role": {
            "original": "Ultimate Parent"
          },
          "isActive": true,
          "registrationNumber": "98765432",
          "registeredAddress": {
            "fullAddress": "100 Example Street, London",
            "country": "GB"
          },
          "type": "Corporation",
          "name": "PARENT HOLDINGS PLC"
        },
        {
          "role": {
            "original": "Immediate Parent"
          },
          "isActive": true,
          "registrationNumber": "11223344",
          "registeredAddress": {
            "fullAddress": "50 Business Park, Manchester",
            "country": "GB"
          },
          "type": "Corporation",
          "name": "INTERMEDIATE HOLDINGS LTD"
        }
      ]
    }
  }
}
```

Parent entries include:

* `role.original` – Either "Ultimate Parent" or "Immediate Parent"
* `isActive` – Whether the parent relationship is currently active
* `registrationNumber` – Registration number of the parent company
* `registeredAddress` – Address details including `fullAddress` and `country`
* `type` – Always "Corporation" for parent companies
* `name` – Parent company name

## Shareholder changes

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

### Corporation registration number

Corporate shareholders now include a `registrationNumber` field:

```json theme={null}
{
  "data": {
    "shareholders": [
      {
        "type": "Corporation",
        "name": "EXAMPLE HOLDINGS PLC",
        "registrationNumber": "98765432",
        "percentage": "75.00"
      }
    ]
  }
}
```

### Voting rights

Share capital now includes voting rights information for each shareholding. See the [Capital shareholdings voting rights](#capital-shareholdings-voting-rights) section above for details.

### Unit nominal value

Capital entries now include the unit nominal value. See the [Unit nominal value](#unit-nominal-value) section above for details.

## Additional resources

* [Enhanced Profile Documentation](/documentation/features/perform-a-kyb-check-v2)
* [Companies House Official Website](https://www.gov.uk/government/organisations/companies-house)