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

Examples on GitHub

See the OpenFIGI/api-examples GitHub repository for code examples on how to use the API.

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. Please note that the limits are approximations and may be subject to change. 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 250
Number of mapping jobs in a single request 5 100
Total number of mapping jobs per minute 25 25,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 - International Securities Identification Number.

Example:

[{"idType":"ID_ISIN","idValue":"XX1234567890"}]
ID_BB_UNIQUE

Unique Bloomberg Identifier - A legacy, internal Bloomberg identifier.

Example:

[{"idType":"ID_BB_UNIQUE","idValue":"EQ0010080100001000"}]
ID_SEDOL

Sedol Number - Stock Exchange Daily Official List.

Example:

[{"idType":"ID_SEDOL","idValue":"1234567"}]
ID_COMMON

Common Code - A nine digit identification number.

Example:

[{"idType":"ID_COMMON","idValue":"123456789"}]
ID_WERTPAPIER

Wertpapierkennnummer/WKN - German securities identification code.

Example:

[{"idType":"ID_WERTPAPIER","idValue":"123456"}]
ID_CUSIP

CUSIP - Committee on Uniform Securities Identification Procedures.

Example:

[{"idType":"ID_CUSIP","idValue":"123456789"}]
ID_CINS

CINS - CUSIP International Numbering System.

Example:

[{"idType":"ID_CINS","idValue":"123456789"}]
ID_BB

ID BB - A legacy internal Bloomberg identifier.

Example:

[{"idType":"ID_BB","idValue":"123456789"}]
ID_ITALY

Italian Identifier Number - The Italian Identification number consisting of five or six digits.

Example:

[{"idType":"ID_ITALY","idValue":"123456"}]
ID_EXCH_SYMBOL

Local Exchange Security Symbol - Local exchange security symbol.

Example:

[{"idType":"ID_EXCH_SYMBOL","idValue":"IBM"}]
ID_FULL_EXCHANGE_SYMBOL

Full Exchange Symbol - Contains the exchange symbol for futures, options, indices inclusive of base symbol and other security elements.

Example:

[{"idType":"ID_FULL_EXCHANGE_SYMBOL", "idValue":"IBM A1819C150000"}]
COMPOSITE_ID_BB_GLOBAL

Composite Financial Instrument Global Identifier - The Composite Financial Instrument Global Identifier (FIGI) enables users to link multiple FIGIs at the trading venue level within the same country or market in order to obtain an aggregated view for an instrument within that country or market.

Example:

[{"idType":"COMPOSITE_ID_BB_GLOBAL", "idValue":"BBG000BLNNH6"}]
ID_BB_GLOBAL_SHARE_CLASS_LEVEL

Share Class Financial Instrument Global Identifier - A Share Class level Financial Instrument Global Identifier is assigned to an instrument that is traded in more than one country. This enables users to link multiple Composite FIGIs for the same instrument in order to obtain an aggregated view for that instrument across all countries (globally).

Example:

[{"idType":"ID_BB_GLOBAL_SHARE_CLASS_LEVEL", "idValue":"BBG001S5S399"}]
ID_BB_GLOBAL

Financial Instrument Global Identifier (FIGI) - An identifier that is assigned to instruments of all asset classes and is unique to an individual instrument. Once issued, the FIGI assigned to an instrument will not change.

Example:

[{"idType":"ID_BB_GLOBAL", "idValue":"BBG0000362Y4"}]
ID_BB_SEC_NUM_DES

Security ID Number Description - Descriptor for a financial instrument. Similar to the ticker field, but will provide additional metadata data.

Example:

[{"idType":"ID_BB_SEC_NUM_DES", "idValue":"IBM 7 10/30/25"}]
TICKER

Ticker - Ticker is a specific identifier for a financial instrument that reflects common usage.

Example:

[{"idType":"TICKER", "idValue":"IBM"}]
ID_CUSIP_8_CHR

CUSIP (8 Characters Only) - Committee on Uniform Securities Identification Procedures.

Example:

[{"idType":"ID_CUSIP_8_CHR","idValue":"12345678"}]
OCC_SYMBOL

OCC Symbol - A twenty-one character option symbol standardized by the Options Clearing Corporation (OCC) to identify a U.S. option.

Example:

[{"idType":"OCC_SYMBOL","idValue":"IBM 170630C00120000"}]
UNIQUE_ID_FUT_OPT

Unique Identifier for Future Option - Bloomberg unique ticker with logic for index, currency, single stock futures, commodities and commodity options.

Example:

[{"idType":"UNIQUE_ID_FUT_OPT","idValue":"IBMG=Z7 SA Equity"}]
OPRA_SYMBOL

OPRA Symbol - Option symbol standardized by the Options Price Reporting Authority (OPRA) to identify a U.S. option.

Example:

[{"idType":"OPRA_SYMBOL","idValue":"IBM F3017C120000"}]
TRADING_SYSTEM_IDENTIFIER

Trading System Identifier - Unique identifier for the instrument as used on the source trading system.

Example:

[{"idType":"TRADING_SYSTEM_IDENTIFIER","idValue":"FZH18 IBMG"}]

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