# Corporate Action Events

Notifies tenants of corporate actions impacting securities holdings across 
all accounts within the organization. This webhook sends updates for dividends, 
stock splits, mergers, tender offers, and other events affecting positions at 
the organizational level.

Endpoint: POST Corporate Action Events
Version: 1.114.0

## Request fields (application/json):

  - `id` (string, required)
    Event unique identifier

  - `created_at` (string, required)
    Date and time when the event was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)

  - `type` (string, required)
    Event type
    Enum: "CORPORATE_ACTION.UPDATED"

  - `object` (object, required)
    Object representing corporate action and its related processing status

  - `object.id` (string, required)
    Unique internal identifier assigned to a corporate action by Upvest.

  - `object.iso_type` (string, required)
    The identifier of a corporate action type [ISO Code](https://www.iso20022.org/15022/uhb/mt564-5-field-22f.htm)

  - `object.instrument` (object, required)
    Entity representing the financial instrument.

  - `object.instrument.uuid` (string)
    Unique internal identifier assigned to an instrument by Upvest.

  - `object.instrument.isin` (string)
    International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).

  - `object.instrument.name` (string)
    Name of the instrument.

  - `object.name` (string)
    Name of the corporate action type

  - `object.currency_denomination` (string)
    Currency in which a financial instrument is currently denominated. [ISO](https://www.iso20022.org/15022/uhb/mt564-24-field-11a.htm).
    Enum: "UNSPECIFIED", "EUR", "USD", "GBP", "SEK", "JPY", "CHF", "CNY", "AUD", "CAD", "HKD", "NOK", "NZD", "AED", "AFN", "ALL", "AMD", "ARS", "AZN", "BAM", "BDT", "BGN", "BHD", "BND", "BOB", "BRL", "BYR", "BZD", "CLP", "COP", "CRC", "CSD", "CZK", "DKK", "DOP", "DZD", "EEK", "EGP", "ETB", "GEL", "GTQ", "HNL", "HRK", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "KES", "KGS", "KHR", "KRW", "KWD", "KZT", "LAK", "LBP", "LKR", "LTL", "LVL", "LYD", "MAD", "MKD", "MNT", "MOP", "MVR", "MXN", "MYR", "NIO", "NPR", "OMR", "PAB", "PEN", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SGD", "SYP", "THB", "TJS", "TMT", "TND", "TRY", "TTD", "TWD", "UAH", "UYU", "UZS", "VEF", "VND", "XOF", "YER", "ZAR", "ZWL"

  - `object.mandatory_voluntary_indicator` (string)
    Indicates whether a corporate action is mandatory, voluntary or choosable.
    Enum: "UNSPECIFIED", "MANDATORY", "VOLUNTARY", "CHOOSABLE"

  - `object.announcement_status` (string)
    Indicates the completeness of the announcement of a corporate action [ISO](https://www.iso20022.org/15022/uhb/mt564-7-field-25d.htm).
    Enum: "UNSPECIFIED", "COMPLETE", "COMPLETE_UNCONFIRMED", "WITH_ENTITLEMENT", "PRELIMINARY_ANNOUNCEMENT_CONFIRMED", "PRELIMINARY_ANNOUNCEMENT_UNCONFIRMED"

  - `object.function_of_message` (string)
    The function of the message is specified in this field. More details under [ISO definitions](https://www.iso20022.org/15022/uhb/mt564-4-field-23g.htm).
    Enum: "UNSPECIFIED", "ADDITIONAL_BUSINESS_PROCESS", "CANCELLATION_ADVICE", "NEW", "ELIGIBLE_BALANCE_NOTIFICATION", "REPLACEMENT", "REMINDER", "WITHDRAWAL"

  - `object.announcement_date` (string)
    Date on which a company announces a corporate event. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)

  - `object.ex_date` (string)
    The date up to which a particular share is eligible for the upcoming corporate action. If buyers purchase a share on the ex-date, they are not entitled to participate in the upcoming corporate action; but the seller still would be. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)

  - `object.record_date` (string)
    Date on which the issuer reviews its records to determine its authorised shareholders. The authorised shareholders are those who are affected by the respective corporate action. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)

  - `object.options` (array)
    Available corporate action options.

  - `object.options.option_number` (string)
    Number to identify the available options for corporate actions.

  - `object.options.option_type` (string)
    Type of option based on [ISO CAOP](https://www.iso20022.org/15022/uhb/mt564-57-field-22f.htm).
    Enum: "UNSPECIFIED", "ABSTAIN", "VOTE_AGAINST_MANAGEMENT", "BENEFICIAL_OWNER_BREAKDOWN_REQUEST", "BONUS_SHARE_PLAN", "BUY_UP", "CASH_AND_SECURITIES", "CASH", "CONSENT_AND_EXCHANGE", "CONSENT_DENIED", "CONSENT_GRANTED", "CONSENT_AND_TENDER", "EXERCISE", "LAPSE", "VOTE_WITH_MANAGEMENT", "RETAIN", "NO_ACTION", "NON_QUALIFIED_INVESTOR", "PROPOSED_RATE", "OTHER", "OVERSUBSCRIBE", "PROXY_CARD", "UNKNOWN_PROCEEDS", "QUALIFIED_INVESTOR", "SECURITIES_OPTION", "SELL_ENTITLEMENT", "SPLIT_INSTRUCTION"

  - `object.options.option_details` (object)
    Details of the corporate action option.

  - `object.options.option_details.default_option` (string)
    Indicates whether the option is the default option.
    Enum: "TRUE", "FALSE"

  - `object.options.option_details.market_deadline` (string)
    Issuer or issuer's agent deadline to respond, including an election instruction to an outstanding offer or privilege. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)

  - `object.options.option_details.client_deadline` (string)
    Client deadline to respond to an outstanding offer or privilege. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)

  - `object.options.option_details.action_period_start` (string)
    Start of the period during which the specified option, or all options of the event, remains valid, for example, offer period.

  - `object.options.option_details.action_period_end` (string)
    End of the period during which the specified option, or all options of the event, remains valid, for example, offer period.

  - `object.options.option_details.minimum_quantity` (string)
    Minimum quantity of financial instrument that can be instructed.

  - `object.options.option_details.minimum_multiple_quantity` (string)
    Minimum of multiple financial instruments that can be instructed.

  - `object.options.movements` (array)
    Movements in corporate action option.

  - `object.options.movements.movement_type` (string)
    Type of the movement.
    Enum: "UNSPECIFIED", "CASH", "SECURITIES_OPTION"

  - `object.options.movements.movement_details` (object)
    Details of the movement.

  - `object.options.movements.movement_details.credit_debit_indicator` (string)
    Indicates whether the movement is a credit or a debit.
    Enum: "UNSPECIFIED", "CREDIT", "DEBIT"

  - `object.options.movements.movement_details.instrument` (object)
    Entity representing the financial instrument.

  - `object.options.movements.movement_details.instrument.uuid` (string)
    Unique internal identifier assigned to an instrument by Upvest.

  - `object.options.movements.movement_details.instrument.isin` (string)
    International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).

  - `object.options.movements.movement_details.instrument.name` (string)
    Name of the instrument.

  - `object.options.movements.movement_details.ratio` (object)
    The ratio is the numerical comparison between instruments and can be calculated in two different ways: 
* ADEX = Additional for Existing Securities. Example: You hold 10 units and the ratio is 1/5. 40 additional units are added. 
* NEWO = New to Old. Example: You hold 1000 units and the ratio is 3/11. 1000 old units are removed and 3666.6 are added.

  - `object.options.movements.movement_details.ratio.debit_factor` (string)
    Amount to be decreased.

  - `object.options.movements.movement_details.ratio.credit_factor` (string)
    Amount to be increased.

  - `object.options.movements.movement_details.payment_date` (string)
    Date on which the movement is due to take place (cash and/or securities). [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)

  - `object.options.movements.movement_details.gross_dividend` (string)
    String value, which represents a monetary amount. Amount of the cash dividend per equity before deductions or allowances.

  - `object.options.movements.movement_details.offer_price_received` (string)
    String value that represents a monetary amount. Generic cash price that the holder of the underlying security receives per product.

  - `object.options.movements.movement_details.withholding_tax` (string)
    Withholding tax rate.

  - `object.options.movements.movement_details.currency` (string)
    Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.
* EUR - Euro
* GBP - Pound Sterling
    Enum: "EUR", "GBP"

  - `object.options.movements.movement_details.rounding_indicator` (string)
    Indicator for the rounding approach for the disposition of fractions.
* BUYU - Buy securities up to the next whole number.
* CINL - Receive cash instead of fractions.
* DIST - Accept distribution of fractions in the form of securities.
* RDDN - Rounds down the entitlement to the last full unit/minimum nominal quantity, fractions are discarded.
* RDUP - Round up to the next full unit/minimum nominal quantity at no cost.
* STAN - If the fraction is greater than or equal to 0.5 of the resulting security, round up, otherwise round down as specified in the respective RDUP and RDDN codes.
* UKWN - The characteristics of the disposition of fractions are unknown.
    Enum: "BUYU", "CINL", "DIST", "RDDN", "RDUP", "STAN", "UKWN"

  - `object.options.movements.movement_details.credit_debit_factor` (string)
    Indicates whether the movement is a credit or a debit. DEPRECATED: Use credit_debit_indicator instead.
    Enum: same as `object.options.movements.movement_details.credit_debit_indicator` (3 values)

  - `object.additional_text` (string)
    Provides additional information or specifies in more detail the content of a message.

  - `webhook_id` (string, required)
    Webhook unique identifier.


## Response 200 fields