> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Legal Entities (GLEIF)

> The GLEIF Global LEI Index as an Open Feed — 3.39M legal entities and their corporate hierarchy, plus a fused hierarchy endpoint resolved through the entity spine.

The Legal Entities API exposes the **GLEIF Global LEI Index**: the Legal Entity Identifier
registry that banks, regulators and reporting regimes key on worldwide. It arrives two ways —
as a **raw Open Feed** (the registry near as-published) and as a **fused endpoint** that
resolves an entity through our spine and returns its corporate hierarchy.

| Surface       | Path                                     | What it is                                                                                       |
| ------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Open Feed** | `/api/v2/gleif/*`                        | 3.39M LEI records, Level-2 relationships and LEI↔ISIN mappings, served close to as-published     |
| **Fused**     | `/api/v2/entities/{entity_id}/hierarchy` | An entity's parents and children, resolved through the same spine as Events / Stories / Entities |
| **Search**    | `/api/v2/search?universe=registry`       | All 3.39M searchable by legal name or LEI, in their own lane                                     |

<Warning>
  **This is corporate hierarchy, not ownership.** GLEIF Level 2 records **accounting
  consolidation** under IFRS/US-GAAP — which entity consolidates which into its financial
  statements. It carries **no ownership percentages** and **excludes natural persons**, so it is
  **not beneficial-ownership data** and must not be used as a substitute for it. Where GLEIF
  records no percentage, this API asserts none.
</Warning>

<Info>
  The Open Feed endpoints are **plan-gated** on `can_use_gleif`, included on the **Analyst plan
  and up**; the fused `/hierarchy` endpoint uses the existing `can_use_exposure` entitlement.
  The **LEI itself is ungated** — it is CC0 and already flows on `GET /api/v2/search`.
</Info>

## Coverage is partial, and the API says so

The single most important field is `coverage`, and it exists because "no parent returned" has
three very different meanings:

| `coverage`                                      | Means                                                                                                       |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `lei_present: false`                            | We hold **no LEI** for this entity. A coverage gap on our side — **not** evidence the entity has no parent. |
| `reporting_exception: "NO_KNOWN_PERSON"` (etc.) | The filer **declared** an exception instead of naming a parent. A **known** absence.                        |
| `in_gleif_level2: false`                        | The LEI exists but files no Level-2 relationships at all.                                                   |
| `direct_parent: null` with none of the above    | No parent relationship is on file.                                                                          |

Read `coverage` before you read `hierarchy`. A null parent with a reporting exception is a
fact about the filing; a null parent with `lei_present: false` is a fact about us.

## Open Feed

`GET /api/v2/gleif/entities` — filtered list over the LEI universe. **At least one filter is
required**: the feed covers 3.39M records, so an unfiltered listing returns
`400 FILTER_REQUIRED` rather than being served slowly.

| Param                                                     | Description                                                                             |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `lei`                                                     | One or more LEIs, comma-separated (max 100). Each must pass the ISO 17442 check digit.  |
| `name`                                                    | Legal name — normalized-exact or **prefix** match. Not a substring scan.                |
| `country`                                                 | ISO-3 of the legal address (our house convention).                                      |
| `jurisdiction`                                            | GLEIF's raw value — alpha-2 or subdivision (`US-CA`).                                   |
| `entity_status`, `registration_status`, `entity_category` | Validated enums; a bad value returns `400 INVALID_ENUM` with `details.accepted_values`. |

`GET /api/v2/gleif/entities/{lei}` — one full record plus its relationships, declared
reporting exceptions and ISINs. A structurally impossible LEI returns `400 INVALID_LEI` (it
fails the ISO 17442 check digit); a well-formed LEI we do not hold returns `404`.

`GET /api/v2/gleif/relationships` — Level-2 records. `lei` matches **either** endpoint. Note
the source convention: the **start node is the child** and the **end node is the parent**.

`GET /api/v2/gleif/isin` — `lei` → ISINs, or `isin` → LEI. One of the two is required.

## Corporate hierarchy (fused)

`GET /api/v2/entities/{entity_id}/hierarchy` accepts the same identifiers as the rest of the
API — a name, an `e_` id, a `wiki:` id, a wikipedia\_url — **and** a bare 20-character LEI. The
identifier you searched with works at this hop too, so `GET /api/v2/search` → `/hierarchy`
composes without translating ids.

```bash theme={null}
curl -H "Authorization: Bearer $GDELT_API_KEY" \
  "https://gdeltcloud.com/api/v2/entities/Gazprom/hierarchy?direction=both"
```

| Param              | Description                                              |
| ------------------ | -------------------------------------------------------- |
| `direction`        | `up`, `down` or `both` (default `both`).                 |
| `depth`            | Ancestor chain depth, 1–5 (default 1).                   |
| `include_siblings` | Entities sharing the same direct parent (default false). |
| `limit`            | Children to return, max 50.                              |

`child_count` is **null**, never `0`, when the requested direction excluded children — an
omitted count and a counted zero are different claims.

<Info>
  Point-in-time (`as_of`) is **not supported** for this source. The hierarchy reflects the latest
  golden copy we loaded; prior states are not reconstructable.
</Info>

## Searching the registry

`GET /api/v2/search?universe=registry&q=…` searches all 3.39M records by legal name or LEI.
Registry results stay in their **own lane** and never appear under `universe=all` or
`universe=reference` — a registry hit is a legal-entity **registration**, not evidence of news
coverage. Each result carries `resolved_in_spine`, telling you whether we also cover the
entity itself, and a `lei` that chains onward to `/api/v2/gleif/entities/{lei}` and
`/api/v2/entities/{lei}/hierarchy`.

## Licence and attribution

GLEIF publishes the Global LEI Index under **CC0 1.0**. Every response carries
`meta.attributions[]` with GLEIF's required notice: the data is provided **as is** and **as
available**, and **GLEIF does not endorse, support or authorize** this product or its outputs.
Nothing here is "GLEIF-verified".