company-v2Updated: 2025-12-12

Enhanced UK Company Data – Director Information Improvements

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.

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

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

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

{
  "legalForm": {
    "original": "private-unlimited"
  }
}

After:

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

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

Before:

{
  "role": {
    "original": "Company Secretary"
  }
}

After:

{
  "role": {
    "original": "Secretary"
  }
}

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

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

Nature of control descriptions are now more detailed and standardized:

Before:

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

After:

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

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:

{
  "birthdate": {
    "original": "7 1981",
    "normalized": "1981-07-01"
  }
}

After:

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

{
  "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):

{
  "data": {
    "activities": [
      {
        "code": "64191",
        "description": "Banks",
        "classificationScheme": "SIC07",
        "type": "Primary"
      }
    ]
  }
}

Capital shareholdings voting rights

Share capital now includes voting rights information:

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

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

Additional resources