In this tutorial we'll see how to create a corporate action source, subscribe an existing transaction portfolio holding 1000 Microsoft shares to it, and upload a corporate action representing a cash dividend of $0.17 per Microsoft share.
Note that dates are important when considering corporate actions:
- Ex-dividend date: We must hold Microsoft in our portfolio before this date for LUSID to automatically generate the 'output transactions' necessary to implement the corporate action, which in this case is a single transaction of $170.
- Payment date: LUSID settles corporate actions on this date, which in this case increases the portfolio's USD cash balance by $170.
For a more detailed examination of cash dividends, and also other types of corporate action, see this Jupyter Notebook.
- Section 1: Creating a corporate action source
- Section 2: Subscribing a portfolio to the corporate action source
- Section 3: Uploading a corporate action to the source
- Section 4: Watching LUSID process the corporate action
Creating a corporate action source
The first step is to create a corporate action source with a particular scope and code by calling the CreateCorporateActionSource API.
For example:
curl -X POST 'https://<your-domain>.lusid.com/api/api/corporateactionsources' -H 'Content-Type: application/json-patch+json' -H 'Authorization: Bearer <your-API-access-token>' -d '{ "scope": "Example-CAS-scope", "code": "Example-CAS-code", "displayName": "Example corporate action source", "description": "This is an example corporate action source", }'
Subscribing a portfolio to the corporate action source
We can call the UpsertPortfolioDetails API to retrospectively subscribe an existing transaction portfolio to our corporate action source.
Note: You can subscribe a new portfolio when you create it.
For example, for a transaction portfolio with a scope of growth
and a code of uk-equities
:
curl -X POST 'https://<your-domain>.lusid.com/api/api/transactionportfolios/growth/uk-equities/details'
-H 'Content-Type: application/json-patch+json'
-H 'Authorization: Bearer <your-API-access-token>'
-d '{
"corporateActionSourceId": {
"scope": "Example-CAS-scope",
"code": "Example-CAS-code"
}
}'
To check the subscription, we can examine the response to the GetDetails API:
{
"originPortfolioId": {
"scope": "growth",
"code": "uk-equities"
},
"version": {
"effectiveFrom": "2022-01-01T00:00:00.0000000+00:00",
"asAtDate": "2023-03-04T12:41:02.5737930+00:00"
},
"baseCurrency": "USD",
"corporateActionSourceId": {
"scope": "Example-CAS-scope",
"code": "Example-CAS-code"
},
"subHoldingKeys": [],
"instrumentScopes": [],
"accountingMethod": "Default",
"amortisationMethod": "NoAmortisation",
...
}
If we call the GetHoldings API for 12 February 2023, we can see that the portfolio has holdings in Microsoft and USD (the API response has been transformed to a Pandas dataframe for clarity):
Uploading a corporate action to the source
We can call the UpsertInstrumentEvents API to upload our Microsoft cash dividend corporate action to the corporate action source. Note the following:
- The
instrumentEventId
is a free string field that must uniquely identify this corporate action in the corporate action source. - The
instrumentIdentifiers
field uses a FIGI to resolve to a Microsoft instrument in the LUSID Security Master. - The
exDate
is 13 February and thepaymentDate
is 17 February 2023. The other dates are informational. - The
inputTransition
has aunitsFactor
of 1 to represent each Microsoft share, and acostFactor
of 0 since this corporate action does not impact the cost basis of these shares (highlighted in red below). - The single
outputTransition
impacts the USD currency instrument, has aunitsFactor
of 0.17 to represent the 17 cents per share, and acostFactor
of 0 (highlighted in yellow).
See how to model other kinds of corporate action.
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-2023-02-13", "instrumentIdentifiers": { "Instrument/default/Figi": "BBG000BPH459" }, "description": "Cash dividend of 17 cents per share", "instrumentEvent": { "instrumentEventType": "TransitionEvent", "announcementDate": "2023-02-01T00:00:00.0000000+00:00", "exDate": "2023-02-13T00:00:00.0000000+00:00", "recordDate": "2023-02-13T00:00:00.0000000+00:00", "paymentDate": "2023-02-17T00:00:00.0000000+00:00", "inputTransition": { "unitsFactor": 1, "costFactor": 0 }, "outputTransitions": [ { "instrumentIdentifiers": { "Instrument/default/Currency": "USD" }, "unitsFactor": 0.17, "costFactor": 0 } ] } } ]'
Watching LUSID process the corporate action
If we call the GetHoldings
API on 13 February 2023 (the exDate
) we can see that LUSID has created a new, temporary, unsettled USD holding for $170 (1000 units * 0.17 cents per share), with a holding type of Accrual
:
If we call the GetHoldings
API on 17 February (the paymentDate
) we can see that LUSID has settled the corporate action, removed the temporary holding, and updated the main USD holding by $170:
For audit purposes, we can call the BuildTransactions API with a suitable window to see the output transaction that LUSID generated to impact the holdings in this way: