company-v2Updated: 2025-12-08

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.

Search results

Legal form enumeration

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

Before:

{
  "legalForm": {
    "original": "ltd"
  }
}

After:

{
  "legalForm": {
    "original": "Limited Liability Company"
  }
}

Start date mapping

Search results now include the company's start date:

{
  "companies": [
    {
      "name": "EXAMPLE LIMITED",
      "startDate": {
        "original": "2020-01-15",
        "normalized": "2020-01-15"
      }
    }
  ]
}

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:

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

Legal form normalization

Legal form values now use proper capitalization:

Before:

{
  "legalForm": {
    "original": "ltd"
  }
}

After:

{
  "legalForm": {
    "original": "limited liability company"
  }
}

Legal status normalization

Legal status values now use title case:

Before:

{
  "status": {
    "normalized": "dissolved"
  }
}

After:

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

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

Unit nominal value

The capital array now includes unitNominalValue:

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

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

{
  "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 section above for details.

Unit nominal value

Capital entries now include the unit nominal value. See the Unit nominal value section above for details.

Additional resources