The OpenFIGI API

Introduction

The OpenFIGI API is part of the OpenFIGI v1.0 REST API. It allows mapping from third-party identifiers to FIGIs.

This API can be accessed without any kind of account/authentication provided in the HTTP Authorization Header, but that access overall will be rate-limited based on all "public" traffic to the API. However, if you sign-up for an account on the website, you can request an API key. With an API key passed in the HTTP Authorization Header, you won't face any generic rate-limiting. However, if you personally pass certain request thresholds, you personally will still be rate-limited.

Please sign-up and/or login to obtain an API Key.

Quick Guide

User can start with making a sample request using the below command:

curl -v -X POST 'https://api.openfigi.com/v1/mapping'   \
     --header 'Content-Type: text/json'             \
     --data '[{"idType":"ID_WERTPAPIER","idValue":"851399","exchCode":"US"}]'

Example response in JSON

[
  {
    "data": [
      {
        "figi": "BBG000BLNNH6",
        "securityType": "Common Stock",
        "marketSector": "Equity",
        "ticker": "IBM",
        "name": "INTL BUSINESS MACHINES CORP",
        "uniqueID": "EQ0010080100001000",
        "exchCode": "US",
        "shareClassFIGI": "BBG001S5S399",
        "compositeFIGI": "BBG000BLNNH6",
        "securityType2": "Common Stock",
        "securityDescription": "IBM",
        "uniqueIDFutOpt": null
      }
    ]
  }
]

Back to top

API Key

User can pass in an API key in the HTTP X-OPENFIGI-APIKEY Header. With a valid API_KEY, user will be subject to a higher rate-limiting threshold and bulk request size.

curl -v -X POST 'https://api.openfigi.com/v1/mapping'                 \
     --header 'Content-Type: text/json'                           \
     --header 'X-OPENFIGI-APIKEY: abcdefghijklmnopqrstuvwxyz'     \
     --data '[{"idType":"ID_WERTPAPIER","idValue":"851399"}]'

Please sign-up and/or login to obtain an API Key.

Back to top

Rate-Limiting

User is subject to rate-limiting while using the OpenFIGI API. There are two types of limitation currently enforced:

Types of limitation Without API_KEY With API_KEY
Number of requests you could make per minute 5 100
Number of mapping jobs in a single request 5 100
Total number of mapping jobs per minute 25 10,000

Back to top

Request Format

You can make a request for one or more mappings at a time. The request is passed in via HTTP request body. The only supported HTTP verb is POST. Here is a sample request to the API:

[
  {"idType":"ID_ISIN","idValue":"US4592001014"},
  {"idType":"ID_WERTPAPIER","idValue":"851399","exchCode":"US"},
  {"idType":"ID_BB_UNIQUE","idValue":"EQ0010080100001000","currency": "USD"},
  {"idType":"ID_SEDOL","idValue":"2005973","micCode":"EDGX", "currency":"USD"}
]

Below is a table describing what each of the parameters mean:

Parameter Type Required Explanation
idType string Yes

Type of third party identifier. See Supported Identifiers for all supported 3rd party identifier types.

idValue string or number Yes

The value for the represented third party identifier.

exchCode string No

An optional exchange code if it applies(cannot use with micCode).

micCode string No

An optional ISO market identification code(MIC) if it applies(cannot use with exchCode).

currency string No

An optional currency if it applies.

marketSecDes string No

An optional market sector description if it applies

Back to top

Response Formats

See below for a sample response from the API. It will be an array of object, where each object represents the response for the corresponding position's request in input array. Each response object contains either a data property or an error property, representing a success or fail mapping request. The data property is an array of object with length greater or equal to 1, containing all the possible matches for the supplied search criteria. If there is an error, the error property will be a string explaining the error condition(such as invalid parameters). Below shows an example of a successful response for a three instrument mapping request, in which contains a single match, a multiple match and an error case respectively.


    [
      {
        "data": [
          {
            "figi": "BBG000NHN466",
            "securityType": "Common Stock",
            "marketSector": "Equity",
            "ticker": "IBMGBX",
            "name": "INTL BUSINESS MACHINES CORP",
            "uniqueID": "EQ0000000005051123",
            "exchCode": "EU",
            "shareClassFIGI": "BBG001S5S399",
            "compositeFIGI": "BBG000NHN304",
            "securityType2": "Common Stock",
            "securityDescription": "IBMGBX",
            "uniqueIDFutOpt": null
          },
          {
            "figi": "BBG000NRMJ71",
            "securityType": "Common Stock",
            "marketSector": "Equity",
            "ticker": "IBMGBX",
            "name": "INTL BUSINESS MACHINES CORP",
            "uniqueID": "EQ0000000005140428",
            "exchCode": "XL",
            "shareClassFIGI": "BBG001S5S399",
            "compositeFIGI": "BBG000NRMD01",
            "securityType2": "Common Stock",
            "securityDescription": "IBMGBX",
            "uniqueIDFutOpt": null
          }
        ]
      },
      {
        "data": [
          {
            "figi": "BBG009R4CLR3",
            "marketSector": "Govt",
            "securityType": "US GOVERNMENT",
            "ticker": "T 2 08/15/25",
            "name": "US TREASURY N/B",
            "exchCode": "BERLIN",
            "securityDescription": "T 2 08/15/25",
            "securityType2": "Note",
            "uniqueID": null,
            "compositeFIGI": null,
            "shareClassFIGI": null,
            "uniqueIDFutOpt": null
          }
        ]
      },
      {
        "error": "No identifier found."
      }
    ]
                    

Back to top

Supported Identifiers

idType Definition
ID_ISIN ISIN
ID_BB_UNIQUE Unique Bloomberg Identifier
ID_SEDOL Sedol Number
ID_COMMON Common Code
ID_WERTPAPIER Wertpapierkennnummer/WKN
ID_CUSIP CUSIP
ID_BB ID BB
ID_ITALY Italian Identifier Number
ID_EXCH_SYMBOL Local Exchange Security Symbol
ID_FULL_EXCHANGE_SYMBOL Full Exchange Symbol
COMPOSITE_ID_BB_GLOBAL Composite Financial Instrument Global Identifier
ID_BB_GLOBAL_SHARE_CLASS_LEVEL Share Class Financial Instrument Global Identifier
ID_BB_SEC_NUM_DES Security ID Number Description
ID_BB_GLOBAL Financial Instrument Global Identifier (FIGI)
TICKER Ticker
ID_CUSIP_8_CHR CUSIP (8 Characters Only)
OCC_SYMBOL OCC Symbol
UNIQUE_ID_FUT_OPT Unique Identifier for Future Option
OPRA_SYMBOL OPRA Symbol
TRADING_SYSTEM_IDENTIFIER Trading System Identifier

Back to top

Error Codes

HTTP Status Code Message Scenario
400 Request body must be an array. The request body is not an array.
401 Key is not active. or Key doesn't exist. The API_KEY is invalid.
404 Invalid path: PATH The requested path is invalid.
405 Invalid method: METHOD The HTTP verb is not POST.
406 Supported Content Type: TYPEs The server does not support the requested Accept type.
413 Request contains #N identifiers. The max number of identifiers allowed is #M. The request exceeds the max number of identifiers support in one request.
429 Too Many Requests. User hit the rate limitation.
500 Error message All other sever internal errors.

Back to top