Corporate Actions

Overview

Corporate Actions are accessible through two levels of the API:

1. Instrument-level (/v1/corporate_actions) - all Corporate Actions affecting instruments in your universe. Use this to learn about upcoming events and track their processing status.
2. Account-level (/v1/accounts/{account_id}/corporate_actions) - the per-account result of a Corporate Action, where applicable (e.g. amounts, taxes, and the securities account involved for cash dividends).

Both endpoints are polymorphic, discriminated by the type field. Refer to the API reference for supported types and filtering options.

Events

corporate_action.created

Subscribe to this event to be notified when a new Corporate Action appears for an instrument in your universe. You also receive it when an instrument with a pending Corporate Action is added to your universe.

The context payload:

{
  "type": "corporate_action.created",
  "context": {
    "corporate_action": "ca_b042d117bc254fcba9d845800c413695",
    "corporate_action_type": "cash_dividend",
    "instrument": "DE0005909006"
  }
}

On receiving this event, call GET /v1/corporate_actions/{id} to fetch the full details.

update.created / update.succeeded

Emitted when the terms of a Corporate Action change. The corporate_action field is included in the context. Subscribe to update.succeeded and call GET /v1/corporate_actions/{id} to refresh your local state.

Account-level event (type-specific)

Each Corporate Action type has its own per-account event. For cash dividends, this is dividend_distribution.created.
The context contains account, securities_account, corporate_action and dividend_distribution.

On receiving this event, refer to the dividend_distribution field to call GET /v1/accounts/{account_id}/corporate_actions/{dividend_distribution_id} and fetch the per-account result.

corporate_action.processed

Emitted when all accounts have been processed. The Corporate Action status is now processed (final).

The case of Income Distributions

Income Distributions differ from the above:

• No corporate_action.* events are emitted at the instrument level.
• Per affected account, an income_distribution.created event is emitted. The income_distribution field in its context refers to GET /v1/accounts/{account_id}/income_distributions/{income_distribution_id}, not to the account-level Corporate Action endpoint.
• The account-level Corporate Action endpoint also includes Income Distributions. The response payload is identical to the dedicated endpoint, except for a different id format and the addition of a type field (set to income_distribution).

Further Reading

• List Corporate Actions (Instrument-level)
• Get Corporate Action (Instrument-level)
• List Corporate Actions (Account-level)
• Get Corporate Action (Account-level)
• Data Mirroring using Events