GLEIF API
This quick-start guide presents:
an overview of the GLEIF API v1.0 for developers and others, with
examples of the most common use cases.
To see a live demonstration of potential applications of this API, please go to the following link:
Potential applications include (for example):
Search for LEIs with names matching, or similar to, a list of names of known legal entities
Find LEIs by BIC Code or ISIN Code
Find LEI records with at least 2 direct and ultimate children (search within parent entities)
The full endpoint listing is found below this guide.
To skip to a specific endpoint, click on a link in the menu bar to the left.
The endpoints are grouped first according to the resource path (API URL) section, and then by the content of their responses.
Each endpoint description below includes a listing of parameters that can be used to build requests, and an example value for each parameter.
Pairs of request-response examples are given for each endpoint. You can select from the available examples using the dropdowns to the right.
Quick-Start Guide
About the GLEIF API
The GLEIF API gives developers access to full LEI Data search engine functionality, including filters, full-text and single-field searches of Level 1 (LEI Record) Data, retrieval of LEI Records (including links to their Level 2 data, where available), based on a search of their associated Level 2 (relationship) data, and "fuzzy" matching of important data fields such as names and addresses.
The GLEIF API is based on the data found in the GLEIF Golden Copy. For more information please see:
https://www.gleif.org/en/lei-data/gleif-golden-copy#
Important Note:
The API responses included in this API documentation are provided as examples. Please note that LEI data is maintained by the LEI Issuing Organization/LOUs, and GLEIF cannot guarantee the accuracy or up-to-date status of the provided API responses.
Request Format
Requests are HTTP REST calls, following the JSON API specification. Detailed example requests can be found in the quick-start guide and in the endpoint listing. Example requests in the quick-start guide can be sent by opening the links in a web browser.
Response Format
The GLEIF API returns LEI Records and Level 2 Data (Relationship Records and Reporting Exceptions). Level 2 Data is available via links found in the Level 1 (LEI Record) responses. Other associated data, such as standard codes, and LEI Issuer information, is also available.
These data are contained in JSON-formatted responses according to the JSON API specification.
JSON API responses represent resources in a REST-ful way, so they include URLs to related resources.
Where a response contains more than 15 results, pagination information and
first/lastpage links are included.LEI Data is presented in a simplified JSON format based on the CDF formats but using more intuitive names for some fields.
Response Pagination
Search results in the API response can be paginated using the page[number] and page[size] parameters, for example:
https://api.gleif.org/api/v1/lei-records?filter[fulltext]=bank&page[number]=2&page[size]=15
Links to the first, next, and last pages in a result set are included in the meta object within the response, where applicable.
Detailed Documentation Per API Resource and LEI Data Field
You can retrieve technical details of resources and LEI Data fields provided by the API from the following fields endpoint:
https://api.gleif.org/api/v1/fields
For each data field, the fields endpoint returns the following information:
type: always has the valuefieldsfor this endpoint.id: a unique ID for the field, based on the CDF format for an LEI, Relationship, or Reporting Exception record.key: a unique key based on the ID of the field.field: the ID for the field in the full API response (similar to JSON structures).label: a human-readable display label for the field, for use in documentation, search results, graphical user interfaces, etc.data_type: the type of data returned by requesting this field, one of:RESOURCE: the field represents a unique resource available to this API.STRING: the field is a string.ENUM: the field is a string, whose value will be one of the allowed value list (enumeration) for the field.DATE: a date/time value in ISO 8601 format.
enum: specifies the allowed value list (enumeration) for the field.resource: specifies the API resource endpoint part for the field.sortable: the field can be used to sort search results (true/false).operators: lists operators for use in a search interface.contexts: lists suggested "contexts" combining two or more fields in a search interface.xpath: the XPATH of this data field in the CDF (Common Data File) format XML Schema Definition (XSD). The XPATH can be used to look up specific CDF data elements, their content definitions (what data may appear in each element), and their cardinalities (how many times an element must or may appear in an LEI Data Record).
An FAQ document with an introduction to the CDF formats and some technical details is available at:
https://www.gleif.org/en/about-lei/common-data-file-format (scroll down to "Relevant Files for Download")
For the fundamental data definitions, please see the LEI-CDF specifications/XML schemas:
https://www.gleif.org/en/about-lei/common-data-file-format/lei-cdf-format/lei-cdf-format-version-2-1 (scroll down to "Relevant Files for Download")
Use Cases
The following Use Cases present example requests for some of the most common business needs of LEI Data Users.
Level 1 (LEI and Legal Entity) Data
Level 1 Data describes the LEI registration and the Legal Entity identified by the LEI.
Finding Legal Entities By Name
If you wish to find LEI records for known Legal Entities, and part or all of their name is known precisely, it can be helpful to start searching with a filter directly on the Legal Name field, for example:
If the desired Legal Entity's name is not known precisely, it could be difficult to find exact matches only by filtering.
You can also find Legal Entities with potentially similar names using the fuzzycompletions endpoint. This type of search can provide a convenient starting point for obtaining LEIs.
Warning: Please see the disclaimer below.
- Use the
qparameter to give a search term, and get back LEI Records with statistically similar data, for example:
https://api.gleif.org/api/v1/fuzzycompletions?field=fulltext&q=factbook
Note: the result of the above request is the "matched" data, not the full record. The LEI Record context can be found by following the related link in this case.
- Set the
fieldparameter to search different LEI Data fields.
Note: This will sometimes produce very different results, depending on the statistical frequency of those terms in legal entity data.
For example, compare a search for hacker, first in the legal name, and then including address fields (fulltext):
https://api.gleif.org/api/v1/fuzzycompletions?field=entity.legalName&q=hacker
(finds mainly Legal Entities with hacker or similar in their names)
https://api.gleif.org/api/v1/fuzzycompletions?field=fulltext&q=hacker
(finds many Legal Entities with hacker or similar in their addresses, even though names are also included)
The following parameters can be used:
Finding LEI Records by LEI
To perfom a simple lookup, getting LEI Records using their LEIs, provide a comma-separated list of LEI Codes in the filter[lei] parameter to the leirecords endpoint, for example:
Finding LEI Records by BIC
Use the filter function as described above, but with the bic filter only, for example:
https://api.gleif.org/api/v1/lei-records?filter[bic]=ALETITMMXXX
Finding LEI Records by ISIN
Use the filter function as described above, but with the isin filter only, for example:
https://api.gleif.org/api/v1/lei-records?filter[isin]=DE000ST8MPP0
Finding all ISINs associated with an LEI Record
Request the related isins of a known LEI Record. The results will be all ISIN-LEI mappings currently reported for the requested LEI Record, where these have been provided according to the mapping process established by Association of National Numbering Agencies (ANNA).
Note: This will sometimes produce a large number of results which can be accessed using the pagination features described above.
https://api.gleif.org/api/v1/lei-records/529900W18LQJJN6SJ336/isins
Level 2 (relationship) Data
Level 2 Data describes relationships between Legal Entities, where these have been reported by the Legal Entities themselves.
Display Parents of an LEI
A search for the parents of Legal Entities can be formulated as the question "who owns...?"
Apply the owns filter to modify an LEI search to return parents of the LEI Record identified, if these exist, for example:
https://api.gleif.org/api/v1/lei-records?filter[owns]=315700WQBDF1ZVVE0T64
Display Children of an LEI
A search for the parents of Legal Entities can be formulated as the question "who is owned by...?"
Apply the ownedBy filter to modify an LEI search to return parents of the LEI Record identified, if these exist, for example:
https://api.gleif.org/api/v1/lei-records?filter[ownedBy]=529900IYQRX2JSSIZA36
Query Syntax
The following use cases reflect typical features of a search engine's interface. These are followed by a listing of filter operators that can be used to build further queries.
To demonstrate each use case simply, the following example requests are configured to return one result at a time.
The full number of "hits" is always available in the
paginationobject in the API response.To obtain the next result, increment the
page[number]parameter, or use thenextlink in the response.
Filter by Country, Legal Entity Type (General Category), or LEI Registration Status
- Retrieve all Legal Entities with an official, registered (legal) address in Germany:
- Retrieve all Legal Entities marked as a
FUND:
https://api.gleif.org/api/v1/lei-records?filter[entity.category]=FUND&page[number]=1&page[size]=1
- Retrieve all Legal Entities whose LEI registration has
LAPSED:
- Retrieve all Legal Entities that fill all of the above criteria:
Search Operators
The following operators can be used together with the filter parameter to build more specific queries.
Display Search Results
- Sort search results by country:
- Sort search results by legal name:
https://api.gleif.org/api/v1/lei-records?sort=entity.legalName&page[size]=1&page[number]=1
Disclaimer
Fuzzy matching of any given data field is based on statistical similarity and does not guarantee that the LEI belongs to the legal entity you are searching for.
You may wish to corroborate potential matches by comparing possibly relevant LEIs' reference data (names, addresses, business register number, etc.) with known attributes of your clients.
Contact legal entities directly in case of doubt, to ensure that the correct LEI for that entity is used, and remind them to renew their LEI if it has lapsed.
There are other tools on the market for using LEI data, though GLEIF does not recommend any specific third-party tool.
Terms & Conditions
There is no charge for the use of GLEIF’s LEI data.
GLEIF does not enter into individual contractual relationships with specific users of the LEI data.
Rate limiting is currently set at 60 requests, per minute, per user, for all users.
Please refer instead to the LEI Data Terms of Use available here: https://www.gleif.org/en/meta/lei-data-terms-of-use/