Converting ISINs to RICs using the DSS REST API
Introduction
This article investigates several use cases that involve translating ISINs into RICs, or retrieving data using ISINs directly, with the DSS (DataScope Select) REST API. To keep it short we will concentrate on the DSS REST API.
You will need some basic DSS GUI and DSS REST API knowledge to understand this article. If you want to test the code a valid DSS user account is also required.
A separate article covers the same topic for LSEG Tick History REST API users - called 'ISIN to RIC conversion with the LSEG Tick History REST API'.
Instrument identifier codes
Instrument identifiers can be referred to using several coding systems.
LSEG products use RICs (Instrument Codes), which uniquely identify financial instruments, including where they are traded. As an example, IBM.N identifies the IBM stock traded on NYSE, and IBM.L identifies the IBM stock traded on LSE. The RIC syntax here is <ticker>.<exchange>, which is the most common syntax in use, but there are cases where the syntax is different (options, futures, FX, etc.).
Several other codes are in use in the financial world (ISIN, Sedol, Cusip, etc.). One of the popular ones is ISINs (International Securities Identification Number) which uniquely identify securities, but do not identify the venue (or exchange) where they are traded. For example, US4592001014 identifies the IBM stock (whatever venue it is traded on).
Mapping ISINs to RICs
To request data on DSS you can use the ISIN (and an exchange code), but for other LSEG products (like Real-Time ones) you must use the RIC, so if you have ISINs (or other codes) you will need to map them to RICs.
As an ISIN does not identify the venue, a single ISIN maps to several RICs. For example, the IBM ISIN US4592001014 maps to more than 50 RICs, one for each data source (i.e. venue or exchange): IBM.LM, IBM.MX, IBM.BE, IBM.HA, IBM.H, IBMI.L, etc.
Primary RIC
One of these is the primary RIC. It identifies the exchange with the primary listing for the instrument (i.e. the venue where it was originally listed, which is usually in the country of origin of the company). In the case of IBM the primary exchange is NYSE, and the Primary RIC is IBM.N.
Other identifier types: Cusip, Sedol
This article uses ISINs as an example, because their use is widespread, but everything in this article can also be applied when working with Cusips and Sedols.
Instruments and code extracts used in this article
We use 4 ISINs in our examples:
| ISIN | Asset class | Comment | Primary RIC | Primary Exchange |
|---|---|---|---|---|
| US4592001014 | Equity | IBM.N | NYS | |
| GB00B29MWZ99 | Equity | Delisted Sept. 2009 | TRIL.L | LSE |
| DE000C0JK7R7 | Future derivative | Expired Sept. 2017 | STXXU7 | EUX |
| DE0001135317 | Bond | Expired 4 Apr. 2017 | N/A | CPL |
The code extracts are based on pure HTTP requests. To try them out you can cut and paste them into a REST client, like Postman. This is explained in the REST API Tutorials Introduction. You can also download the associated Postman environment and collection to avoid copy/pasting. All request headers must contain an authentication token; refer to the REST API Tutorial 1 for details.
The full workflow for some requests is omitted for clarity, but when required you will find pointers to the tutorials where the details are explained.
Delisted RICs
Some queries might return delisted RICs among the results. A delisted RIC is no longer listed on the exchange, there are no quotes, and it is no longer tradable. One is included in our list, TRIL.L, the old RIC for Thomson Reuters, delisted in September 2009.
You can recognize delisted RICs in results through a special syntax: TRIL.L^I09
Here is the syntax: the original RIC (TRIL.L) followed by “^”, followed by a month code and a year code that indicate when the RIC was delisted. For equities the month code starts at “A” for January, so “I” is for September. The year code 09 means 2009.
Use cases
When converting an ISIN to RIC(s) there are 3 main use cases:
- You want the primary RIC
- You want the RIC(s) for a particular exchange (or currency), or a set of exchanges
- You want all the RICs
Another use case could be that you want to find the primary exchange.
There are different ways to go about these use cases.
Manually importing an instrument list file containing ISINs
Before moving to the API calls, I’d like to mention a nice DSS GUI capability. You can create an instrument list, and then populate it by importing a CSV file containing ISINs, optionally specifying one or more exchanges.
CSV file format (columns 3 to 5 are optional):
<IdentifierType>,<Identifier>[,<UserDefinedID 1>,<exchange list>,<UserDefinedID 2>]
Exchange list (column 4) allows choosing a list of exchanges. If it is empty the primary exchange will be taken. Format:
<ExchangeCode>[|<ExchangeCode>]
User defined IDs (columns 3 and 5) are optional tags you can add for your own usage (the DSS server will save them, but otherwise ignore them).
Example lines:
ISN,US4592001014,UserDef11,NYS|PSE|SWX,UserDef12
ISN,US4592001014,,PSE
ISN,US4592001014
ISN,GB00B29MWZ99
ISN,DE000C0JK7R7
ISN,DE0001135317
The first example line above will create 3 entries, one for each exchange code (NYS, PSE and SWX), all with the specified user IDs. The second will create 1 entry for exchange PSE, whereas the third will create an entry for the corresponding primary exchange (NYS, automatically populated).
An extraction referring to an instrument list containing an ISIN and exchange will return data for the RIC corresponding to that ISIN and exchange pair.
You cannot replicate this with the API, but as you will see from the following the API delivers many capabilities to convert ISINs to RIC or retrieve data using ISINs.
API use cases and calls summary
In a nutshell, here is the list of use cases with associated API calls.
| Use case | API call | Comment |
|---|---|---|
| Find primary exchange for an ISIN | InstrumentListValidateIdentifiersWithOptions | Delivers for each input ISIN the primary exchange. |
| Find primary RIC for an ISIN | TermsAndConditionsExtractionRequest | Delivers for each input ISIN the primary RIC. You can also retrieve the currency and exchange code. |
| Find RIC(s) for 1 or more exchanges for an ISIN | TermsAndConditionsExtractionRequest
Search
|
Delivers for each input ISIN and exchange the corresponding RIC; you can also retrieve the currency. The family of Search requests delivers for an input ISIN all RICs and corresponding exchanges; select from results the RICs for the exchanges of interest. |
| Directly run a data extraction request using an ISIN | You can extract data using the ISIN directly, optionally specifying the exchange. |
The details are covered in the next section.
Use cases and calls details
Let us look at the relevant API calls in detail, to get a better understanding of their capabilities.
Finding the primary exchange for an ISIN
A call to InstrumentListValidateIdentifiersWithOptions delivers for each input ISIN the primary exchange.
A single call suffices for multiple ISINs.
Here are the details of the API call:
Method: POST
Body:
{
"InputsForValidation": [
{ "Identifier": "US4592001014", "IdentifierType": "Isin" },
{ "Identifier": "GB00B29MWZ99", "IdentifierType": "Isin" },
{ "Identifier": "DE000C0JK7R7", "IdentifierType": "Isin" },
{ "Identifier": "DE0001135317", "IdentifierType": "Isin" }
],
"Options": {
"AllowDuplicateInstruments": false,
"AllowHistoricalInstruments": true,
"AllowInactiveInstruments": true,
"AllowOpenAccessInstruments": false,
"AllowUnsupportedInstruments": false,
"ExcludeFinrAsPricingSourceForBonds": false,
"UseConsolidatedQuoteSourceForCanada": false,
"UseConsolidatedQuoteSourceForUsa": false,
"UseDebtOverEquity": false,
"UseExchangeCodeInsteadOfLipper": false,
"UseUsQuoteInsteadOfCanadian": false
}
}
Response data:
{
"@odata.context": "https://selectapi.datascope.refinitiv.com/RestApi/v1/$metadata#DataScope.Select.Api.Extractions.SubjectLists.InstrumentsValidateIdentifiersResult",
"ValidatedInstruments": [
{
"Identifier": "US4592001014",
"IdentifierType": "Isin",
"Source": "NYS",
"Key": "VjF8MHgwMDAzZGQwMDEzNzlkNDYwfDB4MDAwM2RjMDA0YTAyNGZkOHxOWVN8RVFRVXxFUVRZfE9EU0h8RXx8SUJNLk58MDA3Nw",
"Description": "INTERNATIONAL BUSINESS MACHINES ORD",
"InstrumentType": "EquityQuote",
"Status": "Valid"
},
{
"Identifier": "GB00B29MWZ99",
"IdentifierType": "Isin",
"Source": "LSE",
"Key": "VjF8MHgwMDAzZGQwMDE0NzUyYzkzfDB4MDAwM2RjMDA0NzkxZGRkNHxMU0V8RVFRVXxFUVRZfE9EU0h8RXx8VFJJTC5MXkkwOXwwNjkx",
"Description": "THOMSON REUTERS PLC ORD",
"InstrumentType": "EquityQuote",
"Status": "Valid"
},
{
"Identifier": "DE000C0JK7R7",
"IdentifierType": "Isin",
"Source": "",
"Key": "VjF8MHgzMDAwMDAwMDAwMDAwMDAwfDB4MzAwMDAwMDAwMDAwMDAwMHx8fERFUlZ8RE9BRHxEfHx8",
"Description": "Historical Instrument",
"InstrumentType": "MortAggregate",
"Status": "Valid"
},
{
"Identifier": "DE0001135317",
"IdentifierType": "Isin",
"Source": "CPL",
"Key": "VjF8MHgwMDAzZTcwMDAzZTEzYTNjfDB4MDAwNDA1MDAzMDJmOTE4ZnxDUEx8R0NCRHxHT1ZUfEdCVU5EfEd8RXx8",
"Description": "DEGV 3.750 01/04/17 MATd",
"InstrumentType": "GovCorpBond",
"Status": "Valid"
}
],
"ValidationResult": {
"ValidInstrumentCount": 4,
"OpenAccessSegments": [],
"StandardSegments": [
{
"Code": "E",
"Description": "Equity",
"Count": 2
},
{
"Code": "G",
"Description": "GORP",
"Count": 1
}
],
"ValidationDuplicates": [],
"Messages": []
}
}
[…]
The response contains an object ValidatedInstruments, array that contains several objects (one for each input ISIN) containing the fields we are interested in: Identifier and Source.
Results: parsing the response allows you to build a list of ISINs and corresponding primary exchange codes:
- US4592001014 – NYS
- GB00B29MWZ99 – LSE
- DE000C0JK7R7 – N/A (there are rare cases where a value is not available)
- DE0001135317 – CPL
Notes:
- The request body contains a number of options. As we set "AllowInactiveInstruments": true and "AllowHistoricalInstruments": true the matured bond and the delisted instruments were delivered. If we had set these parameters to false no results would have been returned for the matured bond and the 2 expired instruments.
- To validate historical instruments you must also set "AllowHistoricalInstruments": true.
Finding the primary RIC for an ISIN
A TermsAndConditionsExtractionRequest delivers for each input ISIN the primary RIC (except if you specified the source, see next section). It is also possible to retrieve the currency and exchange code.
A single call suffices for multiple ISINs.
Method: POST
Endpoint: https://selectapi.datascope.refinitiv.com/RestApi/v1/Extractions/ExtractWithNotes
Body:
{
"ExtractionRequest": {
"@odata.type": "#DataScope.Select.Api.Extractions.ExtractionRequests.TermsAndConditionsExtractionRequest",
"ContentFieldNames": [
"RIC", "ISIN", "Currency Code", "Exchange Code", "Exchange Code List"
],
"IdentifierList": {
"@odata.type": "#DataScope.Select.Api.Extractions.ExtractionRequests.InstrumentIdentifierList",
"InstrumentIdentifiers": [
{ "Identifier": "US4592001014", "IdentifierType": "Isin", "Source": "PSE" },
{ "Identifier": "US4592001014", "IdentifierType": "Isin", "Source": "SWX" },
{ "Identifier": "US4592001014", "IdentifierType": "Isin" },
{ "Identifier": "GB00B29MWZ99", "IdentifierType": "Isin" },
{ "Identifier": "DE000C0JK7R7", "IdentifierType": "Isin" },
{ "Identifier": "DE0001135317", "IdentifierType": "Isin" }
],
"ValidationOptions": {
"AllowHistoricalInstruments": true,
"AllowInactiveInstruments": true,
"AllowOpenAccessInstruments": false
},
"UseUserPreferencesForValidationOptions": false
}
}
}
Response:
Depending on the request size the response will either contain the data, or (if it takes more than 30 seconds) it will be empty, and the header will contain a location URL. A subsequent GET request to the location URL will deliver the data when it is ready. For details see REST API Tutorial 7: On Demand T&C extraction.
Response data:
{
"@odata.context": "https://selectapi.datascope.refinitiv.com/RestApi/v1/$metadata#DataScope.Select.Api.Extractions.ExtractionRequests.ExtractionResult",
"Contents": [
{
"IdentifierType": "Isin",
"Identifier": "US4592001014",
"RIC": "IBM.P",
"ISIN": "US4592001014",
"Currency Code": "USD",
"Exchange Code": "PSE",
"Exchange Code List": "ADC,ARC,ASE,ATH,BAT,BCO,BCU,BEC,BER,BIV,BOS,BRN,BRU,BT1,BTY,BZX,CIN,DEA,DEU,DEX,DUS,ETX,EXT,FRA,GER,GTX,HAM,HAN,IEX,LMA,LSE,LTE,MCX,MEX,MID,MMX,MPE,MUN,MXQ,NAA,NBN,NQT,NYQ,NYS,PSE,QTX,SGO,STU,SWX,TBE,TDG,THM,TRQ,TRU,TUP,VIA,VIE,XBO,XDS,XPH"
},
{
"IdentifierType": "Isin",
"Identifier": "US4592001014",
"RIC": "IBM.S",
"ISIN": "US4592001014",
"Currency Code": "CHF",
"Exchange Code": "SWX",
"Exchange Code List": "ADC,ARC,ASE,ATH,BAT,BCO,BCU,BEC,BER,BIV,BOS,BRN,BRU,BT1,BTY,BZX,CIN,DEA,DEU,DEX,DUS,ETX,EXT,FRA,GER,GTX,HAM,HAN,IEX,LMA,LSE,LTE,MCX,MEX,MID,MMX,MPE,MUN,MXQ,NAA,NBN,NQT,NYQ,NYS,PSE,QTX,SGO,STU,SWX,TBE,TDG,THM,TRQ,TRU,TUP,VIA,VIE,XBO,XDS,XPH"
},
{
"IdentifierType": "Isin",
"Identifier": "US4592001014",
"RIC": "IBM.N",
"ISIN": "US4592001014",
"Currency Code": "USD",
"Exchange Code": "NYS",
"Exchange Code List": "ADC,ARC,ASE,ATH,BAT,BCO,BCU,BEC,BER,BIV,BOS,BRN,BRU,BT1,BTY,BZX,CIN,DEA,DEU,DEX,DUS,ETX,EXT,FRA,GER,GTX,HAM,HAN,IEX,LMA,LSE,LTE,MCX,MEX,MID,MMX,MPE,MUN,MXQ,NAA,NBN,NQT,NYQ,NYS,PSE,QTX,SGO,STU,SWX,TBE,TDG,THM,TRQ,TRU,TUP,VIA,VIE,XBO,XDS,XPH"
},
{
"IdentifierType": "Isin",
"Identifier": "GB00B29MWZ99",
"RIC": "TRIL.L^I09",
"ISIN": "GB00B29MWZ99",
"Currency Code": "GBp",
"Exchange Code": "LSE",
"Exchange Code List": null
},
{
"IdentifierType": "Isin",
"Identifier": "DE000C0JK7R7",
"RIC": null,
"ISIN": null,
"Currency Code": null,
"Exchange Code": null,
"Exchange Code List": null
},
{
"IdentifierType": "Isin",
"Identifier": "DE0001135317",
"RIC": null,
"ISIN": "DE0001135317",
"Currency Code": "EUR",
"Exchange Code": "EJV",
"Exchange Code List": null
}
],
"Notes": [
"Extraction Services Version 15.1.42548 (b07dc8487823), Built Aug 4 2021 14:50:22\r\nProcessing started at 09/15/2021 10:23:19.\r\nUser ID: 9008895\r\nExtraction ID: 544738272\r\nCorrelation ID: CiD/9008895/AAAAAA.07b5a2abf40d2204/RA/EXT.544738272\r\nSchedule: _OnD_0x07b5a2abf41d2204 (ID = 0x07b5a2abf83d2204)\r\nInput List (6 items): _OnD_0x07b5a2abf41d2204 (ID = 07b5a2abf69d2204) Created: 09/15/2021 10:23:17 Last Modified: 09/15/2021 10:23:18\r\nSchedule Time: 09/15/2021 10:23:18\r\nReport Template (11 fields): _OnD_0x07b5a2abf41d2204 (ID = 0x07b5a2abf42d2204) Created: 09/15/2021 10:23:17 Last Modified: 09/15/2021 10:23:17\r\n(ISN,DE0001135317,EJV) is inactive.\r\nProcessing completed successfully at 09/15/2021 10:23:19, taking 0.811 Secs.\r\nExtraction finished at 09/15/2021 09:23:19 UTC, with servers: x11n02, QSHC16 (0.2 secs), QSSHA1 (0.0 secs)\r\nUsage Summary for User 9008895, Client 65508, Template Type Terms and Conditions\r\nBase Usage\r\n Instrument Instrument Terms Price\r\n Count Type Subtype Source Source\r\n------- ----------------------------------- ---------------------------- -------------- ----------------------------------------\r\n 4 Equities N/A N/A\r\n 1 Govt/Treasury/Central Bank N/A N/A\r\n-------\r\n 5 Total instruments charged.\r\n 1 Instrument with no reported data.\r\n=======\r\n 6 Instruments in the input list.\r\nWriting RIC maintenance report.\r\n",
"Identifier,IdentType,Source,RIC,RecordDate,MaintType,OldValue,NewValue,Factor,FactorType\r\n"
]
}
The response contains an object Contents, array that contains several objects (one for each input ISIN) containing the field we are interested in: RIC. In this example we also include the Currency Code and Exchange Code as control elements.
Results: parsing the response allows us to build a list of ISINs and corresponding primary RIC, primary exchange and currency:
- US4592001014 – IBM.N – NYS – USD
- GB00B29MWZ99 – TRIL.L^I09 – LSE – GBp
- DE000C0JK7R7 – null – null – null
- DE0001135317 – null – CPL – EUR
Notes on the expired instruments:
- The syntax of TRIL.L^I09 shows it is a delisted instrument.
- No primary RIC is delivered for the matured bond, because it is no longer quoted.
- No data is delivered for the future derivative, because it is no longer quoted.
For more information on the Terms and Conditions extraction, see REST API Tutorial 7: On Demand T&C extraction.
Finding the RIC(s) for one or more exchanges for an ISIN
The TermsAndConditionsExtractionRequest we saw in the previous section defaults to the primary RIC. But you can add to each input ISIN a specific exchange; the result will then contain the corresponding RIC.
To get results for several exchanges, you need one entry per source.
For instance, if you want to convert the ISIN US4592001014 to get the RICs on the PSE and SWX exchanges, as well as the primary RIC, you would set the following in the InstrumentIdentifiers:
{ "Identifier": "US4592001014", "IdentifierType": "Isin", "Source": "PSE" },
{ "Identifier": "US4592001014", "IdentifierType": "Isin", "Source": "SWX" },
{ "Identifier": "US4592001014", "IdentifierType": "Isin" },
Results: this returns the following RICs: IBM.P, IBM.S and IBM.N.
The above scenario assumes you know exactly what exchanges you want. If you do not, you might want to use a Search.
The family of Search requests delivers for an input ISIN all RICs and corresponding exchanges, from the results you can select those for exchanges of interest.
You need to run one call per ISIN.
The various search requests have different filtering capabilities, for example:
- InstrumentSearch is the generic search; it allows filtering by instrument type.
- EquitySearch allows filtering by 1 currency and/or several exchanges. Since version 11.3 the result contains the exchange and currency codes.
- FuturesAndOptionsSearch allows filtering by a combination of 1 currency, several exchanges, expiration date and/or strike price.
- GovCorpSearch allows filtering by a combination of asset statuses (where matured is MAT), several currencies, dates and more.
- Etc.
This allows you to find the RICs for specific exchanges.
The set of fields that are returned in the response is not configurable. For each result it is recommended to check the value of field IdentifierType, because in cases where a RIC is not available a different identifier type might be returned, as illustrated by our last search example below (the GovCorpSearch).
No RICs are delivered if the instrument is no longer quoted.
Let us see these calls in more detail.
Basic instrument search
InstrumentSearch allows filtering by InstrumentTypeGroup.
Method: POST
Endpoint: https://selectapi.datascope.refinitiv.com/RestApi/v1/Search/InstrumentSearch
Body:
{
"SearchRequest": {
"InstrumentTypeGroups": [
"CollatetizedMortgageObligations", "Commodities", "Equities", "Funds",
"FuturesAndOptions", "GovCorp", "Money", "MortgageBackedSecurities",
"Municipals"
],
"IdentifierType": "Isin",
"Identifier": "US4592001014",
"PreferredIdentifierType": "Ric"
}
}
Response data:
{
"@odata.context": "https://selectapi.datascope.refinitiv.com/RestApi/v1/$metadata#Collection(DataScope.Select.Api.Content.ValidatedInstrument)",
"value": [
{
"Identifier": "IBM.LM",
"IdentifierType": "Ric",
"Source": "LMA",
"Key": "VjF8MHgwMDAzZGQwMDEzNzlkNDYwfDB4MDAwM2RjMDAzZGNiNDE2OHxMTUF8RVFRVXxFUVRZfE9EU0h8RXx8SUJNLkxNfDAzOTM",
"Description": "INTERNATIONAL BUSINESS MACHINES ORD",
"InstrumentType": "EquityQuote",
"Status": "Valid"
},
[…]
{
"Identifier": "IBM.N",
"IdentifierType": "Ric",
"Source": "NYS",
"Key": "VjF8MHgwMDAzZGQwMDEzNzlkNDYwfDB4MDAwM2RjMDA0YTAyNGZkOHxOWVN8RVFRVXxFUVRZfE9EU0h8RXx8SUJNLk58MDA3Nw",
"Description": "INTERNATIONAL BUSINESS MACHINES ORD",
"InstrumentType": "EquityQuote",
"Status": "Valid"
},
[…]
{
"Identifier": "IBMl.BCU",
"IdentifierType": "Ric",
"Source": "BCU",
"Key": "VjF8MHgwMDAzZGQwMDEzNzlkNDYwfDB4MDAxMDBiMDAxZjBjNmFiZHxCQ1V8RVFRVXxFUVRZfE9EU0h8RXx8SUJNbC5CQ1V8NDEwOA",
"Description": "INTERNATIONAL BUSINESS MACHINES ORD",
"InstrumentType": "EquityQuote",
"Status": "Valid"
}
]
}
The response contains an object value, array that contains one or more objects (one for each RIC that maps to the input ISIN) containing the fields we are interested in: Identifier and Source (i.e. the venue / exchange).
Results: parsing the response allows us to build a list of all the RICs and corresponding source (exchange):
- US4592001014 – more than 50 results.
Note: the primary RIC cannot be distinguished from the others. - GB00B29MWZ99 – no results
- DE000C0JK7R7 – no results
- DE0001135317 – no results
There are no results for the delisted instruments and the matured bond, because they are no longer quoted.
For more information on instrument search refer to REST API Tutorial 11: Search by Instrument.
Equity search
EquitySearch allows filtering by 1 currency and/or several exchanges.
Method: POST
Endpoint: https://selectapi.datascope.refinitiv.com/RestApi/v1/Search/EquitySearch
Body:
{
"SearchRequest": {
"AssetStatus": "Active",
"AssetCategoryCodes": null,
"SubTypeCodes": null,
"CurrencyCodes": [ "USD" ],
"CompanyName": null,
"Description": null,
"DomicileCodes": null,
"ExchangeCodes": [ "NAS", "NYS", "GSM", "NSM", "SWX" ],
"FairValueIndicator": null,
"FileCodes": null,
"GicsCodes": null,
"OrgId": null,
"Ticker": null,
"Identifier": "US4592001014",
"IdentifierType": "Isin",
"PreferredIdentifierType": "Ric"
}
}
Note: this example illustrates how additional filtering can be done on one single currency code (multiple codes are not supported) and one or more exchange codes.
Response data:
{
"@odata.context": "https://selectapi.datascope.refinitiv.com/RestApi/v1/$metadata#Collection(DataScope.Select.Api.Search.EquitySearchResult)",
"value": [
{
"Identifier": "IBM.N",
"IdentifierType": "Ric",
"Source": "NYS",
"Key": "VjF8MHgwMDAzZGQwMDEzNzlkNDYwfDB4MDAwM2RjMDA0YTAyNGZkOHxOWVN8RVFRVXxFUVRZfE9EU0h8RXx8SUJNLk58MDA3Nw",
"Description": "INTERNATIONAL BUSINESS MACHINES ORD",
"InstrumentType": "EquityQuote",
"Status": "Valid",
"DomicileCode": "US",
"CurrencyCodes": "USD",
"SubTypeCode": "ODSH",
"AssetStatus": "Active",
"IssuerName": "IBM",
"IssuerOrgId": "18228",
"Exchange": "NYS",
"FileCode": "77"
},
{
"Identifier": "IBMUSD.S",
"IdentifierType": "Ric",
"Source": "SWX",
"Key": "VjF8MHgwMDAzZGQwMDEzNzlkNDYwfDB4MDAxMDBiMDAxMjkwM2NiNXxTV1h8RVFRVXxFUVRZfE9EU0h8RXx8SUJNVVNELlN8MDQ3Nw",
"Description": "INTERNATIONAL BUSINESS MACHINES ORD",
"InstrumentType": "EquityQuote",
"Status": "Valid",
"DomicileCode": "US",
"CurrencyCodes": "USD",
"SubTypeCode": "ODSH",
"AssetStatus": "Active",
"IssuerName": "IBM",
"IssuerOrgId": "18228",
"Exchange": "SWX",
"FileCode": "477"
}
]
}
The response contains an object value, array that contains one or more objects (one for each RIC that maps to the input ISIN) containing the fields we are interested in: Identifier and Source (i.e. the venue / exchange). In version 11.3 several fields were added to the output, among which Exchange and CurrencyCodes.
Results: parsing the response allows us to build a list of all the equity RICs (with corresponding exchange) for the selected exchanges and currency, but only for instruments that are still quoted:
- US4592001014 – IBM.N (NYS) and IBMUSD.S (SWX)
- GB00B29MWZ99 – no results (for a search on LSE), no longer quoted.
There is no point using EquitySearch for DE000C0JK7R7 and DE0001135317 as they are not equities, no results will be returned.
For more information on equity search refer to REST API Tutorial 12: Search for an Equity.
Futures and Options search
FuturesAndOptionsSearch allows filtering by a combination of 1 currency, several exchanges, expiration date and/or strike price.
Method: POST
Endpoint: https://selectapi.datascope.refinitiv.com/RestApi/v1/Search/FuturesAndOptionsSearch
Body:
{
"SearchRequest": {
"FileCodes": null,
"CurrencyCodes": [ "EUR" ],
"ExchangeCodes": [ "EUX", "DTB" ],
"StrikePrice": null,
"ExpirationDate": {
"@odata.type": "#DataScope.Select.Api.Search.DateValueComparison",
"ComparisonOperator": "GreaterThanEquals",
"Value": "2016-12-31T00:00:00.000Z"
},
"IdentifierType": "Isin",
"Identifier": "DE000C0JK7R7",
"PreferredIdentifierType": "Ric",
"UnderlyingRic": null
}
}
Note: this example illustrates how additional filtering can be done on one single currency code (multiple codes are not supported), on one or more exchange codes, and on the expiration date. We did not add a filter on strike price, it would not apply to this ISIN.
Response data:
{
"@odata.context": "https://selectapi.datascope.refinitiv.com/RestApi/v1/$metadata#Collection(DataScope.Select.Api.Search.FuturesAndOptionsSearchResult)",
"value": []
}
The response is empty because the instrument is no longer quoted. If it was quoted then the response would contain an object value, array that would contain one or more objects (one for each RIC that maps to the input ISIN) containing the fields we are interested in: Identifier and Source (i.e. the venue / exchange).
Results: parsing the response allows us to build a list of all the future and option RICs (with corresponding exchange) for the selected exchanges, currency and expiration date, but only for instruments that are still quoted.
There is no point using FutureAndOptionSearch for US4592001014, GB00B29MWZ99 and DE0001135317 as they are not futures or options, no results will be returned.
For more information on future and option search refer to REST API Tutorial 13: Search for a Future or Option.
Government Corporates search
GovCorpSearch allows filtering by a combination of asset statuses (where MAT stands for matured), several currencies, dates and more.
Method: POST
Endpoint: https://selectapi.datascope.refinitiv.com/RestApi/v1/Search/GovCorpSearch
Body:
{
"SearchRequest": {
"FileCodes": null,
"CurrencyCodes": [ "EUR" ],
"ExchangeCodes": [ "EUX", "DTB" ],
"StrikePrice": null,
"ExpirationDate": {
"@odata.type": "#DataScope.Select.Api.Search.DateValueComparison",
"ComparisonOperator": "GreaterThanEquals",
"Value": "2016-12-31T00:00:00.000Z"
},
"IdentifierType": "Isin",
"Identifier": "DE000C0JK7R7",
"PreferredIdentifierType": "Ric",
"UnderlyingRic": null
}
}
Note: this example illustrates how additional filtering can be done on one single currency code (multiple codes are not supported), on one or more exchange codes, and on the expiration date. We did not add a filter on strike price, it would not apply to this ISIN.
Response data:
{
"@odata.context": "https://selectapi.datascope.refinitiv.com/RestApi/v1/$metadata#Collection(DataScope.Select.Api.Search.FuturesAndOptionsSearchResult)",
"value": []
}
The response is empty because the instrument is no longer quoted. If it was quoted then the response would contain an object value, array that would contain one or more objects (one for each RIC that maps to the input ISIN) containing the fields we are interested in: Identifier and Source (i.e. the venue / exchange).
Results: parsing the response allows us to build a list of all the future and option RICs (with corresponding exchange) for the selected exchanges, currency and expiration date, but only for instruments that are still quoted.
There is no point using FutureAndOptionSearch for US4592001014, GB00B29MWZ99 and DE0001135317 as they are not futures or options, no results will be returned.
For more information on future and option search refer to REST API Tutorial 13: Search for a Future or Option.
Government Corporates search
GovCorpSearch allows filtering by a combination of asset statuses (where MAT stands for matured), several currencies, dates and more.
Method: POST
Endpoint: https://selectapi.datascope.refinitiv.com/RestApi/v1/Search/GovCorpSearch
Body:
{
"SearchRequest": {
"AssetStatuses": ["CLD", "CAN", "DFS", "RDM", "EXC", "MAT", "FNG", "DEF", "ISS", "LIQ", "NAC", "PRE", "PUT", "RPN", "RMK", "RBM", "FDD", "REP", "RES", "TEN", "TBC", "TBE", "TBI", "TBP", "TBR", "TBB", "WHN"],
"Coupon": null,
"CurrencyCodes": [ "EUR", "USD" ],
"Group": { "Agency": true, "Government": true, "Corporate": true, "Supra": true },
"MoodyRatingsCodes": null,
"StandardPoorsRatingsCodes": null,
"Callable": false,
"Convertable": false,
"Extendable": false,
"Putable": false,
"Sinkable": false,
"IssueDate": null,
"MaturityDate": null,
"NextPayDate": null,
"Identifier": "DE0001135317",
"IdentifierType": "Isin",
"PreferredIdentifierType": "Ric"
}
}
Note: this example illustrates some of the filtering capabilities.
Response data:
There are 120 results:
{
"@odata.context": "https://selectapi.datascope.refinitiv.com/RestApi/v1/$metadata#Collection(DataScope.Select.Api.Content.ValidatedInstrument)",
"value": [
{
"Identifier": "DE0001135317",
"IdentifierType": "Isin",
"Source": "EJV",
"Key": "VjF8MHgwMDAzZTcwMDAzZTEzYTNjfDB4MDAwNDA1MDAzMDJmNzE2ZnxFSlZ8R0NCRHx8fEd8RXx8R09SUA",
"Description": "DEGV 3.750 01/04/17 MATd",
"InstrumentType": "GovCorpBond",
"Status": "Valid"
},
{
"Identifier": "DE0001135317",
"IdentifierType": "Isin",
"Source": "AAF",
"Key": "VjF8MHgwMDAzZTcwMDAzZTEzYTNjfDB4MDAwNDA1MDAzMDJmNzI2Y3xBQUZ8R0NCRHx8fEd8RXx8",
"Description": "DEGV 3.750 01/04/17 MATd",
"InstrumentType": "GovCorpBond",
"Status": "Valid"
},
[…]
{
"Identifier": "DE0001135317=HSBP",
"IdentifierType": "Ric",
"Source": "HSP",
"Key": "VjF8MHgwMDAzZTcwMDAzZTEzYTNjfDB4MDAxMDJjYWE4NmJiMDdhY3xIU1B8R0NCRHx8fEd8RXxERTAwMDExMzUzMTc9SFNCUHw",
"Description": "DEGV 3.750 01/04/17 MATd",
"InstrumentType": "GovCorpBond",
"Status": "Valid"
}
]
}
The response contains an object value, array that contains one or more objects (one for each RIC that maps to the input ISIN) containing the fields we are interested in: Identifier and Source (i.e. the venue / exchange).
Results: RICs are not always available for a particular instrument, so the response contains a set of ISINs (always the same, with one record per source) and a set of RICs (in this case a mix of contributor and exchange RICs). This is why we recommend checking the value of field IdentifierType, to verify if the returned identifier is a RIC, or if a different identifier type was returned because no RIC was available.
There is no point using GovCorpSearch for US4592001014, GB00B29MWZ99 and DE000C0JK7R7 as they are not bonds, no results will be returned.
Directly running a data extraction request using an ISIN
A DSS data extraction can be done using the ISIN directly. You can add to each input ISIN a specific exchange. The result will then contain data for the corresponding RIC. If you do not mention the exchange, the result will contain data for the primary RIC.
If you want results for several exchanges, you need one entry per source.
For instance, if you want to retrieve data for ISIN US4592001014 on the PSE and SWX exchanges, as well as the primary exchange, you could set the following in the InstrumentIdentifiers:
{ "Identifier": "US4592001014", "IdentifierType": "Isin", "Source": "PSE" },
{ "Identifier": "US4592001014", "IdentifierType": "Isin", "Source": "SWX" },
{ "Identifier": "US4592001014", "IdentifierType": "Isin" },
Results: this will return data for the following RICs: IBM.P, IBM.S and IBM.N.
To see the details of the ISIN to RIC mapping you can include the following fields in the request: RIC, ISIN, Currency Code and Exchange Code. But we do not recommend adding static data to the output field list, because this data will be delivered for every single output record, resulting in slower processing due to useless duplication and information treatment.
As an example, let us look at an End of Day pricing request.
End of Day Pricing request
The EndOfDayPricingExtractionRequest delivers for each input ISIN the data for the exchange you specified, or for the primary RIC if you did not mention the exchange. You can also retrieve the RIC, currency and exchange code, asset and trading status, expiration date, etc.
The following query specifies the exchange for the first ISIN, and defaults to the primary for the others:
Method: POST
Endpoint: https://selectapi.datascope.refinitiv.com/RestApi/v1/Extractions/ExtractWithNotes
Body:
{
"ExtractionRequest": {
"@odata.type": "#DataScope.Select.Api.Extractions.ExtractionRequests.EndOfDayPricingExtractionRequest",
"ContentFieldNames": [
"ISIN", "RIC", "Underlying RIC", "Trading Status", "Asset Status",
"Currency Code", "Exchange Code", "Expiration Date",
"Trade Date", "Open Price", "High Price", "Low Price", "Close Price", "Volume"
],
"IdentifierList": {
"@odata.type": "#DataScope.Select.Api.Extractions.ExtractionRequests.InstrumentIdentifierList",
"InstrumentIdentifiers": [
{ "Identifier": "US4592001014", "IdentifierType": "Isin", "Source": "PSE" },
{ "Identifier": "US4592001014", "IdentifierType": "Isin", "Source": "SWX" },
{ "Identifier": "US4592001014", "IdentifierType": "Isin" },
{ "Identifier": "GB00B29MWZ99", "IdentifierType": "Isin" },
{ "Identifier": "DE000C0JK7R7", "IdentifierType": "Isin" },
{ "Identifier": "DE0001135317", "IdentifierType": "Isin" }],
"ValidationOptions": { "AllowHistoricalInstruments": true },
"UseUserPreferencesForValidationOptions": false
},
"Condition": null
}
}
Response:
Depending on the request size the response will either contain the data, or (if it takes more than 30 seconds) the response will be empty, and the header will contain a location URL. A subsequent GET request to the location URL will deliver the data. For details see REST API Tutorial 2: On Demand End of Day extraction.
Response data:
{
"@odata.context": "https://selectapi.datascope.refinitiv.com/RestApi/v1/$metadata#DataScope.Select.Api.Extractions.ExtractionRequests.ExtractionResult",
"Contents": [
{
"IdentifierType": "Isin",
"Identifier": "US4592001014",
"ISIN": "US4592001014",
"RIC": "IBM.P",
"Underlying RIC": null,
"Trading Status": 1,
"Asset Status": "ISS",
"Currency Code": "USD",
"Exchange Code": "PSE",
"Expiration Date": null,
"Trade Date": "2021-09-14",
"Open Price": 138.4,
"High Price": 138.5,
"Low Price": 135.35,
"Close Price": 136.23,
"Volume": 276241
},
{
"IdentifierType": "Isin",
"Identifier": "US4592001014",
"ISIN": "US4592001014",
"RIC": "IBM.S",
"Underlying RIC": null,
"Trading Status": 1,
"Asset Status": "ISS",
"Currency Code": "CHF",
"Exchange Code": "SWX",
"Expiration Date": null,
"Trade Date": "2021-09-14",
"Open Price": null,
"High Price": null,
"Low Price": null,
"Close Price": null,
"Volume": null
},
{
"IdentifierType": "Isin",
"Identifier": "US4592001014",
"ISIN": "US4592001014",
"RIC": "IBM.N",
"Underlying RIC": null,
"Trading Status": 1,
"Asset Status": "ISS",
"Currency Code": "USD",
"Exchange Code": "NYS",
"Expiration Date": null,
"Trade Date": "2021-09-14",
"Open Price": 138.57,
"High Price": 138.57,
"Low Price": 135.34,
"Close Price": 136.22,
"Volume": 1231032
},
{
"IdentifierType": "Isin",
"Identifier": "GB00B29MWZ99",
"ISIN": "GB00B29MWZ99",
"RIC": "TRIL.L^I09",
"Underlying RIC": null,
"Trading Status": 0,
"Asset Status": "NAC",
"Currency Code": "GBp",
"Exchange Code": "LSE",
"Expiration Date": null,
"Trade Date": "2009-09-09",
"Open Price": 1858,
"High Price": 1893,
"Low Price": 1815,
"Close Price": 1892,
"Volume": null
},
{
"IdentifierType": "Isin",
"Identifier": "DE000C0JK7R7",
"ISIN": null,
"RIC": null,
"Underlying RIC": null,
"Trading Status": null,
"Asset Status": null,
"Currency Code": null,
"Exchange Code": null,
"Expiration Date": null,
"Trade Date": null,
"Open Price": null,
"High Price": null,
"Low Price": null,
"Close Price": null,
"Volume": null
},
{
"IdentifierType": "Isin",
"Identifier": "DE0001135317",
"ISIN": "DE0001135317",
"RIC": null,
"Underlying RIC": null,
"Trading Status": 0,
"Asset Status": "MAT",
"Currency Code": "EUR",
"Exchange Code": "EJV",
"Expiration Date": null,
"Trade Date": null,
"Open Price": null,
"High Price": null,
"Low Price": null,
"Close Price": null,
"Volume": null
}
],
"Notes": [
"Extraction Services Version 15.1.42548 (b07dc8487823), Built Aug 4 2021 14:50:22\r\nHoliday Rollover of Universal Close Price waived.\r\nProcessing started at 09/15/2021 10:26:52.\r\nUser ID: 9008895\r\nExtraction ID: 544738594\r\nCorrelation ID: CiD/9008895/AAAAAA.07b5bd8cd75d223d/RA/EXT.544738594\r\nSchedule: _OnD_0x07b5bd8cd76d223d (ID = 0x07b5bd8cd9dd223d)\r\nInput List (6 items): _OnD_0x07b5bd8cd76d223d (ID = 07b5bd8cd81d223d) Created: 09/15/2021 10:26:49 Last Modified: 09/15/2021 10:26:49\r\nSchedule Time: 09/15/2021 10:26:49\r\nReport Template (20 fields): _OnD_0x07b5bd8cd76d223d (ID = 0x07b5bd8cd77d223d) Created: 09/15/2021 10:26:49 Last Modified: 09/15/2021 10:26:49\r\n(ISN,DE0001135317,EJV) is inactive.\r\nProcessing completed successfully at 09/15/2021 10:26:53, taking 3.05 Secs.\r\nExtraction finished at 09/15/2021 09:26:53 UTC, with servers: x08i02, QSHC16 (0.4 secs), QSSHA1 (0.0 secs)\r\nUsage Summary for User 9008895, Client 65508, Template Type EOD Pricing\r\nBase Usage\r\n Instrument Instrument Terms Price\r\n Count Type Subtype Source Source\r\n------- ----------------------------------- ---------------------------- -------------- ----------------------------------------\r\n 4 Equities N/A N/A\r\n 1 Govt/Treasury/Central Bank N/A N/A\r\n-------\r\n 5 Total instruments charged.\r\n 1 Instrument with no reported data.\r\n=======\r\n 6 Instruments in the input list.\r\nNo Evaluated Pricing Service complex usage to report -- 6 Instruments in the input list had no reported data.\r\nWriting RIC maintenance report.\r\n",
"Identifier,IdentType,Source,RIC,RecordDate,MaintType,OldValue,NewValue,Factor,FactorType\r\n"
]
}
Results: the response contains the data for IBM on the PSE exchange. For the other ISINs it contains the data for the primary exchange, and, where available, the corresponding primary RIC, primary exchange and currency:
- US4592001014 / PSE – IBM.P – PSE – USD
- US4592001014 – IBM.N – NYS – USD
- GB00B29MWZ99 – TRIL.L^I09 – LSE – GBp
- DE000C0JK7R7 – null – null – null
- DE0001135317 – null – CPL - EUR
Notes:
- Asset Status “ISS” means “Issued”, “NAC” means “Not Active”, “MAT” means “Expired/Matured”.
- Trading Status is 1 if the instrument is currently traded, 0 otherwise.
Notes on the expired instruments:
- The syntax of TRIL.L^I09 shows it is a delisted instrument.
- No data nor primary RIC is delivered for the future derivative and the matured bond, because they are no longer quoted. The bond's asset status tells us the instrument has matured.
Conclusions
In this article we saw several DSS REST API calls that allow us to find the primary exchange for an ISIN, the primary RIC for an ISIN, a RIC for a specific ISIN and exchange, and all the RICs for an ISIN. The last capability allows us to select a subset of RICs for specific exchanges (and / or currencies) of interest. We also saw that we can directly retrieve data using ISINs (and exchanges).
