# Corporate action notifications Upvest offers the possibility to inform the client about upcoming corporate actions promptly after their announcement. To this end, announcements are processed and manually reviewed by Upvest's operations teams and distributed within 24 hours of initial receipt. This guide describes how notifications of corporate actions are implemented so that you and your users are fully informed about upcoming corporate actions and their impact on users' investments. The way the notification comes to the relevant recipients is that clients register for the corporate action notification events. Technically, this way they will always be supplied with the latest information, as each corporate action triggers such an event. Upvest executes the notification process as soon as we become aware of the underlying market information, e.g., from our data providers or our custodian. The client then receives a notification of an upcoming corporate action via the Investment API. This information can be used to prepare internal processing by the client or as a trigger for end-user notifications. We apply the [ISO 15022 standard](https://www.iso20022.org/15022/uhb/mt564-5-field-22f.htm) for our corporate action notifications to ensure accurate, standardised, and efficient communication of corporate action details to our clients. This approach aligns with international best practices for securities messaging. ## Currently supported corporate action types The Investment API basically supports notifications for all types of corporate actions. Currently, these types are implemented: - cash dividends (cash-based dividends) - capital distributions - shares premium dividends - intermediate securities distribution - dividend option - stock split/change in nominal value/subdivision - reverse stock split/change in nominal value - tender/acquisition/takeover/purchase offer - spin-off - dividend reinvestment - change - delisting - merger - liquidation dividend/liquidation payment - call on intermediate securities - conversion - stock dividend - bonus issue/capitalisation issue - final maturity - worthless **Coming soon** Further corporate action types will successively follow. ## Announcement flow Below you can find an overview of our announcement flow and related operations processes. We include the [`announcement_status` and `function_of_message`](#announcement-status-and-function-of-message) fields to reflect the lifecycle status of the corporate action. ## Notifications structure The structure of the notifications is basically the same for all types of corporate actions. To illustrate this, some example notifications are listed below. The following table lists the standard elements of such a corporate action notification, which will therefore be present in all notifications. | Parameter | Description | | --- | --- | | `id` | A unique corporate action ID, which is assigned in each case and propagated throughout our system. Corporate action IDs will be visible in the transactions reporting to link notifications with the associated cash or security impact. | | `object` | General information about the instrument and nature of the corporate action. | | `announcement_status` | This field provides information on the status of information known about a corporate action on the mark (see ["Announcement status and function of message"](#announcement-status-and-function-of-message) below). | | `function_of_message` | This field provides information on the reason for the corporate action notification (see ["Announcement status and function of message"](#announcement-status-and-function-of-message) below). | | `dates` | Relevant dates associated with certain corporate actions. Read more about relevant dates [here](/products/tol/guides/corporate_actions/ca_lifecycle#relevant-dates). | | `options` | Information about how the corporate action is processed (options and movements). | Occasionally, there is also additional information (if available) containing explanatory notes, text fields, or similar data that issuers consider relevant to the context of a corporate action. ### Announcement status and function of message Corporate action notifications can be assigned different statuses during their lifecycle. Upvest discloses these statuses in accordance with [ISO standards](https://www.iso20022.org/15022/uhb/mt564-7-field-25d.htm). You can use the `announcement_status` and the `function_of_message` fields to better understand the contents and the reason for the message. #### Announcement status The `announcement_status` field provides information on the status of information known about a corporate action on the mark. | Status | Description | | --- | --- | | `COMPLETE` | The message contains full details of the corporate action at the time the event was notified. It has also already been confirmed by the selected official source of the account service provider. Further updates to the event are still possible. | | `COMPLETE_UNCONFIRMED ` | The message contains full details of the corporate action event at the time of notification of the event, but the occurrence of the event has not been confirmed by the selected official source of the account service provider. Further updates to the event are still possible. | | `WITH_ENTITLEMENT` | The message contains the entitlement details to calculate specific cash or security movements. | | `PRELIMINARY_ANNOUNCEMENT_CONFIRMED` | The message may not contain all the details of the corporate action, but the occurrence of the event has been confirmed by the official source chosen by the account service provider. | | `PRELIMINARY_ANNOUNCEMENT_UNCONFIRMED` | The message may not contain complete details of the corporate action event and the occurrence of the event has not been confirmed by the selected official source of the account service provider at the time the message is sent. | #### Function of message The `function_of_message` field provides information related to the reason for the message. | Status | Description | | --- | --- | | `ADDITIONAL_BUSINESS_PROCESS` | The message contains a notification of an additional business process to a corporate action. | | `CANCELLATION_ADVICE` | The message contains the cancellation of a previously announced corporate action event by the account servicer or a previously sent Preliminary Advice of Payment message. | | `NEW` | The message is a new message. | | `ELIGIBLE_BALANCE_NOTIFICATION` | The message reporting contains an eligible balance that may or may not include an entitlement calculation or a revised entitlement calculation. | | `REPLACEMENT` | The message replaces a previously sent message. | | `REMINDER` | The message is sent as a reminder of an event taking place. | | `WITHDRAWAL` | The message voids a previously sent notification due to the withdrawal of the event or offer by the issuer. | ## Notification examples ### Example: Cash dividends The following example is a corporate action notification for cash dividends. ```json { "id": "d0cb44d6-d61f-4272-b0f5-a8c7349b8b9a", "created_at": "2024-09-05T12:03:43.201937702Z", "type": "CORPORATE_ACTION.UPDATED", "object": { "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f", "instrument": { "uuid": "48b798b7-3a62-4f30-8307-ee94d35b21b7", "isin": "FR0010524777", "name": "Lyxor MSCI New Energy ESG Filtered (DR) ETF" }, "name": "CASH_DIVIDEND", "iso_type": "DVCA", "currency_denomination": "EUR", "mandatory_voluntary_indicator": "MANDATORY", "announcement_status": "PRELIMINARY_ANNOUNCEMENT_CONFIRMED", "function_of_message": "NEW", "announcement_date": "2023-11-09", "ex_date": "2023-12-04", "record_date": "2023-12-05", "options": [ { "option_number": "001", "option_type": "CASH", "option_details": { "default_option": "TRUE" }, "movements": [ { "movement_type": "CASH", "movement_details": { "credit_debit_indicator": "CREDIT", "payment_date": "2023-12-10", "gross_dividend": "0.54", "withholding_tax": "0.30", "currency": "EUR" } } ] } ] }, "webhook_id": "dbebe0ac-a407-4d43-a404-b8fe846eb691" } ``` ### Example: Name & ISIN change Name changes are one of the most common corporate actions, and there are two variants: - **Name change without ISIN change** In this case, only the name of the instrument changes and no position updates need to be made. This type of name change is handled solely by updating the underlying instrument information. The client receives updates about this event via the instruments endpoint or via a webhook. - **Name change with ISIN change** In this case, not only the name of the instrument changes, but also its underlying ISIN. This means that the ‘old’ position of the instrument (i.e. assigned to the old ISIN) must be debited and a corresponding new position containing the updated ISIN must be credited. **Example name with ISIN change** ```json { "id": "ce14bbc0-e729-47ca-81f1-3acdb52a5919", "name": "CHANGE", "options": [ { "movements": [ { "movement_type": "SECURITIES_OPTION", "movement_details": { "ratio": { "debit_factor": "1.", "credit_factor": "1." }, "payment_date": "2026-03-02", "rounding_indicator": "UNSPECIFIED", "credit_debit_indicator": "CREDIT" } }, { "movement_type": "SECURITIES_OPTION", "movement_details": { "instrument": { "isin": "GB0000536739", "name": "Ashtead Group PLC Registered Shares LS -,10", "uuid": "358f7e78-9f50-4c4b-8933-f816ad2772a2" }, "payment_date": "2026-03-02", "credit_debit_indicator": "DEBIT" } } ], "option_type": "SECURITIES_OPTION", "option_number": "001", "option_details": { "default_option": "TRUE", "minimum_quantity": "QUANTITY_TYPE_CODE_UNIT/1,", "minimum_multiple_quantity": "QUANTITY_TYPE_CODE_UNIT/1," } } ], "iso_type": "CHAN", "instrument": { "isin": "GB0000536739", "name": "Ashtead Group PLC Registered Shares LS -,10", "uuid": "358f7e78-9f50-4c4b-8933-f816ad2772a2" }, "record_date": "2026-02-27", "announcement_date": "2026-01-28", "announcement_status": "PRELIMINARY_ANNOUNCEMENT_CONFIRMED", "function_of_message": "NEW", "currency_denomination": "GBP", "mandatory_voluntary_indicator": "MANDATORY" } ```