Skip to content
Dividend Election

List dividend election events

Returns the current account's dividend election events by market and status. These are corporate actions, such as scrip dividends, where the Client chooses between cash and shares. Each event includes registered shares, key dates, cash options, and the scrip option. Use it for the Dividend Election list, details, and history pages.

Pass UNSELECTED in state to get events awaiting election. Pass SELECTED or DISTRIBUTED to get pending or distributed events for history. The Broker App sets page to 1 and size to 100 to fetch everything at once, and locates an event by ann_id from the list on the details page. The Broker configures which markets are available.

Events not elected before the deadline are handled with the default cash option.

POSThttps://api.lbkrs.com/v1/app/be/list

Request body application/json

searchobjectrequired

Query conditions

Child attributes
pageintegerrequired

Page number, starting from 1. The Broker App passes 1

sizeintegerrequired

Records per page. The Broker App passes 100

filtersobjectrequired

Filters

Child attributes
marketstringrequired

Market code, such as HK or US. The Broker configures the available values

statestringrequired

Event status:

  • UNSELECTED - Awaiting election
  • SELECTED - Elected, pending distribution
  • DISTRIBUTED - Distributed
Values
UNSELECTED
SELECTED
DISTRIBUTED

Responses

HTTP 200The request succeeded. The response body contains the result of the “List dividend election events” operation.
Standard response envelopecodemessagedata
dataobjectdata structure
dataarray<object>

Events. Empty when there are no records

Child attributes
ann_idinteger

Event ID used for calculation and submission

counter_idstring

Security ID of the holding, such as ST/HK/700

counter_codestring

Ticker of the holding

counter_namestring

Name of the holding

marketstring

Market code, such as HK

origin_quantitystring

Registered shares, that is, the shares eligible for this corporate action

record_dateinteger

Record date as a Unix timestamp in seconds

election_frominteger

Election start time as a Unix timestamp in seconds

in_side_election_tointeger

Election deadline as a Unix timestamp in seconds. The Client must submit before this time

payable_atinteger

Expected payment date as a Unix timestamp in seconds

choose_rightsstring

Elected option, present only for events already elected:

  • CashDividend - All cash
  • ScripDividend - All shares
  • ScripAndCash - Shares and cash
distribute_statestring

Distribution status, used in history:

  • SELECTED - Elected, pending distribution
  • DISTRIBUTED - Distributed
cash_eventarray<object>

Cash options. When there is more than one, the Client can choose by currency

Child attributes
event_idstring

Option ID used when submitting the election

currencystring

Dividend currency, such as HKD

amountstring

Estimated cash amount if all registered shares elect this option, as a decimal string

surplus_valuestring

Dividend per share, as a decimal string. Submit it as cash_surplus_value when calculating a stock-and-cash split

is_defaultboolean

Whether this is the default cash option. If none is marked, use the first option

scrip_eventobject

Scrip option (shares instead of cash)

Child attributes
event_idstring

Option ID used when submitting the election

counter_idstring

Security ID of the shares to be distributed, such as ST/HK/700

counter_codestring

Ticker of the shares to be distributed

counter_namestring

Name of the shares to be distributed

currencystring

Currency of the conversion price and per-share value

exchange_pricestring

Conversion price, as a decimal string

surplus_valuestring

Dividend per share for the scrip option, as a decimal string. Submit it as stock_surplus_value when calculating a stock-and-cash split

stock_payablestring

Estimated shares receivable if all registered shares elect the scrip option. It is also the upper limit of shares that can be allocated in a stock-and-cash split

pageinteger

Current page number

sizeinteger

Records per page

totalinteger

Total number of records

Whale Docs