How do I load corporate actions into a corporate action source?

You can load corporate actions 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.

Methods

LUSID web app

LUSID API

Luminesce

Call the UpsertInstrumentEvents API with the scope and code of a particular CAS and any number of corporate actions in the array, for example:

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": {
    ...
  }
}

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:

Write a Luminesce SQL query using the Lusid.InstrumentEvent.<event>.Writer provider, for example Lusid.InstrumentEvent.CashDividendEvent.Writer:

Data fields and properties

This section supplements the API documentation and on-screen help text in the LUSID web app.

Fields

A corporate action is identified by an instrumentEventId that must be unique within the CAS.

In the instrumentIdentifiers object, specify at least one unique identifier (type and value) that resolves to an instrument in the LUSID Security Master.

In the instrumentEvent object, select the LUSID instrumentEventType, for example CashDividendEvent or AccumulationEvent. See a list.

Note that for any datetime field (for example, exDate or paymentDate), you can specify either a formatted value or a date stamp. More information.

You must choose a participationType of either Mandatory, MandatoryWithChoices or Voluntary to match the specification of the corporate action issuer, and then the correct number of valid elections for that corporate action and participation type. Consult the table below.

AccumulationEvent	`BonusIssueEvent`	`CallOnIntermediateSecuritiesEvent`	`CapitalDistributionEvent`	`CapitalGainsDistributionEvent`
CashDividendEvent	ClassActionEvent	`ConsentEvent`	`ConversionEvent`	DividendOptionEvent
`DividendReinvestmentEvent`	`DutchAuctionEvent`	`ExchangeOfferEvent`	`IntermediateSecuritiesDistributionEvent`	`LiquidationPaymentEvent`
`MergerEvent`	`PariPassuEvent`	`PriorityIssueEvent`	`RepurchaseOfferEvent`	`ReverseStockSplitEvent`
`ScripDividendEvent`	`SecurityWriteOffEvent`	`SpinOffEvent`	`StockDividendEvent`	`StockSplitEvent`
TenderEvent	`WorthlessEvent`

Properties

You can optionally extend the data model of a corporate action by adding properties from the InstrumentEvent domain.

Subsequent updates

You can update a corporate action at any time by calling the UpsertInstrumentEvents API with the instrumentEventId of the action to change.

For information about updating or deleting properties, see this article.

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.