How do I upload corporate action events to a corporate action source?

You can load corporate action events into an existing corporate action source (CAS), and edit them at any time.

Note a portfolio must subscribe to a CAS in order for the corporate actions it contains to take effect.

Using the LUSID API

You can upload an unbounded number of corporate actions in a single API call. To do this, call the UpsertInstrumentEvents API with the scope and code of a particular CAS and, in the body of the request for each, specify:

An instrumentEventId that uniquely identifies the corporate action in the CAS, and optionally a description.
In the instrumentIdentifiers object, at least one unique identifier (type and value) that resolves to an instrument in the LUSID Security Master.
A participationType of either Mandatory (the default), MandatoryWithChoices or Voluntary to match the specification of the issuer.
In the instrumentEvent object:
- The required LUSID instrumentEventType, for example CashDividendEvent or AccumulationEvent. See a list.
- One or more elections valid for the participationType, if applicable. More information.
- Note that for any datetime field (for example, exDate or paymentDate), you can either specify a formatted value or a date stamp. More information.
Optionally, one or more properties to extend the data model. These properties must be from the InstrumentEvent domain.

Consider the following example, of a CashDividendEvent corporate action uploaded to a CAS with a scope of Example-CAS-scope and code of Example-CAS-code (in the URL below). The dividend is $0.20 per share in an instrument with a FIGI of BBG000BPH459, electing to take it in GBP instead of USD at an exchange rate of 0.8 (so £0.16 per share):

curl -X POST 'https://<your-domain>.lusid.com/api/api/corporateactionsources/Example-CAS-scope/Example-CAS-code/instrumentevents'
 -H 'Content-Type: application/json-patch+json'
 -H 'Authorization: Bearer <your-API-access-token>'
 -d '[
  {
    "instrumentEventId": "MSCashDividend-2024-02-06",
    "instrumentIdentifiers": {"Instrument/default/Figi": "BBG000BPH459"},
    "description": "Cash dividend of 20 cents per Microsoft share",
    "participationType": "MandatoryWithChoices",
    "instrumentEvent": {
      "instrumentEventType": "CashDividendEvent",
      "announcementDate": "2024-01-01T00:00:00.0000000+00:00",
      "exDate": "2024-02-06T00:00:00.0000000+00:00",
      "recordDate": "2024-02-10T00:00:00.0000000+00:00",
      "paymentDate": "2024-02-10T00:00:00.0000000+00:00",
      "cashElections": [
        {
          "electionKey": "USD",
          "dividendCurrency": "USD",
          "dividendRate": "0.2",
          "isDeclared": "True",
          "isChosen": "False",
          "isDefault": "True",
        },
        {
          "electionKey": "GBP",
          "dividendCurrency": "GBP",
          "exchangeRate": "0.8",
          "isDeclared": "False",
          "isChosen": "True",
          "isDefault": "False",
        }
      ]
    }
  }
]'

We recommend checking the failed section of the response. Corporate actions that successfully load are listed in the values section:

{
  "failed": {},
  "values": {
    ...
  }
}

By default, when LUSID emits this event, every portfolio with a holding in Microsoft on the ex-date that also subscribes to this CAS receives 20 cents per share, converted to GBP at an exchange rate of 0.8. Work through a tutorial for this scenario. Note you can override this choice dynamically on a per-portfolio basis by loading an event instruction.

Specifying datetimes for corporate actions

Most corporate actions have one or more datetime fields, for example exDate. You can either specify:

A formatted value for the field, for example "exDate": "2024-02-06T00:00:00.0000000+00:00". If you omit the time component, LUSID defaults to UTC midnight.
A date stamp. This might be useful if the corporate action issuer only supplies information in this form. To do this, omit the datetime field and instead populate an eventDateStamps object, for example:
```
[
  {
    "instrumentEventId": "MSCashDividend-2024-02-06",
    "instrumentIdentifiers": {"Instrument/default/Figi": "BBG000BPH459"},
    "description": "Cash dividend of 20 cents per Microsoft share",
    "participationType": "MandatoryWithChoices",
    "eventDateStamps": {
      "exDate": {
        "day": 6,
        "month": 2,
        "year": 2025
      }
    },
    "instrumentEvent": {
      "instrumentEventType": "CashDividendEvent",
      "announcementDate": "2024-01-01T00:00:00.0000000+00:00",
      "recordDate": "2024-02-10T00:00:00.0000000+00:00",
      "paymentDate": "2024-02-10T00:00:00.0000000+00:00",
      ...
    }
  }
]
```
Note the following:
- The ex-div date is provided as a date stamp, keyed by the exDate field name it replaces and specified as a day, month and year number.
- The exDate field is omitted from the instrumentEvent object. Note that if you do specify both, the field is preferred.
- LUSID appends a time and timezone from the resolved instrument if one is specified. If not, it defaults to UTC midnight.
- LUSID does not persist the date stamp. If you subsequently retrieve the corporate action, the exDate field is populated.

Using the LUSID web app

Some corporate actions are available now and the remainder are coming soon:

Navigate to Data Management > Corporate Actions.
On the Data Management > Corporate Action Sources dashboard, click a row to select a corporate action source (CAS).
On the Data Management > Corporate Action Sources > Your-CAS dashboard, click the Create corporate action button.
On the Create Corporate Action screen, enter a id (no spaces) to uniquely identify the corporate action in this CAS, and optionally a Description.
Specify a Sequence number/Processing order of 0.
In the Instrument area, click the Add button to select an instrument to which the corporate action applies.
From the Event type dropdown, select the required LUSID event, for example CashDividendEvent:

The next step is to choose a Participation type to match the specification of the issuer, and then one or more elections valid for that participation type.

Required reading: Understanding participation types and elections

Consider the example of a CashDividendEvent with a Participation type of MandatoryWithChoices and two currency elections, one of which is declared and the other is chosen. To set this scenario up:

On the Details tab, enter a Payment date that is later than an Ex date. Note Announcement date and Record date are optional:
On the Cash elections tab, click the Add item button to add the first, declared currency election:
1. Specify an Election key to uniquely identify this election in the corporate action.
2. Specify a Dividend rate that expresses the rate as a decimal, so for example 0.2 for 20 cents per share.
3. Enable the Is declared checkbox to specify this election as declared.
4. Enable the Is default checkbox to specify this election as the default:
Click the Add item button again to add the second, chosen currency election:
1. Specify an Election key to uniquely identify this election in the corporate action.
2. Specify an Exchange rate from the declared currency to the chosen currency, for example USD/GBP at 0.8.
3. Enable the Is chosen checkbox to specify this election as chosen:
Click the Save button to upload the corporate action to the CAS.