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.
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 adescription
.In the
instrumentIdentifiers
object, at least one unique identifier (type and value) that resolves to anEquity
orSimpleInstrument
in the LUSID Security Master.A
participationType
of eitherMandatory
(the default),MandatoryWithChoices
orVoluntary
to match the specification of the issuer.In the
instrumentEvent
object:The required LUSID
instrumentEventType
, for exampleCashDividendEvent
orAccumulationEvent
. See a list.One or more elections valid for the
participationType
. More information.
Optionally, one or more
properties
to extend the data model. These properties must be from theInstrumentEvent
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.
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 of type
Equity
orSimpleInstrument
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:
Specify an Election key to uniquely identify this election in the corporate action.
Specify a Dividend rate that expresses the rate as a decimal, so for example
0.2
for 20 cents per share.Enable the Is declared checkbox to specify this election as declared.
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:
Specify an Election key to uniquely identify this election in the corporate action.
Specify an Exchange rate from the declared currency to the chosen currency, for example USD/GBP at
0.8
.Enable the Is chosen checkbox to specify this election as chosen:
Click the Save button to upload the corporate action to the CAS.
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.