Track a corporate action

A corporate action keeps one id, sourceCaId, for its whole life, and gets a new version on every change. Each version is published as one event whose data is the whole object as of that version, and can be read back at any time. Your job is to keep the latest version of each one and to react to what changed.

The lifecycle

ANNOUNCED ─► CONFIRMED ─► ELECTION_OPEN ─► ENTITLEMENTS_FIXED ─► SETTLING ─► COMPLETED
                │                                                              
                └──► POSTPONED (dates cleared, until new ones are set)   ──► CANCELLED

Status	Meaning
`ANNOUNCED`	Published; terms may be `PRELIMINARY` with `null` values
`CONFIRMED`	Terms and dates confirmed; `dataCompleteness` is `COMPLETE`
`ELECTION_OPEN`	Holders can elect among `options` (corporate actions with options, and voluntary ones)
`ENTITLEMENTS_FIXED`	The entitlement snapshot was taken at `dates.snapshotTime`
`SETTLING`	Being executed: payment, multiplier change, delivery
`COMPLETED`	Terminal. `settlement` carries the contracts, transactions and totals
`POSTPONED`	Dates cleared; a later `ca.action.updated` sets new ones and the status resumes
`CANCELLED`	Terminal. `cancellationReason` says why

Not every corporate action goes through every status: a mandatory cash dividend never opens an election, and ops-executed types can move straight from CONFIRMED to SETTLING.

The events, version by version

Event	What changed	Fields to read
`ca.action.created`	Version 1	Everything. `supersedesCaId` when it replaces another
`ca.action.updated`	Terms completed, dates set, status confirmed, in the normal course	`changedFields`
`ca.action.corrected`	A published value was wrong	`changedFields`, `correctionReason`
`ca.action.postponed`	Dates moved or cleared	`dates`, `status`
`ca.action.status_changed`	The lifecycle moved: `ELECTION_OPEN`, `ENTITLEMENTS_FIXED`, `SETTLING`	`status`
`ca.action.cancelled`	Withdrawn, or replaced. Terminal	`cancellationReason`, `supersededByCaId`
`ca.action.completed`	Executed. Terminal	`settlement`

Whatever the event, apply it the same way: if version is higher than what you hold, replace the object with data. changedFields lists the dot paths that differ from the previous version (terms.grossAmountPerShare, dates.exDate) so you can tell what to show or notify. A dividend, through five versions:

v1  ca.action.created         ANNOUNCED   PRELIMINARY  terms.grossAmountPerShare: null
v2  ca.action.updated         CONFIRMED   COMPLETE     changedFields: [dataCompleteness, status, terms.grossAmountPerShare, terms.paymentAsset]
v3  ca.action.corrected       CONFIRMED                changedFields: [terms.grossAmountPerShare]   correctionReason: "Rate corrected per issuer press release"
v4  ca.action.postponed       POSTPONED                changedFields: [dates.exDate, dates.payDate, dates.recordDate, dates.snapshotTime, status]   dates: null
v5  ca.action.cancelled       CANCELLED                changedFields: [status]   cancellationReason: "Withdrawn by issuer"

Replacements

When an issuer withdraws an event and announces a new one, the new corporate action is a new sourceCaId with supersedesCaId pointing at the old one, and the old one is cancelled in the same instant with supersededByCaId pointing at the new one. Two events, two objects, one step. Keep both: the old one is the audit trail, the new one is what applies. Several corporate actions can be active on one asset at the same time, for example a dividend and a shareholder meeting. Each has its own id; relatedCaIds links the ones that belong together, such as a merger and its appraisal option.

Read the current state

curl "$BASE/corporate-actions/ca_01K7Q3ZVB8M2N4P6R8T0V2X4Z6" -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "sourceCaId": "ca_01K7Q3ZVB8M2N4P6R8T0V2X4Z6",
  "version": 2,
  "assetId": "c0a8e2f4-1b3d-4e5f-8a9b-0c1d2e3f4a5b",
  "caType": "CASH_DIVIDEND",
  "caCategory": "MANDATORY",
  "isoEventCode": "DVCA",
  "status": "CONFIRMED",
  "dataCompleteness": "COMPLETE",
  "dates": {
    "announcementDate": "2026-10-20", "exDate": "2026-11-10", "recordDate": "2026-11-10",
    "snapshotTime": "2026-11-10T01:00:00.000Z", "effectiveTime": null, "payDate": "2026-11-13",
    "electionStart": null, "responseDeadline": null, "marketExpiration": null, "votingCutoff": null, "meetingDate": null
  },
  "terms": {
    "grossAmountPerShare": "0.26", "currency": "USD",
    "paymentAsset": { "chainId": "eip155:196", "tokenAddress": "0x74b7f16337b8972027f6196a17a631ac6de26d22", "symbol": "USDC" },
    "withholdingApplies": true, "frankingOrTaxNotes": null
  },
  "options": [],
  "venueActions": { "tradingStop": { "required": false }, "poolMode": "NORMAL", "displayToHolders": true },
  "relatedCaIds": [],
  "supersedesCaId": null,
  "supersededByCaId": null,
  "description": "Quarterly cash dividend of USD 0.26 per share",
  "documents": [{ "title": "Press release", "url": "https://investor.example.invalid/dividend-2026-q4.pdf" }],
  "settlement": null
}

The object has no tokenId: a corporate action is registered once per asset and applies to every chain. The events carry the tokenId of the stream they were published on.

Any version, as published: GET /corporate-actions/{sourceCaId}/versions/{version} returns the object as it stood at that version, which is what the event of that version carried in data.
Everything on a token: GET /tokens/{tokenId}/corporate-actions, latest version of each, with status, caType, from and to filters. from/to match a corporate action when any of its dates falls in the range.

Reading the terms

terms depends on caType; options and venueActions tell you what holders and your venue need to do. Corporate actions lists the terms of each type. Three things hold for all of them:

Amounts are decimal strings. Parse them as decimals, never as floats.
Every published date and, for cash distributions and splits, every term is always present, null when not known or not applicable. dataCompleteness says whether anything is still null because it is pending.
A caType you do not know is informational. Store it, show description and documents if venueActions.displayToHolders is set, and keep applying versions.

Dates to watch

Date	What happens
`dates.snapshotTime`	The entitlement cut-off for CET holders: 8:00 pm New York time on the business day before the ex-date or record date. CETs trade around the clock, so it is an instant, and it can differ from the underlying’s record date
`dates.exDate`, `dates.recordDate`, `dates.payDate`	The underlying’s market dates, `YYYY-MM-DD` on the New York calendar
`dates.effectiveTime`	When a split’s multiplier changes, or a conversion or merger takes effect
`dates.responseDeadline`	Securitize’s deadline for an election, earlier than the market’s
`venueActions.lpExitDeadline`	When liquidity must be withdrawn from pools before a forced withdrawal

What is settled, and where, is in settlement on the COMPLETED version: distribution contracts, transaction hashes and aggregate totals for the asset. Individual payments are read on chain, from those contracts and the holders’ balances.

Get started

Guides

Concepts

Help

API reference