# GLEIF Entity Change Monitor - LEI and Parent Data (`maydit/gleif-entity-change-monitor`) Actor

Monitor explicit LEI watchlists for legal-entity, registration and accounting-parent changes. Preserve parent reporting exceptions and source evidence. No API key.

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

## Pricing

from $3.00 / 1,000 legal entity observations

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?

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

![Entity changes, with parent context — illustrative workflow](https://api.apify.com/v2/key-value-stores/YGxD9JRpduom8Q5Zd/records/gleif-entity-change-monitor-51176498a0b5.png?signature=126y0cLGELn1h8AxsxXZw)

### Entity changes, with parent context

Maintain a counterparty reference-data watchlist from the official GLEIF API. Saved observations combine entity identity, LEI registration and optional accounting-parent evidence without fuzzy company matching.

[Open this Actor in Console](https://console.apify.com/actors/Fl0SFGfZj6r9Eafuq/input) · [First run](#try-this-actor) · [Results](#result-preview) · [Cost](#usage-and-pricing) · [Full guide](#full-guide)

### Try this Actor

1. **Choose a small scope.** Use the existing **Apple identity and parent reporting exceptions** example below: one LEI, parent information enabled and at most one saved entity.
2. **Run and review.** Open the dataset and inspect entity status separately from LEI registration status. The run's key-value-store `SUMMARY` records entity and parent-source failures.
3. **Use the results.** Export JSON to retain parent relationships, reporting exceptions and saved field differences. Keep the LEI and source link when reconciling downstream records.

**Read this before using the data:** An active entity can have a lapsed LEI. Parent relationships describe accounting consolidation, not a complete beneficial-ownership graph. Missing parent data does not prove that no parent exists.

**Apple LEI and Parent Reporting Exceptions** — copy this input into the JSON editor in Console.

```json
{"leis":["HWUPKR0MPOU8FGXBT394"],"includeParents":true,"maxResults":1}
```

### Result preview

The dataset view highlights these columns:

- **LEI** · `lei`
- **Legal entity name** · `legalName`
- **Entity status** · `entityStatus`
- **LEI registration status** · `registrationStatus`
- **Jurisdiction** · `jurisdiction`
- **LEI next renewal date** · `nextRenewalDate`

Use the original source links and the field definitions below when interpreting the results. CSV works well for flat columns; JSON preserves nested values.

### Usage and pricing

Base result rate on the FREE tier: **$5 per 1,000 legal entity observations**. The [Pricing tab](https://apify.com/maydit/gleif-entity-change-monitor/pricing) shows your plan's result rate and any Actor Start charge. Set a small result limit for the first run; the requested limit is not a guarantee of that many results.

***

### Full guide

Monitor explicit **Legal Entity Identifier (LEI) watchlists** for changes in company identity, LEI registration and published accounting-parent relationships. Each result preserves source evidence and distinguishes parent relationships from reporting exceptions. The official public API requires no key.

#### Why use it

Keep a counterparty master-data feed current without repeatedly reconciling entity records, parent links and reporting exceptions yourself. Named observation history produces field-level differences and can skip unchanged records. The product provides evidence for your workflow; it does not decide whether a counterparty should be approved or rejected.

**Price:** $0.005 per saved entity on FREE/BRONZE, plus the configured $0.00005 start event. SILVER results are 20% less; GOLD and higher are 40% less. Parent lookups are included in the entity result. Skipped unchanged observations have no result charge. Apify's configured prices govern the actual charge.

#### Fast default

`{}` checks Apple Inc. (`HWUPKR0MPOU8FGXBT394`) and Microsoft India Corporation (`8945006U6W5TYUM16C74`), including their direct/ultimate parent information. This illustrates both a published reporting exception and a published accounting-consolidation relationship.

#### Inputs

| Field | Meaning |
|---|---|
| `leis` | Up to 50 explicit valid 20-character LEIs, including valid check digits. Empty input uses the two default entities. |
| `includeParents` | Fetch both direct and ultimate relationship records or reporting exceptions; default true. |
| `maxResults` | Maximum saved entity rows; default 2 and maximum 50. |
| `comparePrevious` | Compare the exact LEI list and parent setting with saved observations; default false. |
| `onlyChanges` | Enables comparison and skips unchanged observations; default false. |
| `snapshotName` | Named history scope, default `default`; one writer per name/scope. |
| `maxRunSeconds` | Own deadline, default 240 seconds and range 30–900; also respects the platform deadline with a 25-second reserve. |

#### Output

One complete row per saved entity includes:

- `lei`, `legalName`, `entityStatus`, `entityCategory`, `jurisdiction`, `legalForm`, `registrationAuthority`, `registeredAs`.
- Published `legalAddress` and `headquartersAddress`.
- `registrationStatus`, `registrationUpdatedAt`, `initialRegistrationDate`, `nextRenewalDate`, `managingLou`, `corroborationLevel`, `conformityFlag`.
- `directParent` and `ultimateParent`, each with a status and exact source evidence.
- `sourceGoldenCopyAt` when supplied by the API, `url`, `observedAt`, `contentHash` and attribution.
- `comparisonStatus`: `not_requested`, `new`, `changed` or `unchanged`; `changedFields`, `previousObservedAt` and `previous`.

Parent status meanings:

| Status | Meaning |
|---|---|
| `reported` | A published accounting-consolidation relationship, with `parentLei`, type, status, periods, registration dates and source URL. |
| `reporting_exception` | The publisher gives a reason for not reporting this parent, retained verbatim with its category, reference and source URL. |
| `not_reported` | The entity response supplies neither parent relationship nor exception link. This does not prove that there is no parent. |
| `not_requested` | `includeParents` was false. |

**Entity status and LEI registration status are different.** An active entity can have a lapsed LEI. Parent records describe accounting consolidation, not a full beneficial-ownership graph. A `NATURAL_PERSONS` reporting exception does not identify any individuals. No personal owner lookup is performed.

#### Three exact examples

##### Apple identity and parent reporting exceptions

Use the [copyable first-run input](#try-this-actor) above.

##### Microsoft India accounting-parent relationships

```json
{"leis":["8945006U6W5TYUM16C74"],"includeParents":true,"maxResults":1}
```

##### Unilever and Microsoft identity watchlist

```json
{"leis":["549300MKFYEKVRWML317","INR2EJN1ERAN0W5ZP974"],"includeParents":false,"maxResults":2}
```

#### Repeated observations

The named key-value store `maydit-gleif-entity-history` retains observations. `snapshotName`, sorted LEI list and `includeParents` define the history scope. The first comparison run emits `new` observations and logs a warning. A later unchanged run with `onlyChanges:true` legitimately emits zero results.

Identity, registration and parent fields are compared. Retrieval time and Golden Copy publication time are excluded from the change hash. A newer Golden Copy alone therefore does not manufacture a company change. Publisher update timestamps remain part of the source observation. Changes are observed between runs, not claimed to have happened at the observation time.

History advances only after a complete entity row is confirmed saved. If either requested parent lookup fails, that entity is marked failed and no partial paid row or history update is created. A rejected spending-limit row never updates history; a final accepted row does count when the SDK signals a cap. Choose `maxResults` at least as large as the LEI list when establishing a complete watchlist baseline.

The Actor re-reads history before committing and refuses a detected concurrent change. This is an optimistic check, not an atomic lock: **use one writer per snapshot scope**. Invalid stored history is rejected; a new `snapshotName` starts fresh. Missing entities never generate removal events.

#### Coverage and failures

`SUMMARY` includes `status`, `incomplete`, `rowsSaved`, `rowsObserved`, `unchangedSkipped`, `sourcesSucceeded`, `sourceCoverage`, `failedSources` and limit flags. Failed entity/parent responses, invalid shapes and deadline stops are explicit. A run in which no usable observations can be saved fails; valid no-change runs and budget stops do not invent data rows.

There is no company-name search, child-tree traversal, sanctions screening, credit score or investment/legal advice. Not every business has an LEI. Source data may be incomplete, delayed or inaccurate. Parent and entity endpoints are fetched separately and are not a transactional snapshot of the entire GLEIF database.

#### Sources and reuse

The Actor uses the [official GLEIF API](https://www.gleif.org/en/lei-data/gleif-api) and follows parent/exception endpoints returned by it, restricted to the exact expected public host and LEI path. Requests respect robots rules, bounded time/size limits, rate-limit responses and public-network safety checks.

GLEIF provides the reference data under [CC0 and its data terms](https://www.gleif.org/en/meta/lei-data-terms-of-use). The underlying data is freely available. The price covers this Actor's normalized, repeatable observation workflow. This independent product is not affiliated with or endorsed by GLEIF.

For support or correction/deletion requests, use Actor Issues or **bmay@mayd-it.com**.

### Help with your run

Open the **Issues** tab on this Actor with the run URL, the input field that caused trouble and what you expected to receive. Remove API keys and private information before posting.

[Explore more Mayd-It Actors](https://apify.com/maydit)

### Understand your run

Open **Run report** in the run’s Output tab for saved-record counts, reported source issues and limits, and suggested next steps. Use **CSV export** to take the saved results into a spreadsheet. The existing JSON results and detailed machine-readable summary remain available.

The report reflects this run’s recorded coverage. A successful run or a saved result does not establish that every possible source record was collected.

# Actor input Schema

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

Explicit watchlist of at most 50 valid 20-character LEIs. Empty input uses Apple Inc. and Microsoft India Corporation. No name-based fuzzy matching.

## `includeParents` (type: `boolean`):

Fetch both direct/ultimate accounting consolidation relationships or publisher reporting exceptions. If a required request fails, that entity produces no partial paid row.

## `maxResults` (type: `integer`):

Upper bound on paid saved rows. Unchanged observations skipped by onlyChanges do not consume this limit.

## `comparePrevious` (type: `boolean`):

Compare within this exact configured watchlist/scope. The first run reports new observations; history advances only after confirmed saved output.

## `onlyChanges` (type: `boolean`):

Enables comparison and skips unchanged observations. First observations are emitted. A valid no-change run has zero results and a warning.

## `snapshotName` (type: `string`):

1–80 letters, numbers, underscores or hyphens. Use one writer per name/scope. Concurrent modification is checked before saving, but the store is not an atomic lock.

## `maxRunSeconds` (type: `integer`):

Own wall-clock deadline, also bounded by the platform deadline with a 25-second safety reserve. Network requests and retry delays stay within it.

## Actor input object example

```json
{
  "leis": [
    "HWUPKR0MPOU8FGXBT394",
    "8945006U6W5TYUM16C74"
  ],
  "includeParents": true,
  "maxResults": 2,
  "comparePrevious": false,
  "onlyChanges": false,
  "snapshotName": "default",
  "maxRunSeconds": 240
}
```

# Actor output Schema

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

No description

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

Readable summary of saved records, reported source coverage, limits and next steps. Available when this run saves its SUMMARY.

## `csvExport` (type: `string`):

Download saved dataset records as a CSV file for spreadsheets and other tools.

## `summary` (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 = {
    "leis": [
        "HWUPKR0MPOU8FGXBT394",
        "8945006U6W5TYUM16C74"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("maydit/gleif-entity-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 = { "leis": [
        "HWUPKR0MPOU8FGXBT394",
        "8945006U6W5TYUM16C74",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("maydit/gleif-entity-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 '{
  "leis": [
    "HWUPKR0MPOU8FGXBT394",
    "8945006U6W5TYUM16C74"
  ]
}' |
apify call maydit/gleif-entity-change-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,maydit/gleif-entity-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/Fl0SFGfZj6r9Eafuq/builds/8ggYSwObtcpxioFKf/openapi.json