Tutorial: GLEIF (LEI) - Gnist Context

Legal

Data source: GLEIF

Overview

GLEIF (LEI) wraps GLEIF, handling authentication, pagination, and rate limits for you. This tutorial covers all 6 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-gleif": {
      "url": "https://context.gnist.ai/mcp/gleif/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (6)

`search_entities`

Search GLEIF for registered legal entities by name, registration number, or jurisdiction. GLEIF (Global Legal Entity Identifier Foundation) covers 2M+ legal entities in 200+ countries. Each entity is identified by a 20-character LEI (ISO 17442) — the global standard mandated for financial reporting under EMIR, MiFID II, Dodd-Frank, and DORA. At least one filter parameter must be provided. Args: name: Legal name or partial name to search for (e.g. "Apple Inc", "Deutsche Bank"). registration_number: Company registration number from the national registry. jurisdiction: ISO 3166-1 alpha-2 country code (e.g. "US", "DE", "NO", "GB"). status: Registration status filter — "ISSUED" (active), "LAPSED" (expired renewal), "MERGED", "RETIRED", "PENDING_TRANSFER", or "ANNULLED". limit: Number of results to return (1–50, default 10). Returns: Dict with 'count' and 'entities' list. Each entity includes lei, name, other_names, jurisdiction, registration_number, registered_address, legal_form, status, next_renewal date, and managing_lou (Local Operating Unit).

Parameter	Type	Required	Description
`name`	any	optional	Legal name or partial name to search for (e.g. "Apple Inc", "Deutsche Bank").
`registration_number`	any	optional	Company registration number from the national registry.
`jurisdiction`	any	optional	ISO 3166-1 alpha-2 country code (e.g. "US", "DE", "NO", "GB").
`status`	any	optional	Registration status filter — "ISSUED" (active), "LAPSED" (expired renewal), "MERGED", "RETIRED", "PENDING_TRANSFER", or "ANNULLED".
`limit`	integer	optional	Number of results to return (1–50, default 10). (default: `10`)

curl -X POST "https://context.gnist.ai/mcp/gleif/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_entities", "arguments": {"name": "Apple Inc"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gleif/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'name': 'Apple Inc'}, 'name': 'search_entities'}},
)
print(resp.json())

`get_entity`

Fetch the full GLEIF record for a Legal Entity Identifier (LEI). Returns the authoritative entity record as registered with GLEIF — canonical legal name, all registered names, jurisdiction, registration number, registered address, legal form, current registration status, and next renewal date. Args: lei: The 20-character LEI code (e.g. "HWUPKR0MPOU8FGXBT394" for Apple Inc). Returns: Dict with lei, name, other_names, jurisdiction, registration_number, registered_address, legal_form, status, next_renewal, and managing_lou. Returns {"error": "not_found"} if the LEI does not exist.

Parameter	Type	Required	Description
`lei`	string	required	The 20-character LEI code (e.g. "HWUPKR0MPOU8FGXBT394" for Apple Inc).

curl -X POST "https://context.gnist.ai/mcp/gleif/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_entity", "arguments": {"lei": "HWUPKR0MPOU8FGXBT394"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gleif/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'lei': 'HWUPKR0MPOU8FGXBT394'}, 'name': 'get_entity'}},
)
print(resp.json())

`get_ownership_chain`

Retrieve ownership chain relationships for a legal entity. Uses GLEIF's relationship data to traverse the corporate ownership structure. Covers entities that report their ownership chain as part of LEI registration. Args: lei: The 20-character LEI of the entity to look up. direction: Which relationships to retrieve: - "direct_parent" — the entity that directly consolidates this one (default) - "ultimate_parent" — the topmost parent in the ownership chain - "children" — entities directly consolidated by this one (subsidiaries) Returns: Dict with 'lei', 'direction', 'count', and 'relationships' list. Each relationship includes relationship_type, relationship_status, start_lei (child), and end_lei (parent). Returns empty list if no relationships are registered.

Parameter	Type	Required	Description
`lei`	string	required	The 20-character LEI of the entity to look up.
`direction`	string	optional	Which relationships to retrieve: - "direct_parent" — the entity that directly consolidates this one (default) - "ultimate_parent" — the topmost parent in the ownership chain - "children" — en... (default: `direct_parent`)

curl -X POST "https://context.gnist.ai/mcp/gleif/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_ownership_chain", "arguments": {"lei": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gleif/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'lei': 'example'}, 'name': 'get_ownership_chain'}},
)
print(resp.json())

`resolve_bic`

Resolve a SWIFT BIC code to its corresponding LEI. Uses the GLEIF BIC-to-LEI mapping maintained in cooperation with SWIFT. Essential for financial agents processing SWIFT messages or correspondent banking data. Args: bic: The SWIFT Bank Identifier Code (8 or 11 characters, e.g. "DEUTDEDB"). Returns: Dict with 'bic' and 'lei' if a mapping exists, or {"error": "not_found"} otherwise. Use get_entity(lei) to retrieve the full entity record for the resolved LEI.

Parameter	Type	Required	Description
`bic`	string	required	The SWIFT Bank Identifier Code (8 or 11 characters, e.g. "DEUTDEDB").

curl -X POST "https://context.gnist.ai/mcp/gleif/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "resolve_bic", "arguments": {"bic": "DEUTDEDB"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gleif/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'bic': 'DEUTDEDB'}, 'name': 'resolve_bic'}},
)
print(resp.json())

`resolve_isin`

Resolve an ISIN (securities identifier) to the issuing entity's LEI. Covers equities, bonds, and structured products. Enables agents to identify the legal entity behind a financial instrument. Args: isin: The 12-character International Securities Identification Number (e.g. "US0378331005" for Apple common stock). Returns: Dict with 'isin' and 'lei' if a mapping exists, or {"error": "not_found"} otherwise. Use get_entity(lei) to retrieve the full entity record for the resolved LEI.

Parameter	Type	Required	Description
`isin`	string	required	The 12-character International Securities Identification Number (e.g. "US0378331005" for Apple common stock).

curl -X POST "https://context.gnist.ai/mcp/gleif/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "resolve_isin", "arguments": {"isin": "US0378331005"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gleif/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'isin': 'US0378331005'}, 'name': 'resolve_isin'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/gleif/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gleif/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_entities to find items, then get_entity to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does GLEIF (LEI) provide?

Legal Entity Identifier (LEI) lookup — corporate identity, ownership, and registration. It exposes 6 tools: search_entities, get_entity, get_ownership_chain, resolve_bic, resolve_isin, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the GLEIF (LEI) API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.