GET /schema

POST /v3/mapping

Map third party identifiers to FIGIs.

Request Format

The request should be an Array of Objects (or Mapping Jobs), e.g. [{...}, {...}, ...], where each Object has the following properties:

Property	Type	Required	Description
idType	String		Type of third party identifier. See Enum Values for all supported 3rd party identifier types.
idValue	String, Number		The value for the represented third party identifier.
exchCode	String		Exchange code of the desired instrument(s) (cannot use in conjunction with micCode). Click here for the current list of exchCode values.
micCode	String		ISO market identification code(MIC) of the desired instrument(s) (cannot use in conjunction with exchCode). Click here for the current list of micCode values.
currency	String		Currency associated to the desired instrument(s). Click here for the current list of currency values.
marketSecDes	String		Market sector description of the desired instrument(s). Click here for the current list of marketSecDes values.
securityType	String		Security type of the desired instrument(s). Click here for the current list of securityType values.
securityType2	String	When idType is BASE_TICKER or ID_EXCH_SYMBOL.	An alternative security type of the desired instrument(s). securityType2 is typically less specific than securityType. Click here for the current list of securityType2 values. Use Market sector description if securityType2 is not available. Click here for the current list of marketSecDes values.
includeUnlistedEquities	Boolean		Set to true to include equity instruments that are not listed on an exchange.
optionType	String		Will filter instruments based on option type. Valid values are Call and Put.
strike	Array(2)		Will find instruments whose strike price falls in an interval. Value should be an Array interval of the form [a, b] where a, b are Numbers or null. At least one entry must be a Number. When both are Numbers, it is required that a <= b. Also, [a, null] is equivalent to the interval [a, ∞) and [null, b] is equivalent to (-∞, b].
contractSize	Array(2)		Will find instruments whose contract size falls in an interval. Value should be an Array interval of the form [a, b] where a, b are Numbers or null. At least one entry must be a Number. When both are Numbers, it is required that a <= b. Also, [a, null] is equivalent to the interval [a, ∞) and [null, b] is equivalent to (-∞, b].
coupon	Array(2)		Will find instruments whose coupon falls in an interval. Value should be an Array interval of the form [a, b] where a, b are Numbers or null. At least one entry must be a Number. When both are Numbers, it is required that a <= b. Also, [a, null] is equivalent to the interval [a, ∞) and [null, b] is equivalent to (-∞, b].
expiration	Array(2)	When securityType2 is Option or Warrant.	Will find instruments whose expiration date falls in an interval. Value should be an Array interval of the form [a, b] where a, b are date Strings or null. Date strings must be of the form YYYY-MM-DD. At least one entry must be a date String. When both are date Strings, it is required that a and b are no more than one year apart. Also, [a, null] is equivalent to the interval [a, a + (1 year)] and [null, b] is equivalent to [b - (1 year), b].
maturity	Array(2)	When securityType2 is Pool.	Will find instruments whose maturity date falls in an interval. Value should be an Array interval of the form [a, b] where a, b are date Strings or null. Date strings must be of the form YYYY-MM-DD. At least one entry must be a date String. When both are date Strings, it is required that a and b are no more than one year apart. Also, [a, null] is equivalent to the interval [a, a + (1 year)] and [null, b] is equivalent to [b - (1 year), b].
stateCode	String		State code of the desired instrument(s). Click here for the current list of stateCode values.

Some of the properties above are "enum-like" in the sense that they have only a limited number of valid values. For those properties you can use the GET /v3/mapping/values/:key endpoint to get the current list of valid values.

Response Format

The response is an Array of Objects where the Object at index i contains the results for the Mapping Job at index i in the request. Each Object has one of the following properties:

Property	Type	Description
data	Array of Objects	Is present when FIGI(s) are found for the associated Mapping Job. See below for more information about the structure of the Objects in the Array.
error	String	Is present when Single job result exceeds 15,000 FIGIs. There was an unexpected error when processing the request.
warning	String	Is present when no FIGI is found.

When FIGI(s) are found for a Mapping Job, each Object of the data Array described above will have the following properties:

Property	Type	Description
figi	String	FIGI assigned to the instrument.
securityType, marketSector, exchCode, securityType2	String, null	Enum-like attributes of the instrument.
ticker, name, shareClassFIGI, compositeFIGI, securityDescription	String, null	Various attributes of the instrument.
metadata	"Metadata N/A"	When the above attributes are unavailable or unable to be shown, this property is present.

Limits

Type of limitation	Without API key	With API key
Number of mapping jobs in a single request	5	100

Sample Request

[
    { "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" },
    { "idType":"BASE_TICKER", "idValue":"TSLA 10 C100", "securityType2":"Option", "expiration":["2018-10-01", "2018-12-01"]},
    { "idType":"BASE_TICKER", "idValue":"NFLX 9 P330", "marketSecDes":"Equity", "securityType2":"Option", "strike":[330,null], "expiration":["2018-07-01",null]},
    { "idType":"BASE_TICKER", "idValue":"FG", "marketSecDes":"Mtge", "securityType2":"Pool", "maturity":["2019-09-01", "2020-06-01"]},
    { "idType":"BASE_TICKER", "idValue":"IBM", "marketSecDes":"Corp", "securityType2":"Corp", "maturity":["2026-11-01",null]},
    { "idType":"BASE_TICKER", "idValue":"2251Q", "securityType2":"Common Stock", "includeUnlistedEquities": true}
]                       

Sample Response

[{
    "data": [{
        "figi": "BBG000NHN466",
        "securityType": "Common Stock",
        "marketSector": "Equity",
        "ticker": "IBMGBX",
        "name": "INTL BUSINESS MACHINES CORP",
        "exchCode": "EU",
        "shareClassFIGI": "BBG001S5S399",
        "compositeFIGI": "BBG000NHN304",
        "securityType2": "Common Stock",
        "securityDescription": "IBMGBX"
    }, {
        "figi": "BBG000NRMJ71",
        "securityType": "Common Stock",
        "marketSector": "Equity",
        "ticker": "IBMGBX",
        "name": "INTL BUSINESS MACHINES CORP",
        "exchCode": "XL",
        "shareClassFIGI": "BBG001S5S399",
        "compositeFIGI": "BBG000NRMD01",
        "securityType2": "Common Stock",
        "securityDescription": "IBMGBX"
    }]
}, {
    "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",
        "compositeFIGI": null,
        "shareClassFIGI": null,
    }]
},
{
    "error": "No identifier found."
},
...
]                       

GET /v3/mapping/values/:key

Get the current list of values for the enum-like properties on Mapping Jobs.

Request Format

Parameter	Type	Required	Description
key	String (one of idType, exchCode, micCode, currency, marketSecDes, securityType, securityType2, stateCode )		The name of the Mapping Job property for which to list the possible values.

Response Format

The response is an Object having one of the following properties:

Property	Type	Description
values	Array of Strings	The current list of values present for the property named by the key request parameter.
error	String	Is present when there was an error when processing the request.
warning	String	Is present when no FIGI is found.

Sample Request

/v3/mapping/values/marketSecDes

Sample Response

{
    "values": [
        "Comdty",
        "Corp",
        "Curncy",
        "Equity",
        "Govt",
        "Index",
        "M-Mkt",
        "Mtge",
        "Muni",
        "Pfd"
    ]
}                       

POST /v3/search

Search for FIGIs using key words and other filters.

Request Format

The request should be an Object with the following properties:

Property	Type	Required	Description
query	String		Key words.
start	String		The number of results returned for any given request is fixed. When more results are accessible, the response will contain a next property whose value should be sent in succeeding requests as the value of the start property. This will notify the API to return the next "page" of results.
exchCode, micCode, currency, marketSecDes, securityType, securityType2, includeUnlistedEquities, optionType, strike, contractSize, coupon, expiration, maturity, stateCode	See POST /v3/mapping		All of these properties are optional but otherwise work exactly as in POST /v3/mapping.

Response Format

The response is an Object having the following properties:

Property	Type	Description
data	Array of Objects	Works exactly as in the response of POST /v3/mapping.
error	String	Works exactly as in the response of POST /v3/mapping.
next	String	Present when more results are accessible for the query. To get the next "page" of results for the query, send the same search request except with the start property's value set to the value provided here.

Sample Request

{
    "query": "ibm",
    "exchCode": "US"
}

Sample Response

{
    "data": [{
        "figi": "BBG000BLNNH6",
        "name": "INTL BUSINESS MACHINES CORP",
        "ticker": "IBM",
        "exchCode": "US",
        "compositeFIGI": "BBG000BLNNH6",
        "securityType": "Common Stock",
        "marketSector": "Equity",
        "shareClassFIGI": "BBG001S5S399",
        "securityType2": "Common Stock",
        "securityDescription": "IBM"
    }, {
        "figi": "BBG0002ZTPD8",
        "name": "March 10 Calls on IBM US",
        "ticker": "IBM 03/20/10 C105",
        "exchCode": "US",
        "compositeFIGI": "BBG0002ZTPD8",
        "securityType": "Equity Option",
        "marketSector": "Equity",
        "shareClassFIGI": null,
        "securityType2": "Option",
        "securityDescription": "IBM US 03/20/10 C105"
    }
        ...
    ],
    "next": "QW9JSVFEOFMrQ3hDUWtjd01ERTRTMHhhUXpBPSAx.3AG33VCsv54AsUl5fGHehSytWPuWLJxf0t8VL3YXuJh="
}

The appearance of the next property in the response signals that more results can be accessed for this query. To do so, send the request:

{
    "query": "ibm",
    "exchCode": "US",
    "start": "QW9JSVFEOFMrQ3hDUWtjd01ERTRTMHhhUXpBPSAx.3AG33VCsv54AsUl5fGHehSytWPuWLJxf0t8VL3YXuJh="
}

The next property will continue to appear in the response Object whenever more results are accessible, and those results can be retrieved by repeating this process.

POST /v3/filter

Search for FIGIs using key words and other filters. The results are listed alphabetically by FIGI and include the number of results.

Request Format

The request should be an Object with the following properties:

Property	Type	Required	Description
query	String		Key words.
start	String		The number of results returned for any given request is fixed. When more results are accessible, the response will contain a next property whose value should be sent in succeeding requests as the value of the start property. This will notify the API to return the next "page" of results.
exchCode, micCode, currency, marketSecDes, securityType, securityType2, includeUnlistedEquities, optionType, strike, contractSize, coupon, expiration, maturity, stateCode	See POST /v3/mapping		All of these properties are optional but otherwise work exactly as in POST /v3/mapping.

Response Format

The response is an Object having the following properties:

Property	Type	Description
data	Array of Objects	Works exactly as in the response of POST /v3/mapping.
error	String	Works exactly as in the response of POST /v3/mapping.
next	String	Present when more results are accessible for the query. To get the next "page" of results for the query, send the same search request except with the start property's value set to the value provided here.
total	number	Present how many figis match filter options.

Sample Request

{
    "exchCode": "US"
}

Sample Response

{
    "data": [{
        "figi": "BBG000BLNNH6",
        "name": "INTL BUSINESS MACHINES CORP",
        "ticker": "IBM",
        "exchCode": "US",
        "compositeFIGI": "BBG000BLNNH6",
        "securityType": "Common Stock",
        "marketSector": "Equity",
        "shareClassFIGI": "BBG001S5S399",
        "securityType2": "Common Stock",
        "securityDescription": "IBM"
    }, {
        "figi": "BBG0002ZTPD8",
        "name": "March 10 Calls on IBM US",
        "ticker": "IBM 03/20/10 C105",
        "exchCode": "US",
        "compositeFIGI": "BBG0002ZTPD8",
        "securityType": "Equity Option",
        "marketSector": "Equity",
        "shareClassFIGI": null,
        "securityType2": "Option",
        "securityDescription": "IBM US 03/20/10 C105"
    }
        ...
    ],
    "next": "QW9JSVFEOFMrQ3hDUWtjd01ERTRTMHhhUXpBPSAx.3AG33VCsv54AsUl5fGHehSytWPuWLJxf0t8VL3YXuJh=",
    "total": 29930312
}

The appearance of the next property in the response signals that more results can be accessed for this query. To do so, send the request:

{
    "exchCode": "US",
    "start": "QW9Fc1FrSkhNREF3TVZKVVJGY3ogMQ==.wAoXs2FMDgSubHmn4eCvQjx6pvAIM4KU8g7zWH5N0cw="
}

The next property will continue to appear in the response Object whenever more results are accessible, and those results can be retrieved by repeating this process.

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

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

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

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

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

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

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

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

[{"idType":"ID_BB_8_CHR","idValue":"12345678"}]

[{"idType":"ID_TRACE","idValue":"12345678"}]

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

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

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

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

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

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

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

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

[{"idType":"BASE_TICKER","idValue":"IBM"}]

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

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

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

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

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

[{"idType":"ID_SHORT_CODE","idValue":"120521.SH"}]

[{"idType":"VENDOR_INDEX_CODE","idValue":"990100"}]

Version 2 of the API is nearly the same as Version 3 with any differences in the output below. Version 3 removes 'uniqueID' and 'uniqueIDFutOpt' from the response.

POST /v2/mapping

Response Format

Property	Change from V3
uniqueID	Return 'null'.
uniqueIDFutOpt	Return 'null'.

Version 1 of the API is nearly the same as Version 2 with any differences in specific requests listed below. Version 2 is recommended as it provides increased coverage.

POST /v1/mapping

Request Format

Property	Change from V2
securityType2	Not required.
expiration	Not required.
maturity	Not required.

GET /v1/mapping/values/:key

This request is the same as in V2 although there may be fewer values (due to V2's increased coverage). Use the links below to view the current values for each enum-like parameter in V1.

• idType
• exchCode
• micCode
• currency
• marketSecDes
• securityType
• securityType2
• stateCode

The OpenFIGI Submission API allows creating new FIGIs programmatically. Get detail from Submission API (Login required)