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 making new elections whose Amounts are 0. The below example shows a client wants to cancel his election on Option 1. It is equivalent to election 0 on Option 1 and move all the amounts of Option 1 to Option 2.
PUT https://gateway.saxobank.com/openapi/ca/v2/elections
{
"AccountKey": "<Your Account Key>“,
"EventId": "8667626",
"Options": [
{
"OptionId": "1",
"Amount": "0"
},
{
"OptionId": "2",
"Amount": "35"
},
]
}
Returns:
202 - Accepted
Get Holdings
A Holding means how many event-related shares a client has and what options a client has elected. The ElectionStatus is NotElected if a client hasn't made any election. Once elected, the ElectionStatus will be Elected and elected options will be included in the response.
// Get the Holdings of an event. It is not elected yet
GET https://gateway.saxobank.com/openapi/ca/v2/holdings/?EventId=8667626
{
"__count": 1,
"Data":
[
{
"AccountId": "<Masked>",
"AccountKey": "<Masked>",
"Amount": 35.0,
"ClientId": "<Masked>",
"ClientKey": "<Masked>",
"ClientName": "<Masked>",
"ElectedAmount": 0.0,
"ElectionStatus": "NotElected",
"EventId": "8667626",
"OwnerId": "10067304"
}
],
...
}
// Get the Holdings of the event again after election.
GET https://gateway.saxobank.com/openapi/ca/v2/holdings/?EventId=8667626
{
"__count": 1,
"Data":
[
{
"AccountId": "<Masked>",
"AccountKey": "<Masked>",
"Amount": 35.0,
"ClientId": "<Masked>",
"ClientKey": "<Masked>",
"ClientName": "<Masked>",
"ElectedAmount": 35.0,
"ElectionStatus": "Elected",
"EventId": "8667626",
"OwnerId": "10067304",
"Options": [
{
"ElectedAmount": 10,
"ElectionType": "Manual",
"Instruction": {
"Status": "Accepted"
},
"OptionId": "1"
},
{
"ElectedAmount": 25,
"ElectionType": "Manual",
"Instruction": {
"Status": "Accepted"
},
"OptionId": "2"
}
]
}
]
}
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.
Top Level Client: Get Events and Holdings of My End Clients
A top level client is usually a company who owns lots of end clients while the top level client itself doesn't trade. From the perspective of a top level client, an event can affect many end clients while each client has different holdings and makes different elections . Therefore a top level client needs to know
- What events are affecting end clients and how many clients are affected by each event. This is achievable by the /events endpoint.
- How many shares are Eligible for each client and what options have been made for each event. This is achievable by the /holdings endpoint.
Get Events of My End Clients
The below example shows as a top level client owning lots of end clients, how can I get all their Active events by using IncludeSubAccounts=true.
The response indicates that
- There are totally 71 Active events in the response
- The second event, whose EventId is 8740953, affects only 2 accounts of my end clients. The aggregated holdings of these accounts is 4000.
- The first event, whose EventId is 8772995, is affecting 42 accounts of my end clients. The aggregated holdings of these accounts is 2025.
- To find out the details these 42 or 2 accounts, it is necessary to make a further query to the /holdings endpoint
GET https://gateway.saxobank.com/openapi/ca/v2/events?EventStatus=Active&IncludeSubAccounts=true
{
"__count": 71,
"Data": [
{
"AffectedAccounts": 2,
"AssetType": "Stock",
"CorporateActionType": "Voluntary",
"DisplayAndFormat": {
"Description": "MicroPort Scientific Corp.",
"IsinCode": "KYG608371046",
"Symbol": "00853:xhkg"
},
"ElectionStatus": "NotElected",
"EligibleHoldings": 4000,
"EventId": "8740953",
"EventIndicators": [
{
"Indicator": "Dividend",
"Values": [
{
"Code": "FINL",
"Description": "Payment of a dividend, less the amounts already paid through interim dividends.",
"Name": "Final"
}
]
}
],
"EventState": "Approved",
"EventStatus": "Active",
"EventType": {
"Code": "DVOP",
"Description": "Shareholders may choose to receive their dividend in shares or cash. The company creates new share capital in exchange for the dividend.",
"Name": "Dividend Option"
},
"Ex": {
"Date": "2021-06-28"
},
"Indicators": {
"Dividend": [
{
"Code": "FINL",
"Description": "Payment of a dividend, less the amounts already paid through interim dividends.",
"Name": "Final"
}
]
},
"Narrative": "<b>Additional text</b><p>DVOP - cash or ... in the action and comply with any participation restrictions.<br/></p>",
"Options": [
{
"CashRequired": false,
"Deadline": {
"Date": "2021-07-29T21:00:00.000000Z"
},
"GrossRate": 0.043,
"IsDefault": false,
"IsGross": false,
"IsTaxable": false,
"MinExercisableQuantity": 30,
"OptionId": "1",
"OptionType": {
"Code": "SECU",
"Description": "Distribution of securities to holders.",
"Name": "Securities Option"
},
"Payment": {
"Date": "2021-08-18"
},
"SecurityMovements": [
{
"Currency": "HKD",
"DisplayAndFormat": {
"Description": "MicroPort Scientific Corp.",
"IsinCode": "KYG608371046",
"Symbol": "00853:xhkg"
},
"SecurityMovementType": "Credit",
"Uic": 48625
}
]
},
{
"CashMovements": [
{
"CashMovementType": "Credit",
"Currency": "HKD",
"GrossDividend": 0.043
}
],
"CashRequired": false,
"Deadline": {
"Date": "2021-07-29T21:00:00.000000Z"
},
"IsDefault": true,
"IsGross": true,
"IsTaxable": true,
"OptionId": "2",
"OptionType": {
"Code": "CASH",
"Description": "Distribution of cash to holders.",
"Name": "Cash"
},
"Payment": {
"Date": "2021-08-18"
}
}
],
"Record": {
"Date": "2021-06-29"
},
"Uic": 48625
}，
{
"AffectedAccounts": 42,
"AssetType": "Stock",
"CorporateActionType": "Voluntary",
"DisplayAndFormat": {
"Description": "Baidu.com Inc.",
"IsinCode": "US0567521085",
"Symbol": "BIDU:xnas"
},
"Effective": {
"Date": "2049-12-29"
},
"ElectionStatus": "NotElected",
"EligibleHoldings": 2025,
"EventId": "8772995",
"EventState": "Approved",
"EventStatus": "Active",
"EventType": {
"Code": "CONV",
"Description": "Conversion of securities into another form of securities.",
"Name": "Conversion"
},
"Ex": {
"Date": "2049-12-29"
},
"Narrative": "<b>Additional text</b><p>Conversion<br/><br/>Please be advised that this event has been set up to facilitate processing, settlement and ... and comply with any participation restrictions.<br/></p>",
"Options": [
{
"CashRequired": false,
"Deadline": {
"Date": "2049-12-28T22:00:00.000000Z"
},
"IsDefault": false,
"IsGross": false,
"IsTaxable": false,
"OptionId": "1",
"OptionType": {
"Code": "SECU",
"Description": "Distribution of securities to holders.",
"Name": "Securities Option"
},
"Payment": {
"Status": "Unknown"
},
"SecurityMovements": [
{
"Currency": "USD",
"DisplayAndFormat": {
"Description": "Baidu.com Inc.",
"IsinCode": "US0567521085",
"Symbol": "BIDU:xnas"
},
"SecurityMovementType": "Debit",
"Uic": 16654
},
{
"Currency": "HKD",
"DisplayAndFormat": {
"Description": "Baidu, Inc.",
"IsinCode": "KYG070341048",
"Symbol": "09888:xhkg"
},
"NewQuantity": 8,
"OldQuantity": 1,
"SecurityMovementType": "Credit",
"Uic": 21920402
}
]
},
{
"CashRequired": false,
"Deadline": {
"Date": "2049-12-28T22: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": "Take No Action"
}
}
],
"Uic": 16654
}
...
]
}
Get Holdings of My End Clients
The next step for the top level client is to find out who are the clients affected by each event and what are the status of them.
To continue the above example, in order to find out who owns the 2 accounts affected by event 8740953, a top level can query the /hodings endpoint as below:
GET https://gateway.saxobank.com/openapi/ca/v2/holdings/?EventId=8740953&IncludeSubAccounts=true
{
"__count": 2,
"Data": [
{
"AccountId": "<masked>",
"AccountKey": "<masked>",
"Amount": 2000,
"ClientId": "<End client ID 1>",
"ClientKey": "<masked>",
"ClientName": "<masked>",
"ElectedAmount": 0,
"ElectionStatus": "NotElected",
"EventId": "8740953",
"ManagementType": "Client",
"OwnerId": "<Top Client's Id >"
},
{
"AccountId": "<masked>",
"AccountKey": "<masked>",
"Amount": 2000,
"ClientId": "<End client ID 2>",
"ClientKey": "<masked>",
"ClientName": "<End client name>",
"ElectedAmount": 0,
"ElectionStatus": "NotElected",
"EventId": "8740953",
"ManagementType": "Client",
"OwnerId": "<Top Client's Id >"
}
]
}
The response lists the details of the two accounts affected by event 8740953. Their collective Amount is 4000 which equals to the EligibleHoldings in the response of the previous /events query.
Similarly, in order to know the details of the 42 accounts affected by event 8772995, the top level client needs to make a second query as below:
GET https://gateway.saxobank.com/openapi/ca/v2/holdings/?EventId=8740953&IncludeSubAccounts=true
{
"__count": 42,
"Data": [
{
"AccountId": "<masked>",
"AccountKey": "<masked>",
"Amount": 7,
"ClientId": "<masked>",
"ClientKey": "<masked>",
"ClientName": "<masked>",
"ElectedAmount": 0,
"ElectionStatus": "NotElected",
"EventId": "8772995",
"ManagementType": "Client",
"OwnerId": "<Top Client's Id >"
},
{
"AccountId": "<masked>",
"AccountKey": "<masked>",
"Amount": 146,
"ClientId": "<masked>",
"ClientKey": "<masked>",
"ClientName": "<masked>",
"ElectedAmount": 0,
"ElectionStatus": "NotElected",
"EventId": "8772995",
"ManagementType": "Client",
"OwnerId": "<Top Client's Id >"
},
{
"AccountId": "<masked>",
"AccountKey": "<masked>",
"Amount": 5,
"ClientId": "<masked>",
"ClientKey": "<masked>",
"ClientName": "<masked>",
"ElectedAmount": 0,
"ElectionStatus": "NotElected",
"EventId": "8772995",
"ManagementType": "Client",
"OwnerId": "<Top Client's Id >"
},
...
]
}