--- title: "How do I upload corporate action events to a corporate action source?" slug: "how-do-i-upload-corporate-actions-to-a-corporate-action-source" tags: ["corporate actions"] updated: 2025-10-10T07:52:18Z published: 2025-10-10T07:52:18Z canonical: "support.lusid.com/how-do-i-upload-corporate-actions-to-a-corporate-action-source" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.lusid.com/llms.txt > Use this file to discover all available pages before exploring further. # How do I upload corporate action events to a corporate action source? You can load corporate action events into an existing [corporate action source](/v1/docs/how-do-i-create-a-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](https://www.lusid.com/docs/api/#operation/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](/v1/docs/what-are-unique-and-non-unique-identifiers) (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](/v1/docs/understanding-dedicated-corporate-action-events). - One or more elections valid for the `participationType`, if applicable. [More information](/v1/docs/understanding-participation-types-and-elections-for-corporate-actions). - Note that for any datetime field (for example, `exDate` or `paymentDate`), you can either specify a formatted value or a date stamp. [More information](/v1/docs/how-do-i-upload-corporate-actions-to-a-corporate-action-source#specifying-dates-and-times-for-corporate-actions). - Optionally, one or more `properties` to [extend the data model](/v1/docs/properties). 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): ```json curl -X POST 'https://.lusid.com/api/api/corporateactionsources/Example-CAS-scope/Example-CAS-code/instrumentevents' -H 'Content-Type: application/json-patch+json' -H 'Authorization: Bearer ' -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: ```json {  "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](/v1/docs/handling-a-cash-dividend-corporate-action-event). Note you can override this choice dynamically on a per-portfolio basis by loading an [event instruction](/v1/docs/loading-an-event-instruction-to-override-an-instrument-event-for-a-particular-portfolio). ### Specifying datetimes for corporate actions Most corporate actions have one or more datetime fields, for example `exDate`. You can either specify: - A [formatted value](/v1/docs/what-date-formats-are-accepted) 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: ```json [  {    "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](/v1/docs/adjusting-times-and-delaying-the-impact-of-instrument-events). 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: 1. Navigate to **Data Management > Corporate Actions**. 2. On the **Data Management > Corporate Action Sources** dashboard, click a row to select a corporate action source (CAS). 3. On the **Data Management > Corporate Action Sources > *Your-CAS*** dashboard, click the **Create corporate action** button. 4. On the **Create Corporate Action** screen, enter a **id** (no spaces) to uniquely identify the corporate action in this CAS, and optionally a **Description**. 5. Specify a **Sequence number/Processing order** of `0`. 6. In the **Instrument** area, click the **Add** button to select an instrument to which the corporate action applies. 7. From the **Event type** dropdown, select the required LUSID event, for example `CashDividendEvent`: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(696).png) 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](/v1/docs/understanding-participation-types-and-elections-for-corporate-actions) 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: 1. On the **Details** tab, enter a **Payment date** that is later than an **Ex date**. Note **Announcement date** and **Record date** are optional: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(697).png) 2. 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: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(700).png) 3. 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: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(701).png) 4. 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](/v1/docs/handling-a-cash-dividend-corporate-action-event). Note you can override this choice dynamically on a per-portfolio basis by loading an [event instruction](/v1/docs/loading-an-event-instruction-to-override-an-instrument-event-for-a-particular-portfolio).