DataScope Select - REST API

Close Menu
Expand All Collapse All
Introductory Tutorials Tutorials Introduction Programming without SDK Tutorial REST API Tutorials REST API Tutorials Introduction REST API Tutorial 1: Connecting to the DSS server REST API Tutorial 2: On Demand End of Day Extraction REST API Tutorial 3: On Demand intraday extraction, embargo REST API Tutorial 4: On Demand price history extraction REST API Tutorial 5: On Demand corporate actions extraction REST API Tutorial 6: On Demand ownership data extraction REST API Tutorial 7: On Demand T&C extraction REST API Tutorial 8: On Demand composite extraction REST API Tutorial 9: On Demand extraction: instrument list REST API Tutorial 10: GUI control calls: immediate extract REST API Tutorial 11: Search by Instrument REST API Tutorial 12: Search for an Equity REST API Tutorial 13: Search for a Future or Option REST API Tutorial 14: On Demand price history extraction raw .Net SDK Tutorials .Net SDK Tutorial 1: Connecting to the DSS server .Net SDK Tutorial 2: GUI control calls: List, report, sched .Net SDK Tutorial 3: GUI control calls: Validate, extraction .Net SDK Tutorial 4: GUI control calls: Embargo, note files .Net SDK Tutorial 5: On Demand: EoD extraction .Net SDK Tutorial 6: On Demand: EoD extraction, file I/O .Net SDK Tutorial 7: On Demand: large instrument lists .Net SDK Tutorial 8: On Demand: Terms & Conditions .Net SDK Tutorial 9: On Demand: Composite extraction .Net SDK Tutorial 10: Search by Instrument .Net SDK Tutorial 11: Search for Equity .Net SDK Tutorial 12: Search for Future or Option

REST API Tutorial 5: On Demand corporate actions extraction

Last update November 2019
Environment Any
Language Any HTTP is supported
Compilers None
Prerequisites DSS login, internet access
Source code Below

Tutorial purpose

This tutorial explains how to:

  • Retrieve the available field list from the DSS server.
  • Retrieve corporate actions data from the DSS server, using an on demand request. Corporate actions are events that affect the securities issued by the company. Examples: dividend or coupon payment, call (early redemption) or stock split.

 

Table of contents

 

Get available field list for corporate actions - HTTP request

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 corporate actions data we set a value of CorporateActions. The preceding and following tutorials show other possibilities.

See here for more information on report templates and corresponding field lists.

Note: for all requests we need a user token. This was retrieved in Tutorial 1.

URL:               

https://hosted.datascopeapi.reuters.com/RestApi/v1/Extractions/GetValidContentFieldTypes(ReportTemplateType=ThomsonReuters.Dss.Api.Extractions.ReportTemplates.ReportTemplateTypes'CorporateActions')

Method:          GET

Headers:

Prefer: respond-async
Authorization: Token F0ABE9A3FFF2E02E10AE2765ED872C59B8CC3B40EBB61B30E295E71DE31C254B8648DB9434C2DF9299FDC668AA123501F322D99D45C8B93438063C912BC936C7B87062B0CF812138863F5D836A7B31A32DCA67EF07B3B50B2FC4978DF6F76784FDF35FCB523A8430DA93613BC5730CDC310D4D241718F9FC3F2E55465A24957CC287BDEC79046B31AD642606275AEAD76318CB221BD843348E1483670DA13968D8A242AAFCF9E13E23240C905AE46DED9EDCA9BB316B4C5C767B18DB2EA7ADD100817ADF059D01394BC6375BECAF6138C25DBA57577F0061

 

Get available field list for corporate actions - HTTP response

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 300 values in the response. Here is the beginning of the response:

{
  "@odata.context": "https://hosted.datascopeapi.reuters.com/RestApi/v1/$metadata#ContentFieldTypes",
  "value": [
    {
      "Code": "COR.Accounting Standard",
      "Name": "Accounting Standard",
      "Description": "Code indicating the accounting standard used in accounts in which the EPS figure is reported",
      "FormatType": "Text",
      "FieldGroup": " "
    },
    {
      "Code": "COR.Acquirer Company Name",
      "Name": "Acquirer Company Name",
      "Description": "Name of the acquiring party",
      "FormatType": "Text",
      "FieldGroup": " "
    },
    {
      "Code": "COR.Acquirer RIC",
      "Name": "Acquirer RIC",
      "Description": "RIC of primary issue of acquirer",
      "FormatType": "Text",
      "FieldGroup": " "
    },
    {
      "Code": "COR.Acquirer Row ID",
      "Name": "Acquirer Row ID",
      "Description": "Unique system-assigned identifier for the acquiring party",
      "FormatType": "Number",
      "FieldGroup": " "
    },
    {
      "Code": "COR.Actual Adjustment Factor",
      "Name": "Actual Adjustment Factor",
      "Description": "Actual or as-reported adjustment factor expressing the dilutive effect of the capital change event on per share values",
      "FormatType": "Number",
      "FieldGroup": " "
    },

This goes on with all the other available fields. Here is the last part:

    {
      "Code": "COR.Wertpapier",
      "Name": "Wertpapier",
      "Description": "Issue-level code used for identifying instruments in Germany",
      "FormatType": "Text",
      "FieldGroup": " "
    },
    {
      "Code": "COR.Withdrawn Date",
      "Name": "Withdrawn Date",
      "Description": "Date on which the offer was withdrawn",
      "FormatType": "Date",
      "FieldGroup": " "
    },
    {
      "Code": "COR.Zip Code",
      "Name": "Zip Code",
      "Description": "Current zip code of the organization",
      "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.

 

Get corporate actions data - HTTP request

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:

  • The type of extraction: as we want corporate actions data we set a value of CorporateActionsStandardExtractionRequest. The preceding and following tutorials show other possibilities.
  • The list of field names: these were determined in the first step of this tutorial.
  • The list of instrument identifiers, each one with its type. Similar to the previous tutorial, below we define one instrument using a CUSIP code and other ones using a RIC.
  • The conditions: this is where we set our preferences, among which we have the report date range type (LastRange) and PreviousDays numeric range, choices for events that must be included or not, date settings, etc.

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://hosted.datascopeapi.reuters.com/RestApi/v1/Extractions/ExtractWithNotes

Method:          POST

Headers:

Prefer: respond-async
Content-Type: application/json
Authorization: Token F0ABE9A3FFF2E02E10AE2765ED872C59B8CC3B40EBB61B30E295E71DE31C254B8648DB9434C2DF9299FDC668AA123501F322D99D45C8B93438063C912BC936C7B87062B0CF812138863F5D836A7B31A32DCA67EF07B3B50B2FC4978DF6F76784FDF35FCB523A8430DA93613BC5730CDC310D4D241718F9FC3F2E55465A24957CC287BDEC79046B31AD642606275AEAD76318CB221BD843348E1483670DA13968D8A242AAFCF9E13E23240C905AE46DED9EDCA9BB316B4C5C767B18DB2EA7ADD100817ADF059D01394BC6375BECAF6138C25DBA57577F0061

Body:

{
  "ExtractionRequest": {
    "@odata.type": "#ThomsonReuters.Dss.Api.Extractions.ExtractionRequests.CorporateActionsStandardExtractionRequest",
    "ContentFieldNames": [
      "Corporate Actions Type",
      "Capital Change Event Type",
      "Capital Change Event Type Description",
      "Actual Adjustment Type",
      "Actual Adjustment Type Description",
      "Adjustment Factor",
      "Currency Code",
      "Exchange Code",
      "Effective Date",
      "Dividend Pay Date",
      "Dividend Rate",
      "Nominal Value",
      "Nominal Value Currency",
      "Nominal Value Date"
    ],
    "IdentifierList": {
      "@odata.type": "#ThomsonReuters.Dss.Api.Extractions.ExtractionRequests.InstrumentIdentifierList",
      "InstrumentIdentifiers": [
      	{ "Identifier": "438516AC0", "IdentifierType": "Cusip" },
      	{ "Identifier": "ALVG.DE", "IdentifierType": "Ric" },
      	{ "Identifier": "IBM.N", "IdentifierType": "Ric" }
      ]
    },
    "Condition": {
      "ReportDateRangeType": "Last",
      "PreviousDays": 30,
      "ExcludeDeletedEvents": true,
      "IncludeCapitalChangeEvents": true,
      "IncludeDividendEvents": true,
      "IncludeEarningsEvents": true,
      "IncludeMergersAndAcquisitionsEvents": true,
      "IncludeNominalValueEvents": true,
      "IncludePublicEquityOfferingsEvents": true,
      "IncludeSharesOutstandingEvents": true,
      "IncludeVotingRightsEvents": true,
      "CorporateActionsCapitalChangeType": "CapitalChangeExDate",
      "CorporateActionsDividendsType": "DividendPayDate",
      "CorporateActionsEarningsType": "PeriodEndDate",
      "ShareAmountTypes": [
      ]
    }
  }
}

 

Get corporate actions data - HTTP response

If the token is valid, and there is no timeout, the data will be delivered. This is the response we get:

Status:                        200 OK

Relevant headers:

Content-Type: application/json; charset=utf-8

Body:

{
  "@odata.context": "https://hosted.datascopeapi.reuters.com/RestApi/v1/$metadata#ThomsonReuters.Dss.Api.Extractions.ExtractionRequests.ExtractionResult",
  "Contents": [
    {
      "IdentifierType": "Ric",
      "Identifier": "ALVG.DE",
      "Corporate Actions Type": "CAP",
      "Capital Change Event Type": 13,
      "Capital Change Event Type Description": "Non-renounceable rights issue in same stock",
      "Actual Adjustment Type": "CCH",
      "Actual Adjustment Type Description": "Capital Change - Adjusts Dividend and Earnings per Share, Pricing and Volume",
      "Adjustment Factor": 1,
      "Currency Code": "EUR",
      "Exchange Code": "GER",
      "Effective Date": "2007-05-03",
      "Dividend Pay Date": null,
      "Dividend Rate": null,
      "Nominal Value": null,
      "Nominal Value Currency": null,
      "Nominal Value Date": null
    },
    {
      "IdentifierType": "Ric",
      "Identifier": "ALVG.DE",
      "Corporate Actions Type": "DIV",
      "Capital Change Event Type": null,
      "Capital Change Event Type Description": null,
      "Actual Adjustment Type": null,
      "Actual Adjustment Type Description": null,
      "Adjustment Factor": null,
      "Currency Code": "EUR",
      "Exchange Code": "GER",
      "Effective Date": null,
      "Dividend Pay Date": "2019-05-13",
      "Dividend Rate": 9,
      "Nominal Value": null,
      "Nominal Value Currency": null,
      "Nominal Value Date": null
    },
    {
      "IdentifierType": "Ric",
      "Identifier": "ALVG.DE",
      "Corporate Actions Type": "PEO",
      "Capital Change Event Type": null,
      "Capital Change Event Type Description": null,
      "Actual Adjustment Type": null,
      "Actual Adjustment Type Description": null,
      "Adjustment Factor": null,
      "Currency Code": "EUR",
      "Exchange Code": "GER",
      "Effective Date": null,
      "Dividend Pay Date": null,
      "Dividend Rate": null,
      "Nominal Value": 2.56,
      "Nominal Value Currency": "EUR",
      "Nominal Value Date": null
    },
    {
      "IdentifierType": "Ric",
      "Identifier": "ALVG.DE",
      "Corporate Actions Type": "EAR",
      "Capital Change Event Type": null,
      "Capital Change Event Type Description": null,
      "Actual Adjustment Type": null,
      "Actual Adjustment Type Description": null,
      "Adjustment Factor": null,
      "Currency Code": "EUR",
      "Exchange Code": "GER",
      "Effective Date": null,
      "Dividend Pay Date": null,
      "Dividend Rate": null,
      "Nominal Value": null,
      "Nominal Value Currency": null,
      "Nominal Value Date": null
    },
    {
      "IdentifierType": "Ric",
      "Identifier": "ALVG.DE",
      "Corporate Actions Type": "EAR",
      "Capital Change Event Type": null,
      "Capital Change Event Type Description": null,
      "Actual Adjustment Type": null,
      "Actual Adjustment Type Description": null,
      "Adjustment Factor": null,
      "Currency Code": "EUR",
      "Exchange Code": "GER",
      "Effective Date": null,
      "Dividend Pay Date": null,
      "Dividend Rate": null,
      "Nominal Value": null,
      "Nominal Value Currency": null,
      "Nominal Value Date": null
    },
    {
      "IdentifierType": "Ric",
      "Identifier": "ALVG.DE",
      "Corporate Actions Type": "SHO",
      "Capital Change Event Type": null,
      "Capital Change Event Type Description": null,
      "Actual Adjustment Type": null,
      "Actual Adjustment Type Description": null,
      "Adjustment Factor": null,
      "Currency Code": "EUR",
      "Exchange Code": "GER",
      "Effective Date": null,
      "Dividend Pay Date": null,
      "Dividend Rate": null,
      "Nominal Value": null,
      "Nominal Value Currency": null,
      "Nominal Value Date": null
    },
    {
      "IdentifierType": "Ric",
      "Identifier": "ALVG.DE",
      "Corporate Actions Type": "NOM",
      "Capital Change Event Type": null,
      "Capital Change Event Type Description": null,
      "Actual Adjustment Type": null,
      "Actual Adjustment Type Description": null,
      "Adjustment Factor": null,
      "Currency Code": "EUR",
      "Exchange Code": "GER",
      "Effective Date": null,
      "Dividend Pay Date": null,
      "Dividend Rate": null,
      "Nominal Value": null,
      "Nominal Value Currency": null,
      "Nominal Value Date": "2018-08-14"
    },
    {
      "IdentifierType": "Ric",
      "Identifier": "ALVG.DE",
      "Corporate Actions Type": "VOT",
      "Capital Change Event Type": null,
      "Capital Change Event Type Description": null,
      "Actual Adjustment Type": null,
      "Actual Adjustment Type Description": null,
      "Adjustment Factor": null,
      "Currency Code": "EUR",
      "Exchange Code": "GER",
      "Effective Date": null,
      "Dividend Pay Date": null,
      "Dividend Rate": null,
      "Nominal Value": null,
      "Nominal Value Currency": null,
      "Nominal Value Date": null
    },
    {
      "IdentifierType": "Ric",
      "Identifier": "IBM.N",
      "Corporate Actions Type": "MNA",
      "Capital Change Event Type": null,
      "Capital Change Event Type Description": null,
      "Actual Adjustment Type": null,
      "Actual Adjustment Type Description": null,
      "Adjustment Factor": null,
      "Currency Code": "USD",
      "Exchange Code": "NYS",
      "Effective Date": null,
      "Dividend Pay Date": null,
      "Dividend Rate": null,
      "Nominal Value": null,
      "Nominal Value Currency": null,
      "Nominal Value Date": null
    },
    {
      "IdentifierType": "Ric",
      "Identifier": "IBM.N",
      "Corporate Actions Type": "SHO",
      "Capital Change Event Type": null,
      "Capital Change Event Type Description": null,
      "Actual Adjustment Type": null,
      "Actual Adjustment Type Description": null,
      "Adjustment Factor": null,
      "Currency Code": "USD",
      "Exchange Code": "NYS",
      "Effective Date": null,
      "Dividend Pay Date": null,
      "Dividend Rate": null,
      "Nominal Value": null,
      "Nominal Value Currency": null,
      "Nominal Value Date": null
    },
    {
      "IdentifierType": "Ric",
      "Identifier": "IBM.N",
      "Corporate Actions Type": "VOT",
      "Capital Change Event Type": null,
      "Capital Change Event Type Description": null,
      "Actual Adjustment Type": null,
      "Actual Adjustment Type Description": null,
      "Adjustment Factor": null,
      "Currency Code": "USD",
      "Exchange Code": "NYS",
      "Effective Date": null,
      "Dividend Pay Date": null,
      "Dividend Rate": null,
      "Nominal Value": null,
      "Nominal Value Currency": null,
      "Nominal Value Date": null
    },
    {
      "IdentifierType": "Ric",
      "Identifier": "IBM.N",
      "Corporate Actions Type": "NOM",
      "Capital Change Event Type": null,
      "Capital Change Event Type Description": null,
      "Actual Adjustment Type": null,
      "Actual Adjustment Type Description": null,
      "Adjustment Factor": null,
      "Currency Code": "USD",
      "Exchange Code": "NYS",
      "Effective Date": null,
      "Dividend Pay Date": null,
      "Dividend Rate": null,
      "Nominal Value": 0.2,
      "Nominal Value Currency": "USD",
      "Nominal Value Date": "2008-06-30"
    },
    {
      "IdentifierType": "Ric",
      "Identifier": "IBM.N",
      "Corporate Actions Type": "EAR",
      "Capital Change Event Type": null,
      "Capital Change Event Type Description": null,
      "Actual Adjustment Type": null,
      "Actual Adjustment Type Description": null,
      "Adjustment Factor": null,
      "Currency Code": "USD",
      "Exchange Code": "NYS",
      "Effective Date": null,
      "Dividend Pay Date": null,
      "Dividend Rate": null,
      "Nominal Value": null,
      "Nominal Value Currency": null,
      "Nominal Value Date": null
    },
    {
      "IdentifierType": "Ric",
      "Identifier": "IBM.N",
      "Corporate Actions Type": "EAR",
      "Capital Change Event Type": null,
      "Capital Change Event Type Description": null,
      "Actual Adjustment Type": null,
      "Actual Adjustment Type Description": null,
      "Adjustment Factor": null,
      "Currency Code": "USD",
      "Exchange Code": "NYS",
      "Effective Date": null,
      "Dividend Pay Date": null,
      "Dividend Rate": null,
      "Nominal Value": null,
      "Nominal Value Currency": null,
      "Nominal Value Date": null
    },
    {
      "IdentifierType": "Ric",
      "Identifier": "IBM.N",
      "Corporate Actions Type": "DIV",
      "Capital Change Event Type": null,
      "Capital Change Event Type Description": null,
      "Actual Adjustment Type": null,
      "Actual Adjustment Type Description": null,
      "Adjustment Factor": null,
      "Currency Code": "USD",
      "Exchange Code": "NYS",
      "Effective Date": null,
      "Dividend Pay Date": "2019-12-10",
      "Dividend Rate": 1.62,
      "Nominal Value": null,
      "Nominal Value Currency": null,
      "Nominal Value Date": null
    },
    {
      "IdentifierType": "Ric",
      "Identifier": "IBM.N",
      "Corporate Actions Type": "CAP",
      "Capital Change Event Type": 21,
      "Capital Change Event Type Description": "Stock split",
      "Actual Adjustment Type": "CCH",
      "Actual Adjustment Type Description": "Capital Change - Adjusts Dividend and Earnings per Share, Pricing and Volume",
      "Adjustment Factor": 0.5,
      "Currency Code": "USD",
      "Exchange Code": "NYS",
      "Effective Date": "1999-05-26",
      "Dividend Pay Date": null,
      "Dividend Rate": null,
      "Nominal Value": null,
      "Nominal Value Currency": null,
      "Nominal Value Date": null
    }
  ],
  "Notes": [
    "Extraction Services Version 13.2.41189 (85522a4c8b22), Built Nov 11 2019 22:27:09\r\nUser has overridden estimates broker entitlements.\r\nProcessing started at 19112019 16:00:24.\r\nUser ID: 33314\r\nExtraction ID: 398258302\r\nSchedule: _OnD_0x06df5ec9cd712ba5 (ID = 0x06df5ec9e2412ba5)\r\nReporting the latest corporate actions.\r\nSuppressing Deleted Events\r\nReporting corporate actions with shares default type.\r\nInput List (3 items): _OnD_0x06df5ec9cd712ba5 (ID = 06df5ec9da312ba5) Created: 19112019 16:00:22 Last Modified: 19112019 16:00:23\r\nSchedule Time: 19112019 16:00:23\r\nReport Template (20 fields): _OnD_0x06df5ec9cd712ba5 (ID = 0x06df5ec9cd912ba5) Created: 19112019 16:00:22 Last Modified: 19112019 16:00:22\r\nProcessing completed successfully at 19112019 16:00:28, taking 4.45 Secs.\r\nExtraction finished at 19112019 15:00:28 UTC, with servers: x02E04, QSHC20 (3.5 secs), QSSHA1 (0.0 secs)\r\nUsage Summary for User 33314, Client 11122, Template Type Corporate Actions, Standard Events\r\nBase Usage\r\n    Instrument              Instrument           Terms      Price\r\n  Count Type                Subtype            Source     Source\r\n------- ----------------------------------- ---------------------------- -------------- ----------------------------------------\r\n    2 Equities                             N/A      N/A\r\n-------\r\n    2 Total instruments charged.\r\n    1 Instrument with no reported data.\r\n=======\r\n    3 Instruments in the input list.\r\nWriting RIC maintenance report.\r\n",
    "Identifier,IdentType,Source,RIC,RecordDate,MaintType,OldValue,NewValue,Factor,FactorType\r\n"
  ]
}

No corporate actions apply to the bond, so there are no results for that instrument.

The Corporate Actions Type defines the event type:

Value Description
CAP Capital change
DIV Dividend
EAR Earnings
MNA Mergers and acquisitions
NOM Nominal value
PEO Public equity offering
SHO Shares outstanding
VOT Voting rights

Depending on the event type, some fields will contain values, others, irrelevant to that case, will be null.

Tutorial Group: 
REST API Tutorials