Dividends schemas

Data models returned by Dividends endpoints.

DividendHistory

{
  "instrument": {
    "isin": string
  },
  "entity": {
    "name": string
  },
  "listing": {
    "symbol": string | null,
    "mic": string
  },
  "data": [DividendRecord],
  "meta": {
    "paging": ClassicPaging
  }
}

instrumentobject

isinstring

example: GB0005405286

entityobject

namestring

example: HSBC Holdings plc

listingobject

symbolstring | null

example: HSBA

micstring

data[DividendRecord]

metaobject

pagingClassicPaging

Classic page-based pagination response

DividendProjection

The next dividend, projected from the median gap between the issuer's recent ones. Omitted entirely when there are too few dividends to read a rhythm from, when the gaps are too irregular to have a meaningful median, or when the issuer is already overdue — a company that has stopped paying must not keep generating dates.

{
  "type": string<enum>,
  "sequence": integer,
  "declarationDate": string<date>,
  "exDate": string<date>,
  "paymentDate": string<date>,
  "basis": string<enum>,
  "basedOn": integer
}

typestring<enum>

Allowed values: "INTE", "FINL", "REGR", "SPEC"

sequenceinteger

The next ordinal in the run, wrapping to 1 after the last one the issuer uses. The run length is read from what the issuer actually pays, not assumed.

example: 3

declarationDatestring<date>

When the issuer is expected to declare. This is the date to show during the gap between dividends.

exDatestring<date>

paymentDatestring<date>

basisstring<enum>

Always estimated. Nothing on this object is stated by the issuer.

Allowed values: "estimated"

basedOninteger

How many gaps the median was taken over, so a client can refuse a thin projection.

example: 8

DividendRecord

{
  "type": string<enum>,
  "sequence": integer,
  "financialYear": {
    "endDate": string<date>,
    "basis": string<enum>
  },
  "status": string<enum>,
  "amount": {
    "value": number,
    "currency": string,
    "unit": string<enum>
  },
  "declarationDate": string<date>,
  "exDate": string<date>,
  "recordDate": string<date>,
  "paymentDate": string<date>,
  "disclosure": {
    "id": string,
    "href": string
  }
}

typestring<enum>

ISO 15022/20022 dividend type: INTE interim, FINL final, REGR regular or ordinary, SPEC special. There is no quarterly code — quarterly describes how often a dividend is paid, not which kind it is, so a quarterly interim is INTE with a sequence.

Allowed values: "INTE", "FINL", "REGR", "SPEC"

example: INTE

sequenceinteger

Ordinal within the financial year — 2 for a second interim. Omitted where the announcement states no ordinal, which is usual for an issuer paying one interim and one final.

example: 2

financialYearobject

The financial year this dividend is a distribution for. Present on every record where we can say it without guessing, and absent otherwise — a missing financialYear is never an estimate. Paying in February does not make it a February dividend, so this is the field to group on for a per-year total or a cover ratio, not paymentDate.

endDatestring<date>

The last day of that financial year.

example: 2025-12-31T00:00:00.000Z

basisstring<enum>

stated where the announcement named the year itself. derived where it did not, and we resolved it from the same issuer's other filings — the month and day its year ends, and how far from that end it pays. Both are safe to render; basis is there so a client that wants to show only the issuer's own words can.

Allowed values: "stated", "derived"

example: stated

statusstring<enum>

proposed where the dividend still needs a shareholder vote, which is normal for a final announced with results. A proposed dividend can be voted down.

Allowed values: "declared", "proposed"

amountobject

valuenumber

example: 4.6

currencystring

ISO 4217 code, whether the figure is in the major or minor unit. Omitted where the announcement stated no currency — some issuers print a bare figure.

example: GBP

unitstring<enum>

Whether the figure is in the major unit (pounds, dollars) or the minor unit (pence, cents), as the announcement printed it. Never converted. Omitted where the announcement labelled no unit at all.

Allowed values: "major", "minor"

example: minor

declarationDatestring<date>

The date the dividend was declared. Falls back to the announcement date.

exDatestring<date>

The ex-dividend date. Omitted where the announcement did not state one — it is set by the exchange and is not always in the issuer's filing.

recordDatestring<date>

paymentDatestring<date>

disclosureobject

The announcement this record comes from.

idstring

example: 2026-02-12#7502S

hrefstring

Path to the full announcement.

DividendSummary

{
  "instrument": {
    "isin": string
  },
  "entity": {
    "name": string
  },
  "listing": {
    "symbol": string | null,
    "mic": string
  },
  "data": {
    "current": any,
    "next": DividendProjection
  }
}