# GLEIF LEI Lookup & Entity Change Monitor (`luminar/gleif-lei-change-monitor`) Actor

Look up official GLEIF legal entities and track renewal, status, published parent, subsidiary, successor, predecessor, and relationship changes.

- **URL**: https://apify.com/luminar/gleif-lei-change-monitor.md
- **Developed by:** [Luka](https://apify.com/luminar) (community)
- **Categories:** Automation, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.64 / 1,000 baseline lei entities

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

Assess official GLEIF Legal Entity Identifier records with identity-match evidence, renewal posture, human-readable reference codes, published parent context, source-data quality, and an explainable review priority. Search by company or LEI, export a bounded country registry, and use the same Actor to track verified company, renewal, status, relationship, successor, and predecessor changes over time.

Enter one exact LEI for the strongest match or search registered company names in a batch. Every signal is derived from official GLEIF data; the Actor does not add sanctions, adverse-media, beneficial-ownership, or black-box risk claims.

### 🚀 Start in 60 seconds

1. Choose **Assess current companies**.
2. Enter one exact LEI or one or more registered company names.
3. Keep the Standard result for the complete entity assessment.
4. Click **Start** and open the Dataset and Portfolio review summary.

```json
{
  "mode": "baseline",
  "leis": ["529900T8BM49AURSDO55"]
}
```

The default returns up to 5 company records, includes published direct/ultimate parent context and resolved legal-form/registration-authority names, limits separate relationship records to 20, and stops before a projected $0.25 Actor charge.

### 🎯 Choose the right workflow

| Workflow | Use it for | Result |
|---|---|---|
| **Assess current companies** | Vendor onboarding input, counterparty review, entity resolution, renewal checks, or portfolio triage | Current enriched company rows, optional relationship rows, and a portfolio summary |
| **Track verified changes** | Repeat checks for status, renewal, entity facts, published parents, successors, predecessors, and other relationships | Deterministic `NEW`, `UPDATED`, or safely confirmed `ENDED` records plus typed business events |

For a country registry export, leave LEIs and company names empty and add one or more ISO two-letter codes in `countries`. The Actor pages through official GLEIF results up to `maxEntities`; reaching that limit is reported as `CAPPED`, never as complete country coverage.

The first run in Track verified changes creates the comparison snapshot and normally returns no change records. For repeat runs, keep the same targets, filters and enrichment options, and finish one same-scope run before starting the next. Use `maxTrackedItems` to cap the combined company and relationship snapshot and the changes delivered by one run; the Actor accepts up to 200 tracked items.

### 📦 What you get

Each Standard company result contains:

- LEI, legal and other names, status, category, jurisdiction, addresses, registration dates, managing LOU, BICs, and local registry number.
- Human-readable legal-form and registration-authority names resolved through official GLEIF reference endpoints.
- `identityConfidence`, `identityVerdict`, and `matchingEvidence` for an exact LEI, company name, country, and optional expected registration number.
- `renewalStatus`, `daysUntilRenewal`, `recordFreshness`, official conformity evidence, and source-data quality.
- Published direct/ultimate parent basics or official reporting exceptions, with an explicit relationship-evidence state that never infers beneficial ownership.
- `reviewPriority`, `recommendedNextStep`, `reviewFlags`, and a complete `decisionPath` derived only from the returned GLEIF facts.
- Optional subsidiary counts, raw relationship edges, successors/predecessors, legal-entity events, and mapped ISIN securities.

Synthetic fixture (identifiers and names below are intentionally not live GLEIF records):

```json
{
  "recordType": "entity",
  "stableId": "entity:00000000000000000000",
  "lei": "00000000000000000000",
  "legalName": "Synthetic Demo Entity GmbH",
  "identityVerdict": "EXACT_LEI_MATCH",
  "renewalStatus": "CURRENT",
  "reviewPolicy": "balanced",
  "reviewPriority": "LOW",
  "recommendedNextStep": "USE_AS_CURRENT_GLEIF_REFERENCE",
  "parentContext": {
    "requested": true,
    "directParent": { "lei": "11111111111111111111", "legalName": "Synthetic Demo Parent SE" }
  }
}
```

The separate `PORTFOLIO_SUMMARY` output includes status, renewal, country and review-priority distributions; renewal and high-priority queues; shared published parents; and change counts.

### 🎛️ Input guide

#### Companies and identity evidence

- `leis` — up to 200 exact 20-character LEIs; each receives `EXACT_LEI_MATCH`.
- `companyNames` — up to 100 registered-name searches, with up to 200 matches per name.
- `countries` — up to 20 ISO two-letter filters. With company names they narrow each search; without LEIs or names they become bounded country-registry targets.
- `country` — hidden backward-compatible single-country alias for existing API inputs.
- `registrationNumber` — optional expected home-registry number used as positive identity evidence when it matches.
- `entityStatus`, `registrationStatus`, `entityCategory` — optional GLEIF filters for company-name searches.

#### Result and review detail

- `outputProfile` — Essential for compact automation, Decision for review fields, Standard for the complete normalized result, or Full to retain the official source record as well.
- `reviewPolicy` — Balanced, renewal-strict, or identity-strict source-backed review weights. None is an approval, legal, sanctions, credit, or compliance verdict.
- `includeParentContext` — official direct/ultimate parent basics or reporting exceptions; on by default and included in the company-record charge.
- `resolveReferenceData` — official legal-form and registration-authority names; on by default and included in the company-record charge.

#### Optional relationships and identifiers

- `includeRelationships` — adds official requests and runtime for separate parent, head-office, branch and fund rows. They are bundled in Assess current companies; only delivered verified relationship changes use the change event in Track verified changes.
- `includeChildren` — adds official requests and runtime for direct/ultimate subsidiary counts and rows, with the same Baseline-bundled/Changes-event rule.
- `expandHierarchy` and `maxHierarchyDepth` — walk the published direct-parent chain for up to 10 levels. The chain is included in the company row; a verified chain update is a change event only in Track verified changes.
- `includeSuccessorsPredecessors` — adds official requests and runtime for published links and legal-entity events, included in Baseline and charged only when a verified change is delivered in Changes.
- `includeSecurities` — adds official requests and runtime for mapped ISINs, included in Baseline and charged only when the mapped set produces a delivered entity change.

#### Monitoring and safeguards

- `deltaWindow` selects the official Golden Copy change window used by Track verified changes.
- `includeUnchanged` optionally adds unchanged audit records without charging them as changes.
- `watchlistName` gives a monitored portfolio a stable label and keeps its state history separate.
- `maxEntities` bounds Baseline company results from 1 to 5,000. `maxTrackedItems` independently bounds the combined Changes state and delivered changes from 1 to 200; the preflight reserves room for as many as 400 simultaneous current and safely confirmed ended candidates. `maxRelationships`, `maxSecurities`, and `maxBuyerChargeUsd` bound enrichment and projected charges. For large country exports, turn off optional parent/relationship enrichment unless it is required.

### 💰 Pricing

`run charge = verified run start + delivered company records`, or, in Track verified changes, `verified run start + delivered changes`. Separate Baseline relationship rows are bundled with their delivered company records.

| Result event | Free | Bronze | Silver | Gold |
|---|---:|---:|---:|---:|
| Verified run start | $0.001 | $0.001 | $0.001 | $0.001 |
| Enriched company record | $0.00170 | $0.00168 | $0.00166 | $0.00164 |
| Verified change | $0.00170 | $0.00168 | $0.00166 | $0.00164 |

On the Free plan, one enriched company result with included parent context is `$0.0027`; five enriched company results are `$0.0095`; one company plus two separately delivered relationship records remains `$0.0027`; a valid Track verified changes run with no delivered changes is `$0.001`; and one delivered change is `$0.0027`. The fixed start protects reliable empty and zero-change work, so this Actor does not claim to be cheapest for every tiny run. Against the current selected same-job Baseline reference, this Actor is scoped cheaper from four delivered enriched company results on Free and from three on Bronze, Silver, and Gold, with the compared Standard profile and included parent context. Parent basics, resolved reference labels, Baseline relationship rows, the portfolio summary, failed/blocked inputs, duplicates, first-run seeds, unchanged audit rows, and suppressed records do not add result events. Apify platform compute and storage charges can still apply under your account plan.

### ✅ Coverage you can trust

Every run writes one explicit coverage state:

- `COMPLETE` — every requested exact scope was reached within the declared limits.
- `FILTERED` — company-name matching, a country registry, or another explicit filter bounds what was visible.
- `CAPPED` — a record, request, byte, runtime, delta, or charge allowance stopped the run.
- `PARTIAL` — usable official records exist but some requested source targets failed.
- `EMPTY_CONFIRMED` — the official source positively returned no records for the requested exact scope.
- `BLOCKED` — official source access was blocked and no trustworthy result was produced.
- `FAILED` — the input, source contract, parser, or run failed without trustworthy output.

`ENDED` is never inferred from `FILTERED`, `CAPPED`, `PARTIAL`, `BLOCKED`, or `FAILED`. An entity or relationship must remain absent through two consecutive comparable `COMPLETE` or `EMPTY_CONFIRMED` snapshots before it can become `ENDED`.

### 🔌 API and automation

Send the same JSON through the Apify API, then read the default Dataset, `PORTFOLIO_SUMMARY`, and `OUTPUT` records. Route downstream workflows on `identityVerdict`, `renewalStatus`, `reviewPriority`, `recommendedNextStep`, or verified change flags while retaining `OUTPUT.coverage.state` with every decision.

An empty Dataset alone is not proof that a run succeeded. Check the run status and coverage state; an empty first Track verified changes result commonly means the comparison snapshot was created successfully.

### ❓ FAQ and support

**Does LOW review priority approve a counterparty?**\
No. It means the returned GLEIF record has no configured source-based review trigger. It is not sanctions, PEP, adverse-media, legal, or regulatory approval.

**Why did a company-name result receive POSSIBLE\_MATCH?**\
Name searches can be ambiguous. Add a country and expected registration number, or switch to the confirmed exact LEI.

**Why is there no parent company?**\
GLEIF may publish a parent, a reporting exception, or neither. The Actor reports which evidence state was reached and never invents a parent or beneficial owner.

**Why did the first Track verified changes run return no records?**\
It creates the comparison snapshot. Later successful same-scope runs can report verified changes.

For support, include the run ID, input without secrets, coverage state, and the `resourceBudget` section from `OUTPUT`. Never send account tokens or private credentials.

# Actor input Schema

## `mode` (type: `string`):

Assess current companies returns enriched current records and a portfolio summary. Track verified changes compares with the previous successful run for the exact same scope.

## `leis` (type: `array`):

Exact 20-character LEIs. Exact LEIs receive an EXACT\_LEI\_MATCH identity verdict. At least one LEI, company name, or country target is required.

## `companyNames` (type: `array`):

Search official GLEIF legal and other names. Each result includes deterministic match confidence and evidence; confirm the returned LEI before automation.

## `countries` (type: `array`):

ISO two-letter countries. With company names, these filter each search. When countries are the only targets, the Actor exports a bounded country registry up to Maximum company records with truthful FILTERED or CAPPED coverage.

## `maxEntities` (type: `integer`):

Stops after this many unique company records. Reaching the limit reports CAPPED when more records may exist. For a large country export, turn off optional enrichment unless you need its extra official-source work.

## `maxTrackedItems` (type: `integer`):

Used only by Track verified changes. Caps the combined company and relationship state and the paid changes delivered by one run. Source work is preflighted for up to twice this number so current changes and safely confirmed ended items can coexist without surprise charges.

## `maxBuyerChargeUsd` (type: `number`):

Stops before the worst-case proposed result charge for the selected limits exceeds this amount. Your Apify account can apply an additional per-run spending limit.

## `country` (type: `string`):

Backward-compatible single-country alias. New inputs should use Countries.

## `registrationNumber` (type: `string`):

Optional home-registry number. A normalized match against GLEIF registeredAs becomes explicit identity evidence; a mismatch is never hidden.

## `entityStatus` (type: `string`):

Optional company-name search filter using GLEIF legal-entity status.

## `registrationStatus` (type: `string`):

Optional company-name search filter for the current GLEIF registration state.

## `entityCategory` (type: `string`):

Optional company-name search filter for the broad GLEIF entity category.

## `outputProfile` (type: `string`):

Controls delivered company-row detail without weakening monitoring state. Standard includes official fields, identity evidence, renewal, quality, review signals and parent context.

## `reviewPolicy` (type: `string`):

Selects transparent source-backed review weights. It changes review priority and the decision path, never sanctions, legal, credit, or onboarding approval.

## `deltaWindow` (type: `string`):

Used by Track verified changes. Larger official delta files can exceed the source-byte safety limit and are rejected before download.

## `includeUnchanged` (type: `boolean`):

Used only by Track verified changes. Adds unchanged records for audit workflows; they are not charged as change results.

## `watchlistName` (type: `string`):

Optional stable label for a tracked portfolio. It becomes part of the state scope, so different names keep independent comparison histories.

## `includeParentContext` (type: `boolean`):

Adds official direct/ultimate parent basics or GLEIF reporting exceptions to each company result. Included by default because it is central to counterparty review.

## `resolveReferenceData` (type: `boolean`):

Resolves official GLEIF legal-form and registration-authority codes to human-readable names. Cached within the run.

## `includeRelationships` (type: `boolean`):

Adds official source requests and runtime for separate parent, head-office, branch and fund relationship rows. In Assess current companies these rows are bundled with the company-record event; in Track verified changes, only a delivered NEW, UPDATED or safely confirmed ENDED relationship uses the change event.

## `includeChildren` (type: `boolean`):

Adds official source requests and runtime for direct/ultimate child counts and relationship rows. In Assess current companies these rows are bundled with the company-record event; in Track verified changes, only a delivered child-relationship change uses the change event. Large groups remain bounded by Maximum relationship records.

## `includeSuccessorsPredecessors` (type: `boolean`):

Adds official source requests and runtime for successor/predecessor links and legal-entity events. In Assess current companies they are included with the company-record event; in Track verified changes, only a delivered verified transition uses the change event. Missing links are never invented.

## `includeSecurities` (type: `boolean`):

Adds official source requests and runtime for mapped ISIN identifiers. In Assess current companies they are included with the company-record event; in Track verified changes, only a delivered entity change caused by the mapped set uses the change event. Results are capped by Maximum ISINs per company.

## `expandHierarchy` (type: `boolean`):

Walks published direct-parent links up to Maximum hierarchy depth. This adds official source requests and runtime. The chain is included with each company result in Assess current companies; a verified chain change uses the change event in Track verified changes.

## `maxHierarchyDepth` (type: `integer`):

Maximum published direct-parent levels followed when hierarchy expansion is on. A cycle or missing published link stops the chain safely.

## `maxSearchResultsPerName` (type: `integer`):

Limits each name search. A limited name search cannot prove that no other matching entity exists.

## `maxRelationships` (type: `integer`):

Global limit for separately delivered parent, subsidiary, successor, predecessor, branch and fund relationship records. In Baseline these rows are bundled with delivered company records and do not add a relationship charge.

## `maxSecurities` (type: `integer`):

Caps mapped ISIN identifiers for each company when securities are included.

## `maxRequests` (type: `integer`):

Infrastructure safety limit across the GLEIF API, Golden Copy catalogue, downloads and retries.

## `maxSourceBytes` (type: `integer`):

Infrastructure safety limit checked before and during official delta downloads.

## `maxRuntimeSecs` (type: `integer`):

Infrastructure safety limit for new official-source work.

## Actor input object example

```json
{
  "mode": "baseline",
  "leis": [
    "529900T8BM49AURSDO55"
  ],
  "maxEntities": 5,
  "maxTrackedItems": 25,
  "maxBuyerChargeUsd": 0.25,
  "outputProfile": "standard",
  "reviewPolicy": "balanced",
  "deltaWindow": "INTRA_DAY",
  "includeUnchanged": false,
  "includeParentContext": true,
  "resolveReferenceData": true,
  "includeRelationships": false,
  "includeChildren": false,
  "includeSuccessorsPredecessors": false,
  "includeSecurities": false,
  "expandHierarchy": false,
  "maxHierarchyDepth": 5,
  "maxSearchResultsPerName": 10,
  "maxRelationships": 20,
  "maxSecurities": 50,
  "maxRequests": 60,
  "maxSourceBytes": 5000000,
  "maxRuntimeSecs": 120
}
```

# Actor output Schema

## `dataset` (type: `string`):

The default Dataset with current company and optional relationship records or verified change records. Use recordType to distinguish mixed rows.

## `portfolioSummary` (type: `string`):

Batch totals, status, renewal and review-priority distributions, attention queues, shared published parents and change counts.

## `runReport` (type: `string`):

The OUTPUT record with requested and reached scope, Golden Copy or delta file date, applied limits, duplicates, coverage, and comparison status.

# 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 = {
    "mode": "baseline",
    "leis": [
        "529900T8BM49AURSDO55"
    ],
    "maxEntities": 5,
    "maxTrackedItems": 25,
    "maxBuyerChargeUsd": 0.25,
    "outputProfile": "standard",
    "reviewPolicy": "balanced",
    "deltaWindow": "INTRA_DAY",
    "includeUnchanged": false,
    "includeParentContext": true,
    "resolveReferenceData": true,
    "includeRelationships": false,
    "includeChildren": false,
    "includeSuccessorsPredecessors": false,
    "includeSecurities": false,
    "expandHierarchy": false,
    "maxHierarchyDepth": 5,
    "maxSearchResultsPerName": 10,
    "maxRelationships": 20,
    "maxSecurities": 50,
    "maxRequests": 60,
    "maxSourceBytes": 5000000,
    "maxRuntimeSecs": 120
};

// Run the Actor and wait for it to finish
const run = await client.actor("luminar/gleif-lei-change-monitor").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 = {
    "mode": "baseline",
    "leis": ["529900T8BM49AURSDO55"],
    "maxEntities": 5,
    "maxTrackedItems": 25,
    "maxBuyerChargeUsd": 0.25,
    "outputProfile": "standard",
    "reviewPolicy": "balanced",
    "deltaWindow": "INTRA_DAY",
    "includeUnchanged": False,
    "includeParentContext": True,
    "resolveReferenceData": True,
    "includeRelationships": False,
    "includeChildren": False,
    "includeSuccessorsPredecessors": False,
    "includeSecurities": False,
    "expandHierarchy": False,
    "maxHierarchyDepth": 5,
    "maxSearchResultsPerName": 10,
    "maxRelationships": 20,
    "maxSecurities": 50,
    "maxRequests": 60,
    "maxSourceBytes": 5000000,
    "maxRuntimeSecs": 120,
}

# Run the Actor and wait for it to finish
run = client.actor("luminar/gleif-lei-change-monitor").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 '{
  "mode": "baseline",
  "leis": [
    "529900T8BM49AURSDO55"
  ],
  "maxEntities": 5,
  "maxTrackedItems": 25,
  "maxBuyerChargeUsd": 0.25,
  "outputProfile": "standard",
  "reviewPolicy": "balanced",
  "deltaWindow": "INTRA_DAY",
  "includeUnchanged": false,
  "includeParentContext": true,
  "resolveReferenceData": true,
  "includeRelationships": false,
  "includeChildren": false,
  "includeSuccessorsPredecessors": false,
  "includeSecurities": false,
  "expandHierarchy": false,
  "maxHierarchyDepth": 5,
  "maxSearchResultsPerName": 10,
  "maxRelationships": 20,
  "maxSecurities": 50,
  "maxRequests": 60,
  "maxSourceBytes": 5000000,
  "maxRuntimeSecs": 120
}' |
apify call luminar/gleif-lei-change-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,luminar/gleif-lei-change-monitor"
        }
    }
}

```

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/VRZhGEdugEqZDvYWe/builds/nvJHffa3T8pOrRkDy/openapi.json