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.

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

Announcement flow

Below you can find an overview of our announcement flow and related operations processes.

The information sent to Upvest clients via the Investment API includes:

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.

Announcement status

Corporate action notifications can be assigned different statuses during their lifecycle. Upvest discloses these statuses in accordance with ISO standards.

The announcement_status field provides information on the status of information known about a corporate action on the mark.

Notification examples

Example: Cash dividends

The following example is a corporate action notification for cash dividends.

{
    "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

{
"id": "8962b496-8d42-4560-bfab-10490dd1a721",
"created_at": "2021-07-0916:23:45.00Z",
"type": "CORPORATE_ACTION.NEW",
"object": {
    "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f",
    "type": {
        "id": "CHAN",
        "name": "Change"
    },
    "instrument": {
        "uuid": "48b798b7-3a62-4f30-8307-ee94d35b21b7",
        "isin": "FR0010524777",
        "name": "Lyxor MSCI New Energy ESG Filtered (DR) ETF"
    },
    "details": {
        "dates" : {
            "declaration_at": "2021-07-01T14:10:00.00Z",
            "effective_at": "2021-07-04T14:10:00.00Z",
            "payment_at": "2021-07-08T14:10:00.00Z"
        },
        "options": [{
            "option_type": "SECURITY",
            "security_movements": [{
                "movement_kind": "DEBIT",
                "instrument_id": "48b798b7-3a62-4f30-8307-ee94d35b21b7",
            }, {
                "movement_kind": "CREDIT",
                "instrument_id": "010ad7e2-db05-466e-8340-de836ede03bf",
                "ratio": {
                    "ratio_from": 1,
                    "ratio_to": 1
                }
            }]
        }]
    },
    "created_at": "2021-07-04T14:10:00.00Z",
    "updated_at": "2021-07-04T14:12:00.00Z",
    "status": "PLANNED"
}