OpenAPI

Corporate Actions are events initiated by issuers of instruments to the investors who holds certain units of these instruments as holdings. These events give opportunities to the investors to receive benefits or take part in certain activities.  These events could be

  • Cash Dividend (DVCA): Distribution of cash to shareholders, in proportion to their equity holding. Ordinary dividends are recurring and regular. Shareholder must take cash and may be offered a choice of currency.

  • Dividend Option (DVOP): Distribution of a dividend to shareholders with a choice of benefit to receive. Shareholders may choose to receive shares or cash. To be distinguished from DRIP as the company creates new share capital in exchange for the dividend rather than investing the dividend in the market.
  • Conversion (CONV): Conversion of securities (generally convertible bonds or preferred shares) into another form of securities (usually common shares) at a pre-stated price/ratio.

Corporate Action events can be categorized into two types: Mandatory events and Voluntary events. 

  • Mandatory events take effect automatically so that it is not necessary for the investors to respond;
  • Voluntary events require investors to respond. Together with the events, companies usually provides several options to investors so that investors can decide which option to choose by an election

An investor can also set Standing Instructions in advance so that election will be automatically made to choose the default options on specific instruments.


Get Active Events

Below is an example of how to get active events and their detailed information. 

GET https://gateway.saxobank.com/openapi/ca/v2/events?EventStatus=Active

Returns:
200 OK and
{
    "__count": 1,
    "Data": [
        {
            "AssetType": "Stock",
            "CorporateActionType": "Voluntary",
            "DisplayAndFormat": {
                "Description": "Alibaba Group Holding Ltd",
                "IsinCode": "US01609W1027",
                "Symbol": "AHLA:xetr"
            },
            "ElectionStatus": "NotElected",
            "EventId": "8667626",
            "EventState": "Approved",
            "EventStatus": "Active",
            "EventType": {
                "Code": "TEND",
                "Description": "An offer made to shareholders to tender or exchange securities by a third party.",
                "Name": "Tender Offer"
            },
            "Ex": {
                "Date": "2021-12-01"
            },
            "Holdings": [
                {
                    "AccountId": "<Masked>",
                    "AccountKey": "<Masked>",
                    "Amount": 35.0,
                    "ClientId": "<Masked>",
                    "ClientKey": "<Masked>",
                    "ClientName": "<Masked>",
                    "ElectedAmount": 0.0,
                    "ElectionStatus": "NotElected",
                    "EventId": "8667626",
                    "OwnerId": "10067304"
                }
            ],
            "MaxQuantitySought": 1000000.0,
            "Narrative": "<b>Additional text</b><p>Tender offer<br/><br/>***update as on 06-jan-2021***<br/><br/>...Timetable eoffer</p>",
            "Options": [
                {
                    "CashRequired": false,
                    "Deadline": {
                        "Date": "2021-11-30T22:00:00.000000Z"
                    },
                    "IsDefault": false,
                    "IsGross": false,
                    "IsTaxable": false,
                    "OptionId": "1",
                    "OptionType": {
                        "Code": "NOAC",
                        "Description": "Option for the account owner not to take part in the event.",
                        "Name": "Receive Cash"
                    }
                },
                {
                    "CashRequired": false,
                    "Deadline": {
                        "Date": "2021-11-30T22:00:00.000000Z"
                    },
                    "IsDefault": true,
                    "IsGross": false,
                    "IsTaxable": false,
                    "OptionId": "2",
                    "OptionType": {
                        "Code": "NOAC",
                        "Description": "Option for the account owner not to take part in the event.",
                        "Name": "Receive Securities"
                    }
                }
            ],
            "Uic": 1284310
        }
    ]
}

The response is equivalent to the Overview/Details views of Corporate Actions in SAXO TraderGo. 

Similarly, you can get Past or Upcoming events by the below requests:

GET https://gateway.saxobank.com/openapi/ca/v2/events?EventStatus=Past 
GET https://gateway.saxobank.com/openapi/ca/v2/events?EventStatus=Upcoming

Create an Election

The event 8667626 above is allowed for election since it is an Active Voluntary event which has two options. Below is an example of how to elect the second option of Event 8667626.

PUT https://gateway.saxobank.com/openapi/ca/v2/elections
{
    "AccountKey": "<Your Account Key>“,
    "EventId": "8667626",
    "Options": [
        {
        "OptionId": "1",  
        "Amount": "10"
        },
		{
        "OptionId": "2",
        "Amount": "25"
        }
    ]
}

Returns:
202 - Accepted

The request is equivalent to the "Election ticket" in SAXO TraderGo. 

Cancel Elections

Existing elections can be canceled by changing them into an empty array. Here an empty array stands for "No Option". Once being canceled, the ElectionStatus in the Holdings field of the event will be "NotElected" and the ElectedAmount will be 0. 

PUT https://gateway.saxobank.com/openapi/ca/v2/elections
{
    "AccountKey": "<Your Account Key>“,
    "EventId": "8667626",
    "Options": [
    ]
}

Returns:
202 - Accepted


Manage Standing Instructions

A client can create multiple standing instructions for automatic elections on specific accounts or instruments. 

Below is an example of how to create a new standing instruction to elect "Receive securities" for all the Apple Inc. shares in all the accounts.

POST https://gateway.saxobank.com/openapi/ca/v2/standinginstructions
{
    "ClientKey": "hcqD9bB9ETvo6glQeRINHg==",
    "StandingInstructions": [
        {
            "AssetType": "Stock",
            "OptionType": "SECU",
            "Uic": 211
        }
    ]
}

Returns:
201 - Created
{
    "__count": 1,
    "Data": [
        {
            "AssetType": "Stock",
            "CreatedDate": "2021-06-17",
            "OptionType": "SECU",
            "StandingInstructionId": "534366",
            "Uic": 211
        }
    ]
}

The request is equivalent to the "Add instruction" in SAXO TraderGo. 


An existing standing instruction can be deleted but not updated. An investor can delete the old standing instruction and recreate a new one for modification.  Below is an example of how to delete a standing instruction:

DELETE https://gateway.saxobank.com/openapi/ca/v2/standinginstructions?StandingInstructionIds=534366


Returns:
200 - OK

The request is equivalent to the "Delete standing instruction" in SAXO TraderGo.