# Corporate KYC Intelligence (LEI ownership & risk) (`hllerdgn80/corporate-kyc-intelligence`) Actor

Look up any company's GLEIF Legal Entity Identifier (LEI) record and get its full ownership tree (direct/ultimate parent, direct children) plus a registration-status compliance flag (LAPSED/RETIRED). Uses only GLEIF's free, keyless, official API.

- **URL**: https://apify.com/hllerdgn80/corporate-kyc-intelligence.md
- **Developed by:** [Halil Erdogan](https://apify.com/hllerdgn80) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.01 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Corporate KYC Intelligence — LEI ownership tree & compliance risk

Give it a company name or LEI code and get back its official Legal Entity
Identifier (LEI) record, its registration health, and its full corporate
ownership tree — direct parent, ultimate parent, and direct subsidiaries —
in one request. Built for KYC analysts, compliance and supplier-risk teams,
and anyone who needs to answer "who actually owns this company, and is its
official registration in good standing?" without opening five different
sites by hand.

### What it does

For each company you give it (a legal name or a 20-character LEI code) it
returns:

- the GLEIF LEI record: legal name, jurisdiction, legal form, registered and
  headquarters address, entity status
- **registration status** — `ISSUED` (current), `LAPSED` or `RETIRED`. A
  lapsed/retired LEI means the company stopped renewing its own official
  identifier — a real, independent compliance red flag banks and auditors
  watch for, separate from any news event
- **the ownership tree in one request**: direct parent, ultimate parent
  (with their own LEI, name, jurisdiction and registration status), and up
  to `childrenLimit` direct subsidiaries
- `compliance_risk_flags`: a plain list such as `LEI_REGISTRATION_LAPSED`,
  `ENTITY_STATUS_INACTIVE`, `DIRECT_PARENT_NOT_DISCLOSED` — so you can filter
  a batch straight to the companies worth a second look
- optionally, an OpenCorporates enrichment block (company number,
  incorporation date, current status) — only if you supply your **own**
  OpenCorporates API token

### Why this and not the other OpenCorporates-style Actors

Most Actors in this niche wrap OpenCorporates search, which as of September
2026 requires a paid API token even for a plain company search (OpenCorporates
now rejects unauthenticated requests outright — verified live: `{"error":
{"message":"Invalid Api Token..."}}`). This Actor is built primarily on
**GLEIF's own LEI database instead** — the international regulator-run
registry of Legal Entity Identifiers, covering 2.7M+ companies worldwide,
with a **completely free, keyless, official REST API**
(https://www.gleif.org/en/lei-data/gleif-api).

The distinguishing feature: **the full ownership tree in a single Actor
run** — direct parent, ultimate parent AND direct subsidiaries together,
plus the registration-status compliance flag. Existing OpenCorporates-based
Actors return one company's own filing data; GLEIF's relationship data
(who owns whom) needs three separate endpoint calls per company, which this
Actor already handles for you, batched and throttled.

### How to use it

1. Put company names or LEI codes in **Companies**, one per line.
2. Leave **Include ownership tree** on (default) to get direct/ultimate
   parent and direct subsidiaries for free — no extra charge.
3. If a name matches more than one company (e.g. "Deutsche Bank" — dozens
   of legal entities share that brand name), the row comes back with
   `status: "ambiguous"` and a `match_candidates` list of every LEI/name/
   jurisdiction GLEIF found; re-run with the exact legal name, the LEI code,
   or set **Limit name search to jurisdiction**.
4. Sort the resulting dataset by `compliance_risk_flags` to see which
   companies have a lapsed registration or an undisclosed parent.

### Sample output

```json
{
  "input": "Lehman Brothers Limited",
  "status": "ok",
  "lei": "213800Q7NV3T5PZOU403",
  "legal_name": "LEHMAN BROTHERS LIMITED",
  "jurisdiction": "GB",
  "entity_status": "ACTIVE",
  "registration_status": "LAPSED",
  "registration_next_renewal": "2025-12-20T00:00:00Z",
  "direct_parent": {"relationship": "direct-parent", "disclosed": false, "reason": "NO_KNOWN_PERSON"},
  "ultimate_parent": {"relationship": "ultimate-parent", "disclosed": false, "reason": "NO_KNOWN_PERSON"},
  "direct_children": {"count_returned": 0, "children": [], "truncated": false},
  "compliance_risk_flags": ["LEI_REGISTRATION_LAPSED"],
  "opencorporates": null,
  "gleif_record_url": "https://search.gleif.org/#/record/213800Q7NV3T5PZOU403",
  "fetched_at": "2026-09-27T12:00:00+00:00",
  "error": null
}
```

A company with a live ownership tree (`apps: ["Google Ireland Limited"]`):

```json
{
  "legal_name": "GOOGLE IRELAND LIMITED",
  "registration_status": "ISSUED",
  "direct_parent": {"relationship": "direct-parent", "lei": "5493...", "legal_name": "GOOGLE INTERNATIONAL LLC"},
  "ultimate_parent": {"relationship": "ultimate-parent", "lei": "5493006MHB84DD0ZWV18", "legal_name": "ALPHABET INC."},
  "compliance_risk_flags": []
}
```

### What this Actor does NOT do (honest scope)

- **It is not a beneficial-ownership / UBO register.** GLEIF's parent data is
  the *corporate accounting-consolidation parent* an entity itself reports —
  it is authoritative for "which company owns this company" but is not the
  same as a natural-person beneficial-ownership disclosure (some
  jurisdictions' UBO registers are not public data at all, so no Actor can
  honestly promise that).
- **No officers, directors or filing documents.** That is OpenCorporates
  territory, and OpenCorporates' free tier no longer allows it (see above).
  If you have your own OpenCorporates API token, paste it in
  `opencorporatesApiToken` and the Actor adds company number, incorporation
  date and current status per company — this is clearly labelled as an
  optional, user-supplied-token enrichment, never invented data.
- **A name search can be ambiguous.** Common brand names (banks, "Deutsche
  Bank", "HSBC") map to dozens of separate legal entities in GLEIF. The
  Actor never silently guesses — it returns `status: "ambiguous"` with every
  candidate so you can pick the right one, instead of quietly returning the
  wrong company's data.
- **No sanctions/PEP screening.** This Actor only reads GLEIF's LEI registry
  (and, optionally, OpenCorporates). It is not an OFAC/sanctions list check.

### Data source

- GLEIF LEI API — https://www.gleif.org/en/lei-data/gleif-api — free,
  keyless, official, covers every LEI ever issued worldwide including
  lapsed/retired ones.
- OpenCorporates API — https://api.opencorporates.com — official, but as of
  27 September 2026 requires your own paid API token even for search; used
  only if you supply one.

No scraping, no login walls bypassed, no paid API called without your own
key.

# Actor input Schema

## `companies` (type: `array`):

One per line: a company legal name (e.g. Google Ireland Limited) or a 20-character LEI code (e.g. HWUPKR0MPOU8FGXBT394). Duplicates are removed.

## `companiesText` (type: `string`):

Paste many companies at once: one per line (commas and semicolons also separate entries). Combined with the list above.

## `jurisdiction` (type: `string`):

Two-letter country code, e.g. GB, US, DE. Only used when searching by name (not by LEI) and only when a company name matches several entities — narrows the match. Leave empty to search worldwide.

## `includeHierarchy` (type: `boolean`):

The Actor's core feature: for each company, also fetches its direct parent, ultimate parent, and up to 'Children per company' direct subsidiaries from GLEIF's official relationship data — free, no extra charge. Turn off for a faster run if you only need the base record.

## `childrenLimit` (type: `integer`):

Maximum number of direct subsidiaries to return per company (GLEIF paginates; most companies have few or none). Capped at 100 to keep runs predictable.

## `opencorporatesApiToken` (type: `string`):

OpenCorporates' free tier is rate-limited and most useful fields (officers, filings) need a paid token. If you paste your own OpenCorporates API token here, the Actor adds an 'opencorporates' enrichment block per company (company number, incorporation date, current status, source URL) using OpenCorporates' official /companies/search endpoint. Leave empty to skip — GLEIF data alone still gives the full ownership tree and compliance flag.

## `maxConcurrency` (type: `integer`):

How many companies to look up in parallel.

## Actor input object example

```json
{
  "companies": [
    "Apple Inc",
    "Google Ireland Limited",
    "Lehman Brothers Limited"
  ],
  "includeHierarchy": true,
  "childrenLimit": 25,
  "maxConcurrency": 5
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "companies": [
        "Apple Inc",
        "Google Ireland Limited",
        "Lehman Brothers Limited"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("hllerdgn80/corporate-kyc-intelligence").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "companies": [
        "Apple Inc",
        "Google Ireland Limited",
        "Lehman Brothers Limited",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("hllerdgn80/corporate-kyc-intelligence").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "companies": [
    "Apple Inc",
    "Google Ireland Limited",
    "Lehman Brothers Limited"
  ]
}' |
apify call hllerdgn80/corporate-kyc-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,hllerdgn80/corporate-kyc-intelligence"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Z9Uf2Uxz2JiSoguXA/builds/TA9JF8lIUKe4mXyib/openapi.json