Legal Entity & LEI API
The Legal Entity & LEI API returns verified company and legal-entity data from GLEIF as clean JSON.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
The primary lookup endpoint returns an entity's LEI, legal name, other names, status, jurisdiction, category, legal form and registered address, and you can search, autocomplete, map relationships, resolve mappings, pull reference data and batch. It is built for KYC, compliance and B2B-data workflows that need authoritative legal-entity identifiers without a licensed database. One ReefAPI key, one shared credit pool, the standard envelope.
The LEI code shape, the two status axes, and the codes inside a record
An LEI record carries several code systems at once and they answer different questions: one says how the entity is incorporated, one says whether the record is up to date, and a different one says whether the company still exists. Confusing the last two is the most common misread. Every row below was measured against GLEIF live on Apple Inc. (HWUPKR0MPOU8FGXBT394), Apple Ford, Inc. (254900KZR24L5GN8TE52), Alphabet Inc. and Deutsche Bank.
| Field | Measured shape and values | What it means |
|---|---|---|
| lei | exactly 20 characters: 18 alphanumeric plus 2 check digits (ISO 17442) | format and the ISO 7064 MOD-97-10 checksum are validated locally before any upstream call, so a typo costs nothing and returns INVALID_PARAM with the reason (bad_length or checksum_failed) |
| registration.status | ISSUED, LAPSED, RETIRED, ANNULLED, MERGED, DUPLICATE, PENDING_TRANSFER, PENDING_ARCHIVAL | the state of the LEI RECORD. Every response also carries status_note in plain English. |
| entity_status | ACTIVE or INACTIVE | the state of the COMPANY, a different axis: Apple Ford, Inc. is entity_status ACTIVE with registration status LAPSED |
| legal_form.code | 4-character ISO 20275 ELF code: H1UM (Apple Inc.), O90R (Apple Canada), 6QQB (Deutsche Bank), XTIQ | legal_form.name is filled only when you pass resolve_codes true, which returned "For-Profit Corporation General Stock" for H1UM |
| registration.managing_lou | the issuing organization's own LEI: 5493001KJTIIGC8Y1R12 issued both Apple records | reference kind=lei-issuers lists all 41 LOUs with name, marketing name, website and accreditation date |
| registration.next_renewal | ISO-8601 UTC timestamp | in the future on a healthy record (Apple: 2027-03-08) and in the past on a lapsed one (Apple Ford: 2021-04-08) |
| registration.authority_id / entity_id_at_authority | an RA code plus the id the company holds there: RA000598 / 806592 | the link back to the national business register; reference kind=registration-authorities resolves the RA code |
| conformity_flag | CONFORMING or NON_CONFORMING | measured CONFORMING for Apple Inc. and NON_CONFORMING for the lapsed Apple Ford record |
| relationships parent | type is one of entity, reporting_exception or no_data | Alphabet Inc. returned reporting_exception on both parents, category DIRECT/ULTIMATE_ACCOUNTING_CONSOLIDATION_PARENT, reason NO_KNOWN_PERSON, with a plain-English meaning field |
| map type | isin, bic, mic, qcc and spglobal map to an LEI record; lei_to_isin reverses it | ISIN US0378331005 resolved to Apple Inc., BIC DEUTDEFFXXX to Deutsche Bank AG, and Apple's LEI reversed to 950 ISINs |
| search total vs count | total is GLEIF's full match count, count is what came back | "Apple Inc" returned total 62 with count 6 at limit 6. limit tops out at 200, GLEIF's own page cap. |
match_confidence on search candidates is a string-similarity heuristic computed here for disambiguation, and the response says so in its own confidence_note. It is not a GLEIF field, so do not store it as one. Measured on "Apple Inc": Apple Inc. 1.0, Apple Ford, Inc. 0.92, APPLE CANADA INC. 0.87, APPLE MANAGEMENT INC. 0.7707.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/lei/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"name": "Apple Inc",
"country": "US"
}
}{
"ok": true,
"meta": {
"api": "lei",
"endpoint": "search",
"mode": "live",
"latency_ms": 1487,
"record_count": 20,
"bytes": 97298,
"cache_hit": false,
"source": "gleif",
"license": "CC0",
"upstream_total": 49,
"typo_recovered": false
},
"data": {
"query": "Apple Inc",
"scope": "auto",
"candidates": [
{
"lei": "HWUPKR0MPOU8FGXBT394",
"legal_name": "Apple Inc.",
"match_confidence": 1,
"jurisdiction": "US-CA",
"entity_status": "ACTIVE",
"registration_status": "ISSUED",
"status_note": "LEI is current and maintained.",
"city": "Glendale",
"country": "US",
"legal_form_code": "H1UM",
"other_names": [
"Apple Computer, Inc."
]
},
{
"lei": "254900KZR24L5GN8TE52",
"legal_name": "Apple Ford, Inc.",
"match_confidence": 0.92,
"jurisdiction": "US-DE",
"entity_status": "ACTIVE",
"registration_status": "LAPSED",
"status_note": "renewal is overdue — the entity may very well still exist and operate; lapsed means the LEI record stopped being re-certified, not that the company is gone.",
"city": "WILMINGTON",
"country": "US",
"legal_form_code": "XTIQ",
"other_names": []
},
{
"lei": "5493005L9LZDI71S5Y95",
"legal_name": "Apple Gold, Inc.",
"match_confidence": 0.92,
"jurisdiction": "US-NC",
"entity_status": "ACTIVE",
"registration_status": "LAPSED",
"status_note": "renewal is overdue — the entity may very well still exist and operate; lapsed means the LEI record stopped being re-certified, not that the company is gone.",
"city": "Raleigh",
"country": "US",
"legal_form_code": "8888",
"other_names": [
"M O R Restaurants, Inc."
]
}
],
"count": 20,
"total": 49,
"page": 1,
"confidence_note": "match_confidence is a string-similarity heuristic computed by this API for ranking/disambiguation — it is not a GLEIF field."
}
}What the Legal Entity & LEI API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| lookup | One LEI → the full verified legal-entity record (Level-1 who-is-who): legal name, addresses, jurisdiction, legal form, registration status + honesty note, authority ids, renewal dates, BIC/ISIN-adjacent identifiers. | Fintech apps call lookup to get one LEI → the full verified legal-entity record (Level-1 who-is-who). | lei, resolve_codes, history |
| search | Company name → ranked candidate entities with match_confidence for disambiguation (same-name entities across countries/legal-forms). Filters: country, status, jurisdiction, entity_status. | Portfolio dashboards call search to get company name → ranked candidate entities with match_confidence for disambiguation (same-name…. | name, scope, country, status, entity_status, ... |
| autocomplete | Type-ahead suggestions for a partial company name (GLEIF autocompletions surface) — each suggestion carries its LEI for direct lookup. | Analysts call autocomplete to get type-ahead suggestions for a partial company name (GLEIF autocompletions surface). | name |
| relationships | One LEI → Level-2 corporate hierarchy: direct & ultimate parent (entity OR the entity's declared reporting-exception with reason+meaning OR no_data), children list + total counts. detail=true adds the auditable relationship provenance. | Data teams call relationships to get one LEI → Level-2 corporate hierarchy. | lei, children_limit, detail |
| map | Identifier mapping: ISIN / BIC / MIC / QCC / S&P-Global-ID → LEI record(s), or reverse LEI → all its ISINs. | Fintech apps call map to get identifier mapping. | type, value, limit |
| reference | GLEIF reference collections: ISO-20275 legal forms, registration authorities, LEI issuers (LOUs), jurisdictions, countries, regions, field catalog — list or fetch one by code. | Portfolio dashboards call reference to get gLEIF reference collections. | kind, code, limit, page |
| batch | Up to 50 mixed lookup/search items in one call. Lookups are collapsed into one upstream request per 50 LEIs (GLEIF rate-friendly); searches are spaced. | Analysts call batch to get up to 50 mixed lookup/search items in one call. | items |
Call search from your stack
curl -X POST https://api.reefapi.com/lei/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"name":"Apple Inc","country":"US"}'import requests
r = requests.post(
"https://api.reefapi.com/lei/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"name": "Apple Inc",
"country": "US"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/lei/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"name": "Apple Inc",
"country": "US"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.lei.search with {"name":"Apple Inc","country":"US"}.Who uses this API and why
- KYC and onboarding tools call lookup to verify a counterparty's legal name and jurisdiction from an LEI.
- Compliance teams use relationships to map a company's parent and subsidiary structure.
- B2B-data products use search and autocomplete to resolve a company name to a verified entity.
Questions developers ask before integrating
How long is an LEI, and what happens if one character is wrong?
Exactly 20 characters: 18 alphanumeric plus 2 check digits, per ISO 17442. Both the length and the ISO 7064 MOD-97-10 checksum are verified locally before anything goes upstream, so a bad code fails in milliseconds with a specific reason. "ABC123" returned INVALID_PARAM "bad_length (LEI is exactly 20 chars, got 6)"; changing Apple's last digit from 4 to 0 returned "checksum_failed (ISO 7064 MOD-97-10 remainder != 1)". Spaces, dashes and lowercase are normalized away first.
The status says LAPSED. Has the company shut down?
Almost certainly not, and this is the single most common misreading of LEI data. LAPSED describes the RECORD: its annual re-certification is overdue. Whether the company exists is a separate field, entity_status, which is ACTIVE or INACTIVE. Apple Ford, Inc. measured as registration status LAPSED with entity_status ACTIVE and a next_renewal date back in 2021. Every response spells this out in status_note, so you do not have to remember which axis is which.
legal_form.name is empty. Where do I get the legal form in words?
Pass resolve_codes true on the lookup. By default only legal_form.code comes back (H1UM for Apple Inc.), because resolving it costs two extra cached GLEIF calls. With the flag set, the same call returned name "For-Profit Corporation General Stock". You can also resolve codes in bulk through the reference action with kind=legal-forms, though note the ISO 20275 catch-all code 8888 returns an item whose names array is entirely null.
Why is direct_parent a reporting_exception instead of a company?
Because GLEIF lets an entity declare why it has no reportable parent, and that declaration is data rather than a gap. Alphabet Inc. returned type reporting_exception on both direct and ultimate parent, category DIRECT_ACCOUNTING_CONSOLIDATION_PARENT, reason NO_KNOWN_PERSON, and a meaning field reading "no person (legal or natural) controls the entity". The three possible types are entity (a real parent record), reporting_exception (a declared reason) and no_data (nothing filed at all), and they mean different things in a compliance check.
How many subsidiaries does relationships return?
As many as children_limit allows, defaulting to 50 and capped at 200, but the totals are always complete. Alphabet Inc. with children_limit 3 returned 3 rows in direct_children alongside direct_children_total 33, so you always know what you did not fetch. Each child row carries lei, legal_name, country, jurisdiction and registration_status, which is enough to fan out into further lookups without a second search.
Can I go from an ISIN or a bank's BIC to the company?
Yes, and back again. The map action takes type isin, bic, mic, qcc or spglobal and returns full entity records: US0378331005 resolved to Apple Inc. and DEUTDEFFXXX to DEUTSCHE BANK AKTIENGESELLSCHAFT, each with the same address, legal-form and registration blocks a direct lookup gives you. type lei_to_isin runs the other direction, and Apple's LEI returned 950 ISINs in one call.
I misspelled a company name and still got results. What happened?
Typo recovery ran. When a name has no exact matches, the search probes GLEIF's autocompletions for plausible corrections, re-runs on the best one and then tells you it did: "gogle" came back with typo_recovered true, did_you_mean "GOOGLE LLC" and 3 candidates. It never fires on a query that already matched, and typo false turns it off if you would rather see the empty result.
Why does search report a total far bigger than the rows I got?
total is GLEIF's full match count for the query, and count is what this page returned. "Apple Inc" at limit 6 returned count 6 with total 62. Raise limit up to 200 (GLEIF's own page cap) or walk page, and narrow with country, jurisdiction, status or entity_status rather than paging blindly. min_confidence is the cheapest filter when you only want near-exact name matches.
What is the Legal Entity & LEI API?
Legal Entity & LEI API is a ReefAPI endpoint group for legal entity & lei It returns live JSON through POST requests under /lei/v1.
Is the Legal Entity & LEI API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Legal Entity & LEI calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Legal Entity & LEI login or account?
No login to Legal Entity & LEI is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Legal Entity & LEI data?
The page example is captured from a live lookup call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Legal Entity & LEI API use?
Legal Entity & LEI actions currently cost 1-2 credits per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.
Can I call Legal Entity & LEI from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call lei actions with the same key, credit pool and JSON envelope used by normal REST requests.