# China LEI Entity Change Monitor (`zinin/china-lei-entity-change-monitor`) Actor

Monitor official GLEIF LEI records for entity, registration and parent-relationship changes in mainland China and Hong Kong.

- **URL**: https://apify.com/zinin/china-lei-entity-change-monitor.md
- **Developed by:** [Tim Zinin](https://apify.com/zinin) (community)
- **Categories:** Lead generation, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $6.80 / 1,000 lei entity check delivereds

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/platform/actors/running/actors-in-store#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

## China LEI Entity Change Monitor

Monitor legal-entity, LEI-registration, and published parent-relationship changes for mainland China and Hong Kong using the official GLEIF API. It is designed for scheduled compliance, counterparty, vendor, and portfolio workflows that need a durable baseline rather than an unbounded company scraper.

### What it does

- accepts exact LEIs, bounded entity-name searches, or a bounded `CN`/`HK` country query;
- reads only `https://api.gleif.org/api/v1` — no API key or proxy is required;
- captures legal and alternate names, entity/registration status, renewal dates, LOU, conformity, and published direct/ultimate parents;
- persists a private baseline scoped by `watchName + LEI`;
- distinguishes `new`, `change`, `replay`, `no_change`, `no_match`, and `source_error` without silently converting failures to empty results.

This is not a sanctions check, beneficial-ownership determination, credit decision, or complete company registry. A GLEIF reporting exception means a parent relationship may legitimately be unavailable.

### Quick start

```json
{
  "countries": ["CN"],
  "names": ["Bank of China"],
  "nameMatchMode": "fuzzy",
  "includeRelationships": true,
  "replayBaseline": false,
  "maxResults": 10,
  "maxConcurrency": 3,
  "watchName": "china-lei-watch"
}
```

Use the same `watchName` on later scheduled runs. Exact LEI lookups remain constrained to the selected country list. Name searches use GLEIF matching; `exact` mode additionally requires a normalized legal, alternate, or transliterated-name equality check. The Actor never accepts arbitrary URLs.

### Result and baseline semantics

| `changeType` | Meaning | Baseline action | PPE item |
|---|---|---|---|
| `new` | First confirmed snapshot for this watch | Written only after paid row delivery | Yes |
| `change` | Canonical snapshot differs | Advanced only after paid row delivery | Yes |
| `replay` | Unchanged snapshot, explicitly requested | Preserved | Yes |
| `no_change` | Unchanged scheduled check | Preserved | No |
| `no_match` | Valid official response confirms no matching record | Preserved | No |
| `source_error` | Transport, HTTP, JSON, schema, or relationship failure | Preserved; run fails | No |

The Dataset default item event must resolve to numeric exact zero. The `entity-checked` event and run-start event must match the same approved contract tier and are never string-coerced. A mutex serializes strict budget checks and delivery/charge calls under concurrent fetches. Caps and spend must be finite nonnegative numbers, except the explicitly contracted unlimited cap (`Infinity`). A paid row is confirmed only by a finite numeric `chargedCount >= 1`; otherwise processing fails and no affected baseline is written.

### Output

Each Dataset row includes runtime GLEIF source name, CC0 license, and terms URL in addition to its entity/no-match/error fields. Successful entity rows include LEI, legal name, country, entity and registration status, changed fields, previous/current snapshots, optional parent relationships, Golden Copy publication date, official record URL, and observation time. The terminal `OUTPUT` key-value-store record includes `terminal`, status, counters, billing event, runtime attribution, error, storage IDs, and completion time.

### Limits and responsible use

- Countries: `CN` and optionally `HK` only.
- Up to 20 LEIs, 20 names, 100 unique results, and concurrency 1–5.
- Public official data only; no proxy, browser session, credential, buyer token, dynamic Actor ID, or child Actor.
- Data freshness and completeness follow the GLEIF Golden Copy and the submitting LEI issuers.

### Data source, license, and independence

Entity data comes from the [official GLEIF API](https://www.gleif.org/en/lei-data/gleif-api). GLEIF makes LEI data available under the [Creative Commons CC0 1.0 dedication](https://www.gleif.org/en/meta/lei-data-terms-of-use). Source rows include attribution for traceability even though CC0 does not require it.

This independent Actor is not affiliated with, sponsored by, or endorsed by the Global Legal Entity Identifier Foundation. It does not use GLEIF branding or logos.

### 中文简介

本 Actor 通过 GLEIF 官方 API 监控中国大陆（`CN`）及可选香港（`HK`）的 LEI 主体、注册状态和已公布的母公司关系变化。无需 API 密钥或代理。请在定时任务中保持相同的 `watchName`，以便比较历史基线。`no_match` 表示官方响应确认无匹配；网络、HTTP 或数据结构错误会输出 `source_error` 并使运行失败，不会伪装成空结果。数据采用 CC0 1.0；本 Actor 与 GLEIF 无隶属或背书关系。

### Local verification

```bash
npm ci
npm test
npm audit --omit=dev
npm run probe:live
```

The deterministic tests never use the network. Their 40-case raw JSON:API corpus covers 20 CN entities, 8 HK entities, 4 relationships, 4 normalized exact alias searches, 2 lapsed registrations, and 2 adversarial identity/schema responses. Fuzzy mode is delegated to the official GLEIF name-search endpoint; this Actor does not claim a separate client-side fuzzy scorer. `probe:live` is an intentionally separate, read-only check of current official API compatibility.

# Actor input Schema

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

Mainland China (CN) is the default. Add Hong Kong (HK) when required.

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

Optional exact 20-character Legal Entity Identifiers.

## `names` (type: `array`):

Optional bounded entity-name searches. Searches are restricted to the selected countries.

## `nameMatchMode` (type: `string`):

Fuzzy uses GLEIF full-text matching. Exact additionally requires a normalized legal or alternate-name match.

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

Resolve direct and ultimate accounting parents when GLEIF publishes a relationship.

## `replayBaseline` (type: `boolean`):

Emit a paid replay row for unchanged records. Keep disabled for change-only scheduled monitoring.

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

Hard cap across all searches after deterministic LEI de-duplication.

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

Bounded concurrency for official GLEIF requests.

## `watchName` (type: `string`):

Stable private baseline scope. Reuse this value on scheduled runs.

## Actor input object example

```json
{
  "countries": [
    "CN"
  ],
  "leis": [],
  "names": [
    "Bank of China"
  ],
  "nameMatchMode": "fuzzy",
  "includeRelationships": true,
  "replayBaseline": false,
  "maxResults": 20,
  "maxConcurrency": 3,
  "watchName": "china-lei-watch"
}
```

# Actor output Schema

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

API URL for new, changed, replayed, unchanged, no-match and source-error rows.

## `OUTPUT` (type: `string`):

API URL for terminal schemaVersion/flag, status, counters, billing event, runtime GLEIF attribution/license/terms, error, Dataset/KVS IDs and finishedAt.

# 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 = {
    "countries": [
        "CN"
    ],
    "names": [
        "Bank of China"
    ],
    "watchName": "china-lei-watch"
};

// Run the Actor and wait for it to finish
const run = await client.actor("zinin/china-lei-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 = {
    "countries": ["CN"],
    "names": ["Bank of China"],
    "watchName": "china-lei-watch",
}

# Run the Actor and wait for it to finish
run = client.actor("zinin/china-lei-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 '{
  "countries": [
    "CN"
  ],
  "names": [
    "Bank of China"
  ],
  "watchName": "china-lei-watch"
}' |
apify call zinin/china-lei-entity-change-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,zinin/china-lei-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/BGP8kgZAimEEN7ahM/builds/kWgtV6IN1hWu45Vv8/openapi.json