| Last update | Nov 2023 |
| Environment | Any |
| Language | Any HTTP is supported |
| Compilers | None |
| Prerequisites | DSS login, internet access |
| Source code | Below |
This tutorial explains how to:
If you do not know what field lists are available, you can request a list of those available.
The report template type must be specified in the path. As we want ownership data we set a value of Owners. The preceding tutorials show other possibilities.
Note: for all requests we need a user token. This was retrieved in Tutorial 1.
URL:
https://selectapi.datascope.refinitiv.com/RestApi/v1/Extractions/GetValidContentFieldTypes(ReportTemplateType=DataScope.Select.Api.Extractions.ReportTemplates.ReportTemplateTypes'Owners')
Method: GET
Headers:
Prefer: respond-async
Authorization: Token F0ABE9A3FFF2E02E10AE2765ED872C59B8CC3B40EBB61B30E295E71DE31C254B8648DB9434C2DF9299FDC668AA123501F322D99D45C8B93438063C912BC936C7B87062B0CF812138863F5D836A7B31A32DCA67EF07B3B50B2FC4978DF6F76784FDF35FCB523A8430DA93613BC5730CDC310D4D241718F9FC3F2E55465A24957CC287BDEC79046B31AD642606275AEAD76318CB221BD843348E1483670DA13968D8A242AAFCF9E13E23240C905AE46DED9EDCA9BB316B4C5C767B18DB2EA7ADD100817ADF059D01394BC6375BECAF6138C25DBA57577F0061
If the token is valid, this is the response we get:
Status: 200 OK
Relevant headers:
Content-Type: application/json; charset=utf-8
Body:
There are more than 60 values in the response. Here is the beginning of the response:
{
"@odata.context": "https://selectapi.datascope.refinitiv.com/RestApi/v1/$metadata#ContentFieldTypes",
"value": [
{
"Code": "OWN.Asset ID",
"Name": "Asset ID",
"Description": "Unique system-assigned identifier for the instrument",
"FormatType": "Text",
"FieldGroup": " "
},
{
"Code": "OWN.Asset Status",
"Name": "Asset Status",
"Description": "Code representing the status of the instrument",
"FormatType": "Text",
"FieldGroup": " "
},
{
"Code": "OWN.Asset Status Description",
"Name": "Asset Status Description",
"Description": "Description of Asset Status code",
"FormatType": "Text",
"FieldGroup": " "
},
{
"Code": "OWN.Asset SubType",
"Name": "Asset SubType",
"Description": "Code representing the asset sub classification within the security type code",
"FormatType": "Text",
"FieldGroup": " "
},
{
"Code": "OWN.Asset Subtype Country Code",
"Name": "Asset Subtype Country Code",
"Description": "Countries to which the Asset Subtype apply",
"FormatType": "Text",
"FieldGroup": " "
},
This goes on with all the other available fields. Here is the last part:
{
"Code": "OWN.Value Changed",
"Name": "Value Changed",
"Description": "Dollar value of shares changed",
"FormatType": "Number",
"FieldGroup": " "
},
{
"Code": "OWN.Value Held",
"Name": "Value Held",
"Description": "Dollar value of shares held",
"FormatType": "Number",
"FieldGroup": " "
},
{
"Code": "OWN.Wertpapier",
"Name": "Wertpapier",
"Description": "Issue-level code used for identifying instruments in Germany",
"FormatType": "Text",
"FieldGroup": " "
}
]
}
The result contains the field code, name, a description, field type (number, text, date) and group. Use this to choose the field names you want. In the next step we will make a request for data, using some data fields we chose.
This is similar to the previous tutorials, as it is also an On Demand extraction request.
The body of the request must mention it is an extraction request. It contains several parts:
Note: for all requests we need to include a user token in the header of our request. This was retrieved in Tutorial 1.
URL:
https://selectapi.datascope.refinitiv.com/RestApi/v1/Extractions/ExtractWithNotes
Method: POST
Headers:
Prefer: respond-async
Content-Type: application/json
Authorization: Token F0ABE9A3FFF2E02E10AE2765ED872C59B8CC3B40EBB61B30E295E71DE31C254B8648DB9434C2DF9299FDC668AA123501F322D99D45C8B93438063C912BC936C7B87062B0CF812138863F5D836A7B31A32DCA67EF07B3B50B2FC4978DF6F76784FDF35FCB523A8430DA93613BC5730CDC310D4D241718F9FC3F2E55465A24957CC287BDEC79046B31AD642606275AEAD76318CB221BD843348E1483670DA13968D8A242AAFCF9E13E23240C905AE46DED9EDCA9BB316B4C5C767B18DB2EA7ADD100817ADF059D01394BC6375BECAF6138C25DBA57577F0061
Body:
{
"ExtractionRequest": {
"@odata.type": "#DataScope.Select.Api.Extractions.ExtractionRequests.OwnershipExtractionRequest",
"ContentFieldNames": [
"Asset ID",
"Asset Status",
"Asset Status Description",
"Change Sign",
"Common Code",
"Currency Code",
"Currency Code Description",
"CUSIP",
"File Code",
"Issuer ID",
"Issuer Name",
"Issuer OrgID",
"RCP ID",
"Issuer Short Name",
"Legal Entity OrgID",
"Holdings Previous Report Date",
"Holdings Report Date",
"Owner Country",
"Owner ID",
"Owner Name",
"Owner Type",
"Owner Type Description",
"Percent of Shares Outstanding",
"Primary Issue Flag",
"Security Description",
"Shares Held",
"Value Held",
"Shares Changed",
"Value Changed"
],
"IdentifierList": {
"@odata.type": "#DataScope.Select.Api.Extractions.ExtractionRequests.InstrumentIdentifierList",
"InstrumentIdentifiers": [
{ "Identifier": "438516AC0", "IdentifierType": "Cusip" },
{ "Identifier": "IBM.N", "IdentifierType": "Ric" }
]
}
}
}
If the token is valid, and there is no timeout (these requests can take time as they generate very large data sets), the data will be delivered.
This is the response we get:
Status: 200 OK
Relevant headers:
Content-Type: application/json; charset=utf-8
Body:
There are more than 5000 values in the response. Here is the beginning of the response:
{
"@odata.context": "https://selectapi.datascope.refinitiv.com/RestApi/v1/$metadata#DataScope.Select.Api.Extractions.ExtractionRequests.ExtractionResult",
"Contents": [
{
"IdentifierType": "Cusip",
"Identifier": "438516AC0",
"Asset ID": "0x0000190000004b52",
"Asset Status": "MAT",
"Asset Status Description": "Expired/Matured",
"Change Sign": null,
"Common Code": "038610325",
"Currency Code": "USD",
"Currency Code Description": "U.S. Dollar",
"CUSIP": "438516AC0",
"File Code": null,
"Issuer ID": "0x00001900004f782e",
"Issuer Name": "HONEYWELL INTERNATIONAL INC",
"Issuer OrgID": "18181",
"RCP ID": null,
"Issuer Short Name": "Honeywell Intl",
"Legal Entity OrgID": "18181",
"Holdings Previous Report Date": null,
"Holdings Report Date": null,
"Owner Country": null,
"Owner ID": null,
"Owner Name": null,
"Owner Type": null,
"Owner Type Description": null,
"Percent of Shares Outstanding": null,
"Primary Issue Flag": null,
"Security Description": "HON 9.500 06/01/16 MATd",
"Shares Held": null,
"Value Held": null,
"Shares Changed": null,
"Value Changed": null
},
{
"IdentifierType": "Ric",
"Identifier": "IBM.N",
"Asset ID": "0x0003dd001379d460",
"Asset Status": "ISS",
"Asset Status Description": "Issued",
"Change Sign": "P",
"Common Code": null,
"Currency Code": "USD",
"Currency Code Description": "U.S. Dollar",
"CUSIP": "459200101",
"File Code": "77",
"Issuer ID": "0x000019000050e3aa",
"Issuer Name": "International Business Machines Corp",
"Issuer OrgID": "18228",
"RCP ID": "300018228",
"Issuer Short Name": null,
"Legal Entity OrgID": "18228",
"Holdings Previous Report Date": "2021-12-31",
"Holdings Report Date": "2022-03-31",
"Owner Country": "United States",
"Owner ID": "24232909",
"Owner Name": "Invesco S&P 500 High Dividend Low Vol Ind ETF",
"Owner Type": "MF",
"Owner Type Description": "Mutual Fund",
"Percent of Shares Outstanding": 0,
"Primary Issue Flag": "Y",
"Security Description": "INTERNATIONAL BUSINESS MACHINES ORD",
"Shares Held": 2383,
"Value Held": 309838,
"Shares Changed": 74,
"Value Changed": 9621
},
{
"IdentifierType": "Ric",
"Identifier": "IBM.N",
"Asset ID": "0x0003dd001379d460",
"Asset Status": "ISS",
"Asset Status Description": "Issued",
"Change Sign": "NC",
"Common Code": null,
"Currency Code": "USD",
"Currency Code Description": "U.S. Dollar",
"CUSIP": "459200101",
"File Code": "77",
"Issuer ID": "0x000019000050e3aa",
"Issuer Name": "International Business Machines Corp",
"Issuer OrgID": "18228",
"RCP ID": "300018228",
"Issuer Short Name": null,
"Legal Entity OrgID": "18228",
"Holdings Previous Report Date": "2021-12-31",
"Holdings Report Date": "2022-03-31",
"Owner Country": "Italy",
"Owner ID": "22521846",
"Owner Name": "AcomeA Patrimonio Aggressivo",
"Owner Type": "MF",
"Owner Type Description": "Mutual Fund",
"Percent of Shares Outstanding": 0,
"Primary Issue Flag": "Y",
"Security Description": "INTERNATIONAL BUSINESS MACHINES ORD",
"Shares Held": 680,
"Value Held": 88414,
"Shares Changed": 0,
"Value Changed": 0
},
{
"IdentifierType": "Ric",
"Identifier": "IBM.N",
"Asset ID": "0x0003dd001379d460",
"Asset Status": "ISS",
"Asset Status Description": "Issued",
"Change Sign": "S",
"Common Code": null,
"Currency Code": "USD",
"Currency Code Description": "U.S. Dollar",
"CUSIP": "459200101",
"File Code": "77",
"Issuer ID": "0x000019000050e3aa",
"Issuer Name": "International Business Machines Corp",
"Issuer OrgID": "18228",
"RCP ID": "300018228",
"Issuer Short Name": null,
"Legal Entity OrgID": "18228",
"Holdings Previous Report Date": "2020-06-30",
"Holdings Report Date": "2020-09-30",
"Owner Country": "Luxembourg",
"Owner ID": "22002857",
"Owner Name": "Argenta Asset Management SA",
"Owner Type": "IA",
"Owner Type Description": "Investment Advisor",
"Percent of Shares Outstanding": 0,
"Primary Issue Flag": "Y",
"Security Description": "INTERNATIONAL BUSINESS MACHINES ORD",
"Shares Held": 0,
"Value Held": 0,
"Shares Changed": -53136,
"Value Changed": -6465057
},
{
"IdentifierType": "Ric",
"Identifier": "IBM.N",
"Asset ID": "0x0003dd001379d460",
"Asset Status": "ISS",
"Asset Status Description": "Issued",
"Change Sign": "S",
"Common Code": null,
"Currency Code": "USD",
"Currency Code Description": "U.S. Dollar",
"CUSIP": "459200101",
"File Code": "77",
"Issuer ID": "0x000019000050e3aa",
"Issuer Name": "International Business Machines Corp",
"Issuer OrgID": "18228",
"RCP ID": "300018228",
"Issuer Short Name": null,
"Legal Entity OrgID": "18228",
"Holdings Previous Report Date": "2021-03-31",
"Holdings Report Date": "2021-06-30",
"Owner Country": "United States",
"Owner ID": "23282419",
"Owner Name": "Thomas Story & Son LLC",
"Owner Type": "IA",
"Owner Type Description": "Investment Advisor",
"Percent of Shares Outstanding": 0,
"Primary Issue Flag": "Y",
"Security Description": "INTERNATIONAL BUSINESS MACHINES ORD",
"Shares Held": 0,
"Value Held": 0,
"Shares Changed": -2760,
"Value Changed": -404588
},
{
"IdentifierType": "Ric",
"Identifier": "IBM.N",
"Asset ID": "0x0003dd001379d460",
"Asset Status": "ISS",
"Asset Status Description": "Issued",
"Change Sign": "S",
"Common Code": null,
"Currency Code": "USD",
"Currency Code Description": "U.S. Dollar",
"CUSIP": "459200101",
"File Code": "77",
"Issuer ID": "0x000019000050e3aa",
"Issuer Name": "International Business Machines Corp",
"Issuer OrgID": "18228",
"RCP ID": "300018228",
"Issuer Short Name": null,
"Legal Entity OrgID": "18228",
"Holdings Previous Report Date": "2021-03-31",
"Holdings Report Date": "2021-06-30",
"Owner Country": "Canada",
"Owner ID": "22737392",
"Owner Name": "CI Global Quality Dividend Managed Corporate Class",
"Owner Type": "MF",
"Owner Type Description": "Mutual Fund",
"Percent of Shares Outstanding": 0,
"Primary Issue Flag": "Y",
"Security Description": "INTERNATIONAL BUSINESS MACHINES ORD",
"Shares Held": 0,
"Value Held": 0,
"Shares Changed": -3716,
"Value Changed": -544728
},
This goes on with all the other available fields. Here is the last part:
{
"IdentifierType": "Ric",
"Identifier": "IBM.N",
"Asset ID": "0x0003dd001379d460",
"Asset Status": "ISS",
"Asset Status Description": "Issued",
"Change Sign": "S",
"Common Code": null,
"Currency Code": "USD",
"Currency Code Description": "U.S. Dollar",
"CUSIP": "459200101",
"File Code": "77",
"Issuer ID": "0x000019000050e3aa",
"Issuer Name": "International Business Machines Corp",
"Issuer OrgID": "18228",
"RCP ID": "300018228",
"Issuer Short Name": null,
"Legal Entity OrgID": "18228",
"Holdings Previous Report Date": "2021-09-30",
"Holdings Report Date": "2021-12-31",
"Owner Country": "United States",
"Owner ID": "24247542",
"Owner Name": "American Century Low Volatility ETF",
"Owner Type": "MF",
"Owner Type Description": "Mutual Fund",
"Percent of Shares Outstanding": 0,
"Primary Issue Flag": "Y",
"Security Description": "INTERNATIONAL BUSINESS MACHINES ORD",
"Shares Held": 0,
"Value Held": 0,
"Shares Changed": -420,
"Value Changed": -56137
},
{
"IdentifierType": "Ric",
"Identifier": "IBM.N",
"Asset ID": "0x0003dd001379d460",
"Asset Status": "ISS",
"Asset Status Description": "Issued",
"Change Sign": "P",
"Common Code": null,
"Currency Code": "USD",
"Currency Code Description": "U.S. Dollar",
"CUSIP": "459200101",
"File Code": "77",
"Issuer ID": "0x000019000050e3aa",
"Issuer Name": "International Business Machines Corp",
"Issuer OrgID": "18228",
"RCP ID": "300018228",
"Issuer Short Name": null,
"Legal Entity OrgID": "18228",
"Holdings Previous Report Date": "2021-12-31",
"Holdings Report Date": "2022-03-31",
"Owner Country": "United States",
"Owner ID": "22031320",
"Owner Name": "Northwestern Mutual Capital, LLC",
"Owner Type": "IA",
"Owner Type Description": "Investment Advisor",
"Percent of Shares Outstanding": 0.01,
"Primary Issue Flag": "Y",
"Security Description": "INTERNATIONAL BUSINESS MACHINES ORD",
"Shares Held": 86301,
"Value Held": 11220856,
"Shares Changed": 5132,
"Value Changed": 667263
},
{
"IdentifierType": "Ric",
"Identifier": "IBM.N",
"Asset ID": "0x0003dd001379d460",
"Asset Status": "ISS",
"Asset Status Description": "Issued",
"Change Sign": "S",
"Common Code": null,
"Currency Code": "USD",
"Currency Code Description": "U.S. Dollar",
"CUSIP": "459200101",
"File Code": "77",
"Issuer ID": "0x000019000050e3aa",
"Issuer Name": "International Business Machines Corp",
"Issuer OrgID": "18228",
"RCP ID": "300018228",
"Issuer Short Name": null,
"Legal Entity OrgID": "18228",
"Holdings Previous Report Date": "2021-12-31",
"Holdings Report Date": "2022-03-31",
"Owner Country": "United States",
"Owner ID": "23755766",
"Owner Name": "Fidelity Advisor Multi-Asset Income Fund",
"Owner Type": "MF",
"Owner Type Description": "Mutual Fund",
"Percent of Shares Outstanding": 0,
"Primary Issue Flag": "Y",
"Security Description": "INTERNATIONAL BUSINESS MACHINES ORD",
"Shares Held": 30200,
"Value Held": 3926604,
"Shares Changed": -155100,
"Value Changed": -20166102
}
],
"Notes": [
"Extraction Services Version 16.0.43633 (806c08a4ae8f), Built May 9 2022 17:21:07\r\nProcessing started at 05/30/2022 08:47:09.\r\nUser ID: 9008895\r\nExtraction ID: 2000000402712820\r\nCorrelation ID: CiD/9008895/AAAAAA.080833b43f2df0a6/RA\r\nSchedule: 0x080833b43f3df0a6 (ID = 0x0000000000000000)\r\nInput List (2 items): (ID = 0x080833b43f3df0a6) Created: 05/30/2022 08:47:09 Last Modified: 05/30/2022 08:47:09\r\nReport Template (35 fields): _OnD_0x080833b43f3df0a6 (ID = 0x080833b43f4df0a6) Created: 05/30/2022 08:47:08 Last Modified: 05/30/2022 08:47:08\r\nSchedule dispatched via message queue (0x080833b43f3df0a6)\r\nSchedule Time: 05/30/2022 08:47:09\r\nProcessing completed successfully at 05/30/2022 08:47:15, taking 5.430 Secs.\r\nExtraction finished at 05/30/2022 07:47:15 UTC, with servers: x02q12, QSDHA1 (0.0 secs), QSHC17 (1.6 secs)\r\nUsage Summary for User 9008895, Client 65508, Template Type Ownership Owners\r\nBase Usage\r\n Instrument Instrument Terms Price\r\n Count Type Subtype Source Source\r\n------- ----------------------------------- ---------------------------- -------------- ----------------------------------------\r\n 1 Corporate N/A N/A\r\n 1 Equities N/A N/A\r\n-------\r\n 2 Total instruments charged.\r\n 0 Instruments with no reported data.\r\n=======\r\n 2 Instruments in the input list.\r\nWriting RIC maintenance report.\r\n",
"Identifier,IdentType,Source,RIC,RecordDate,MaintType,OldValue,NewValue,Factor,FactorType\r\n"
]
}
If the token is valid, but there was a timeout, this is the response we get:
Status: 202 Accepted
Relevant headers:
Location: https://selectapi.datascope.refinitiv.com/RestApi/v1/Extractions/ExtractResult(ExtractionId='0x053c0831a44b5841')
Body:
Response does not contain any data.
You will have to send another HTTP GET request to retrieve the result, using the location URL that was delivered in the HTTP 202 Response header.
This is how we resend our request. Note the path, taken from the 202 response header:
URL:
https://selectapi.datascope.refinitiv.com/RestApi/v1/Extractions/ExtractResult(ExtractionId='0x053c0831a44b5841')
Method: GET
Headers:
Prefer: respond-async
Authorization: Token F0ABE9A3FFF2E02E10AE2765ED872C59B8CC3B40EBB61B30E295E71DE31C254B8648DB9434C2DF9299FDC668AA123501F322D99D45C8B93438063C912BC936C7B87062B0CF812138863F5D836A7B31A32DCA67EF07B3B50B2FC4978DF6F76784FDF35FCB523A8430DA93613BC5730CDC310D4D241718F9FC3F2E55465A24957CC287BDEC79046B31AD642606275AEAD76318CB221BD843348E1483670DA13968D8A242AAFCF9E13E23240C905AE46DED9EDCA9BB316B4C5C767B18DB2EA7ADD100817ADF059D01394BC6375BECAF6138C25DBA57577F0061
If the data is available, you will get the results. Otherwise, you will have to try again later. The more data is requested, the longer it can take for it to be available.