API status

Implementing

In this section you will learn how to implement corporate actions with the Investment API.

Preparation

The prerequisites for implementing corporate actions with the Investment API are:

  1. You have agreed in advance with your Upvest Launch Manager during the integration phase the following:

    • the scope of the ISIN (the asset types correspond to CA types)

    • the domicile.

  2. You have updated your Terms & Conditions to cover voluntary/ optional corporate actions processing.
    Some events are choosable and offer the user (shareholder) various options. Using Upvest's standard approach, we always choose the cash option if this exists, otherwise we fall back on the custodian bank's standard approach. This has to be adapted in your Terms & Conditions.

1. Subscribing to corporate action notifications

Corporate actions are made public on the market on the announcement date. After the company has determined the shareholders entitled to dividends on the record date, Upvest makes the corresponding notification available. This also includes any subsequent update events that become known through new information about this event.

To receive such notifications about corporate actions, you only have to subscribe to webhooks with the corresponding event type CORPORATE_ACTION.

Read our guide to learn more about webhooks registration.

Once you are registered, you will receive webhooks for corporate actions in which you or your users are involved.

2. Positions changes

On the payment date, the corresponding securities and cash movements are booked for all eligible users and reflected in position changes.

You will find detailed information on how positions work and how to implement it in the 'Positions' guide and the Positions API.

3. Reports

PDF reports for each specific corporate action are generated within seconds after the corporate action processing being completed and can be sent to end users.

See Reports API

Example Transaction report

After the corporate actions have been carried out and payment has been made for them, the user receives a corresponding transaction report.

{
  "id": "bed637ec-b6d1-461c-b8ea-f11118969496",
  "account_group_id": "a1d23c45-5bb5-4704-ad4a-74d4090b2398",
  "booking_date": "2023-12-10T09:07:23.520751Z",
  "value_date": "2023-12-10T09:07:23.520751Z",
  "instrument":
  {
    "uuid": "48b798b7-3a62-4f30-8307-ee94d35b21b7",
    "isin": "FR0010524777"
  },
  "account_id": "bcdeeabf-04ca-4c0b-b799-abcbae2fd5b7",
  "delta":
  {
    "amount": "1.08",
    "currency": "EUR"
  },
  "taxes":
  [
    {
      "amount": "0.00",
      "currency": "EUR",
      "type": "TOTAL"
    }
  ],
  "type": "CASH_DIVIDEND",
  "created_at": "2023-12-10T09:07:23.975621Z",
  "updated_at": "2023-12-10T09:07:24.037186Z",
  "references":
  [
    {
      "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f",
      "type": "CORPORATE_ACTION"
    },
    {
      "id": "1d643699-6eac-454c-b294-bc4a87992069",
      "type": "CORPORATE_ACTION_TRANSACTION_ID"
    }
  ]
}

Treasury reports

For cash-based corporate actions, when a settlement event occurs, Upvest sends a treasury report event detailing the gross and net amounts distributed. Further details can be found here.

Depending on the cash configuration, the cash is either distributed to

  • Post-trade settlement: the clients' pooling account

  • Pre-funding: the respective bank accounts of the end users.

4. Settlement

Settlement takes place when Upvest carries out the necessary treasury transactions for clients on the payment date. Securities and cash movements are visible via our /transactions endpoint, allowing for easy reconciliation.

5. Taxes (Germany only)

Taxes are calculated, withheld, paid and reported to the (German) tax authorities according to the users’ individual tax situations and respective corporate action requirements. The respective taxes may include the payment and deduction of international and financial transactions taxes.

See Tax Collection Events

6. Blocking period

For corporate actions involving the debiting of securities (or a detailed instruction process), the relevant securities are blocked to ensure that the corporate action can be settled without financial loss.

The blocking period depends on the timing of the corporate action and may take a few days (e.g. 5 days in advance) to allow for settlement and processing times.

In the event of a corporate action ‘delisting’, the ISINs concerned will no longer be tradable on public exchanges and Upvest will inform our clients so that they can take appropriate measures, for example to adapt their user facing frontend.

Was this page helpful?