Resolve companies to verified legal entity records
The Legal Entity & LEI API returns verified company and legal-entity data from GLEIF as clean JSON.
7 active endpoints, on 1 and 2 credit tiers.
- POST/lei/v1/lookup
- POST/lei/v1/search
- POST/lei/v1/autocomplete
- POST/lei/v1/relationships
- POST/lei/v1/map
- POST/lei/v1/reference
- POST/lei/v1/batch
What Legal Entity & LEI endpoints does ReefAPI ship?
7 live read endpoints. Read-only data API: no writes, no account actions, no dashboard access on the target site.
Legal Entity & LEI API
3 of 7 endpoints, ready to run
Find a legal entity by name and get ranked candidates with a confidence score, the jurisdiction, the entity and registration status, and a plain-language note on what that status means.
{ "ok": true, "meta": { "api": "lei", "endpoint": "search", "mode": "live", "latency_ms": 1125.7, "record_count": 5, "cache_hit": false }, "data": { "query": "Siemens Aktiengesellschaft", "scope": "auto", "candidates": [ { "lei": "W38RGI023J3WT1HWRP32", "legal_name": "Siemens Aktiengesellschaft", "match_confidence": 1, "jurisdiction": "DE", "entity_status": "ACTIVE", "registration_status": "ISSUED", "status_note": "LEI is current and maintained.", "city": "München", "country": "DE", "legal_form_code": "6QQB", "other_names": [] }, { "lei": "5299004HJB6D966Q0P96", "legal_name": "Siemens Beteiligungen Europa GmbH", "match_confidence": 0.5556, "jurisdiction": "DE", "entity_status": "ACTIVE", "registration_status": "ISSUED", "status_note": "LEI is current and maintained.", "city": "München", "country": "DE", "legal_form_code": "2HBR", "other_names": [] }, { "lei": "529900VGZ27M5ZHAEZ97", "legal_name": "Siemens Advanta Solutions GmbH", "match_confidence": 0.5098, "jurisdiction": "DE", "entity_status": "ACTIVE", "registration_status": "ISSUED", "status_note": "LEI is current and maintained.", "city": "München", "country": "DE", "legal_form_code": "2HBR", "other_names": [] } ], "count": 5, "total": 6, "page": 1, "confidence_note": "match_confidence is a string-similarity heuristic computed by this API for ranking/disambiguation — it is not a GLEIF field." } }
How the Legal Entity & LEI API works
Legal Entity & LEI is a normal ReefAPI surface — the same four rules that hold for every other engine on the key.
No OAuth app, no request signing, no per-site account. One key covers all 185 engines.
Every route is a POST with a JSON body. Parameters are validated against the published schema before anything is charged.
Credits, not seats. Failed and blocked calls are never charged, and cache hits cost nothing.
One envelope everywhere. meta carries latency_ms, record_count and the endpoint that answered.
From a security you hold to the legal entity behind it
The chain that matters for reporting runs identifier, entity, ownership. All three are one call each, and the middle one is the only verified name in the chain.
{"type": "isin", "value": "US0378331005"}An instrument identifier resolves straight to its issuer's verified record, address and current status.
{"lei": "HWUPKR0MPOU8FGXBT394"}The register authority, the id held at that register, the corroboration level and the next renewal date — the fields that tell you whether the record is being maintained.
{"lei": "HWUPKR0MPOU8FGXBT394", "children_limit": 10}Direct and ultimate parents and children, each side with a total so you know how much of the tree you are seeing.
Three credits turn a line in a portfolio into a named, addressed, register-verified legal entity and its group structure.
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"}'{
"ok": true,
"data": { … },
"meta": {
"api": "lei",
"endpoint": "search",
"mode": "live",
"latency_ms": …,
"record_count": …
},
"error": null
}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.
Will it find the company I mean, and how do I know the record is current
Measured on 2026-08-28 against three large groups, one deliberate misspelling and one instrument identifier. The first row is the difference between this working and not working.
Searching a well-known brand name with its home country and a limit of twenty did NOT return the parent company at all: the top hit was a differently-named listed spin-off and the rest were investment funds and a foundation. Searching the full legal name returned the parent at a match confidence of 1.0 as the first row. Register data is filed under the legal name, and so is this index.
Three misspelt company words each recovered: the response set typo_recovered true and did_you_mean to the corrected name, and returned five candidates. But a misspelt word glued to a CORRECT legal suffix returned zero candidates and took over fifteen seconds — recovery never fired. And recovery is not resolution: on two of the three, the top candidate after correction was a subsidiary or a foreign-language entity rather than the company we meant. Read did_you_mean, then read the names back.
Every record carries registration status with a plain-language note, the date it was last updated, the date it is next due for renewal, and a corroboration level saying how thoroughly it was verified. It also names the company register it was validated at and the id it holds there, so the claim is checkable outside this API.
An exact legal name scored 1.0; the next candidates on the same query scored 0.56, 0.51, 0.37 and 0.15, which is a clean cliff to threshold on. On a common word the second-place candidate scored 0.92 and was a completely different company, so the cliff is not always there. Read the name back, do not trust the rank.
One group returned ten children with the totals beside them: 458 direct and 570 ultimate. Another returned 8 direct out of 8 and 10 of 20 ultimate. Always read the totals, not the length of the array. Names in that tree can look unrelated and still be correct — we checked a suspicious one and it was a recent acquisition.
Where there is no parent, the response returns a typed reporting exception with a category and a plain-English meaning rather than a null. Two large groups returned two different reasons: no controlling person at all in one case, control by natural persons in the other. That distinction matters for beneficial-ownership work and it is not something you can infer from an empty field.
Search returned in 1.2 to 2.7 seconds on five consecutive runs and lookup in about 1.5 — but the sample pane on this page has caught the same search taking 32 seconds, so the typical figure is not the figure to build a timeout around. The relationships call is slow by design rather than by accident: 8.5 seconds on one group and 34.8 on another. Cache what you can; a legal entity record and its ownership tree do not change hourly.
What people build with Legal Entity & LEI
The jobs this data is most often used for.
endpoints
credits per call
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.
What Legal Entity & LEI data costs
The cheapest call here is 1 credit, so $15/mo (Pro) buys 10,000 of them — $1.50 per 1,000 credits. Credits roll over and never expire, and failed or blocked calls are not charged.
Full pricing →- 1,000 free credits on signup, no card
- One key, all 185 APIs, one credit pool
- Failed and blocked calls are never charged
- Credits roll over and never expire
Call it in two lines
Sign up, get 1,000 credits and one key that works on every engine. Then this is the whole protocol.
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"])Have a question? We got answers.
The questions people actually ask before wiring up Legal Entity & LEI.
Get a free key →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.
5 Finance & Data APIs on the same key
One key, one credit pool, one response envelope. If you are pulling Legal Entity & LEI, you are one call away from the rest of the category — no second contract, no second integration.
Need something this API does not do?
Name the endpoint, the field, or a source we do not carry yet. We ship new APIs every week and you would be first to get the key. Real people read every message and reply the same day.
Try it on your own data before you pay anything
The call above is the real endpoint, not a recording. A free key gives you 1,000 credits, the other 184 APIs, and the same envelope everywhere.
Endpoints, parameters and credit costs on this page are read from the live catalog and cannot drift from what the API accepts. Field notes were captured on 2026-08-28.