Research11 min read

Corporate Actions Data in India: A Developer's Guide

By Deion DSouza
Drishti logo beside an upward chart illustrating corporate actions data in India

Corporate actions data in India looks simple until you try to put it into a portfolio ledger. A dividend can fit in one row. A demerger may arrive as a scheme, approval, record-date notice, allotment, listing update, and cost-allocation document spread across months.

A useful corporate actions API in India gives you the filings and extracted terms. Your application still has to decide which records describe the same event, when that event becomes effective, and how one security turns into another.

This guide shows the data model and pipeline we would build for that job.

Key takeaways

  • Store the original announcement before you normalize anything.
  • Keep announcement, corporate event, and security as separate entities.
  • Treat symbols and International Securities Identification Numbers (ISINs) as time-bound identifiers, not permanent company IDs.
  • Model event state. A board approval is not the same as a record date, allotment, or listing.
  • Make every portfolio update idempotent so a repeated filing cannot credit shares twice.
  • Keep missing values as null. Do not guess a ratio, date, resulting ISIN, or cost allocation.
  • Drishti can supply filtered announcements, structured extraction when available, and source-document access. Cross-record lifecycle linkage remains application logic.

What counts as corporate-actions data in India?

For an investor-facing product, “corporate actions” is wider than a dividend calendar. You will usually need:

EventTerms your system may need
Dividendamount per share, face value, record date, ex-date, payment date
Bonus issuebonus ratio, record date, allotment date, resulting quantity
Stock splitold and new face value, ratio, record date, effective date
Rights issueentitlement ratio, issue price, record date, offer period, subscribed quantity
Buybackmethod, price, maximum shares, record date, accepted quantity
Merger or amalgamationparent entities, exchange ratio, effective date, old and resulting securities
Demergerparent security, resulting company, entitlement ratio, listing date, cost allocation
Name, symbol, or ISIN changeold identifier, new identifier, effective date, exchange

The official NSE corporate-actions page exposes fields such as symbol, purpose, face value, ex-date, record date, and book-closure dates. NSE also documents a downloadable corporate-action report with symbol, series, ISIN, record date, ex-date, and action description in its market-data report guide.

Those dates are not optional decoration. Regulation 42 of the SEBI Listing Obligations and Disclosure Requirements covers record-date notices for dividends, rights and bonus shares, mergers, demergers, splits, and other actions.

The identity fields matter just as much. CDSL's issuer instructions use parent ISIN, benefit ISIN, ratio, record date, and effective date when an issuer or registrar and transfer agent sets up a corporate action. NSDL describes a similar base-ISIN and credit-ISIN model for automated actions such as bonus issues, demergers, and amalgamations. See the official CDSL issuer instructions and NSDL master circular.

That gives you the first design rule: a ticker is a label. It is not the security's full history.

A corporate-action feed is not a security lifecycle

An exchange announcement is a source record. A corporate event is the real-world change described by one or more records. A security is the instrument affected by that event.

Do not collapse those three concepts into one table.

Code
Announcement A: board approves a demerger
             |
Announcement B: record date is fixed
             |
Announcement C: resulting shares are allotted
             |
Announcement D: new security starts trading
             v
Corporate event: one demerger
             |
             +--> Parent security (old symbol + ISIN)
             |
             +--> Resulting security (new symbol + ISIN)

If you treat every announcement as a completed action, you will update holdings too early and possibly more than once. If you group every filing by company and category, you may join unrelated events from different dates.

The safe approach is boring on purpose: preserve each source record, build a separate event, attach evidence to it, then apply the event only when your rule for that action is satisfied.

Store this model before writing portfolio logic

You do not need a graph database to start. A relational model works if the relationships are explicit.

Code
type CorporateActionEvent = {
  eventId: string
  eventType:
    | "dividend"
    | "bonus"
    | "split"
    | "rights"
    | "buyback"
    | "merger"
    | "demerger"
    | "identifier_change"
  status: "proposed" | "approved" | "record_date_set" | "effective" | "listed"
  parentSecurityIds: string[]
  resultingSecurityIds: string[]
  recordDate: string | null
  effectiveDate: string | null
  ratio: { numerator: number; denominator: number } | null
  sourceAnnouncementIds: string[]
  needsReview: boolean
}

Back that type with a few focused tables:

  • announcements: immutable vendor/exchange payload, source ID, published time, category, summary, and document reference.
  • securities: your stable internal ID, instrument type, exchange, and issuer relationship.
  • security_identifiers: symbol, scrip code, or ISIN with valid_from and valid_to.
  • corporate_events: normalized event type, current state, dates, and review status.
  • event_securities: parent, resulting, or affected security roles.
  • event_terms: ratio, price, cash amount, fractional treatment, and cost-allocation data.
  • event_documents: link between an event and each scheme, approval, record-date, allotment, or listing document.
  • portfolio_postings: the cash or quantity changes created by an effective event.

Keep the raw payload. Normalization rules will change. You need to be able to replay them without downloading every filing again.

Build an Indian corporate actions data pipeline in seven steps

1. Ingest announcements as immutable records

Use the source record ID as the first deduplication key. Save the payload and a hash. If the same ID arrives again with a changed payload, store a revision instead of silently overwriting it.

2. Normalize the event type

Map provider categories to your smaller internal vocabulary. Do not throw away the original category or related categories.

One filing may be an Outcome of Board Meeting with Dividend as a related category. Another may have Dividend as its main category. Both can carry useful dividend terms.

3. Assign an event state

Read the language and document type:

  • “board approved” usually means approved;
  • “record date fixed” means record_date_set;
  • “shares allotted” may mean effective for your entitlement engine;
  • “trading approval” or “listing effective” can move a resulting security to listed.

These are policy rules, not universal truths. Version them, log which rule fired, and send ambiguous cases to review.

4. Resolve security identity over time

Match using more than the current symbol. Prefer exchange plus ISIN for a listed instrument, while retaining the issuer, scrip code, old symbols, and validity dates.

For a merger or demerger, create the resulting security only when you have enough evidence. A company name in a scheme is not automatically a listed instrument. The symbol and ISIN may arrive later.

5. Parse event terms without filling gaps

Event-specific extraction belongs behind a typed boundary. A dividend parser should not know about merger ratios. A merger parser should not pretend its exchange ratio is a bonus ratio.

Store both the normalized value and the source text. If the filing says 1:20, keep that text even after parsing it into { numerator: 1, denominator: 20 }.

6. Link records into one event

Start with deterministic signals: issuer, event type, scheme name, announced dates, related entities, and explicit references to earlier filings. Use a confidence score if you need fuzzy matching, but never let a low-confidence link update holdings.

This is where most of the real work sits. The source records are usually truthful. The hard part is proving that six truthful records describe one lifecycle.

7. Emit idempotent portfolio postings

Create a stable posting key such as:

Code
{portfolio_id}:{event_id}:{security_id}:{posting_type}

Put a unique constraint on it. If a job retries, the second write should do nothing.

Never let a summary directly mutate holdings. It should create or update an event. Only the entitlement or accounting stage should create portfolio postings.

Fetch NSE and BSE corporate actions with Drishti

Drishti's List announcements endpoint accepts symbol, date, category, important, and detailed filters. Category names are exact, so read the current announcement category list instead of hard-coding a remembered label.

Code
curl -G "https://developers.manasija.in/v1/announcements" \
  -H "Accept: application/json" \
  -H "X-API-Key: $DRISHTI_API_KEY" \
  --data-urlencode "categories=Merger" \
  --data-urlencode "categories=Demerger" \
  --data-urlencode "categories=Stock Split" \
  --data-urlencode "categories=Bonus Issue" \
  --data-urlencode "categories=Rights Issue" \
  --data-urlencode "categories=Dividend" \
  --data-urlencode "categories=Buyback" \
  --data-urlencode "categories=Change in company name" \
  --data-urlencode "detailed=true" \
  --data-urlencode "limit=20"

Detailed rows can include the announcement ID, symbol, company, publication date, category, related categories, summary, and event-specific extracted_information when extraction is complete.

Treat those nested fields as optional. A dividend record may have a record date but no amount. A scheme announcement may name the resulting company before a listed symbol or ISIN exists. That is normal partial data, not a reason to invent a value.

Announcement REST and WebSocket responses do not include attachment URLs or internal R2 keys. Keep source-document workflows separate from the announcement feed and preserve a clean evidence trail in your own event model.

For near-live delivery, use the documented WebSocket stream. For backfills, reconciliation, and deterministic retries, use REST or an official SDK. An interactive MCP session is useful for research and payload inspection; it should not be your production event processor. The boundary is explained in four ways to build with Drishti MCP.

Apply events without corrupting portfolio history

Different actions need different posting rules.

ActionPortfolio treatment
DividendCalculate eligibility from the record-date position; post cash only when your product's payment rule is met
BonusAdd quantity using the entitlement ratio; do not create a cash purchase
SplitChange quantity and per-share basis while preserving total basis, subject to your accounting rules
RightsCreate an entitlement first; add shares only for the quantity actually subscribed and allotted
BuybackRemove only accepted or tendered quantity, not the maximum offer size
MergerRetire or reduce the parent security and add the resulting security using the final exchange ratio
DemergerKeep the parent where applicable, add the resulting security, and store the published cost allocation separately
Identifier changeClose the old identifier's validity period and attach the new identifier to the same security when the instrument itself is continuous

Do not calculate tax treatment from a short announcement summary. Fractional shares, cash in lieu, and cost-of-acquisition allocation often live in later documents. Keep those fields pending until you have the source your accounting policy requires.

And do not rewrite old transactions with today's ticker. A 2021 trade should retain the identifier known in 2021 while resolving to the same internal security or lifecycle today. That is how you preserve an auditable history.

Production checklist for an Indian corporate action data feed

  • Raw announcement payload and source ID are immutable.
  • Symbols, scrip codes, and ISINs are stored with validity dates.
  • Event state separates approval, record date, effective date, allotment, and listing.
  • Event-specific fields are nullable and keep their source text.
  • Every event links back to the filings that support it.
  • Low-confidence cross-record links require review.
  • Portfolio postings have stable idempotency keys and database uniqueness.
  • Backfill and live-stream records pass through the same normalization rules.
  • Reconciliation checks exchange records against your stored events.
  • API keys stay server-side and out of logs, browser bundles, and examples.

Frequently asked questions

What is the best primary key for corporate actions data?

Use your own stable event_id for the normalized event and retain every provider or exchange announcement ID as a source key. An announcement ID identifies a record. It does not always identify the full multi-document event.

Can I use a symbol to track a security across a merger or demerger?

No. Symbols can change, be reassigned, or appear only after a resulting company lists. Use a stable internal security ID and store symbol, scrip code, and ISIN history with validity dates.

What is the difference between record date and effective date?

The record date determines which holders are considered for an entitlement. The effective date is when the action takes legal or operational effect. Depending on the event, allotment, credit, and listing can happen later. Store each date separately.

Does Drishti provide a complete security-lifecycle graph?

Not as a single canonical lifecycle endpoint today. Drishti provides corporate announcements, category filters, detailed extraction when available, and source-document resolution. Your application should link related records, maintain identifier history, and apply its own review and accounting rules.

Should I use REST, WebSockets, or MCP?

Use REST for backfills, explicit fetches, and reconciliation. Use WebSockets for supported near-live delivery. Use MCP while researching records, checking current documentation, or prototyping with an agent. Production portfolio updates belong in deterministic application code.

Start with one event family

Do not build every action on day one. Start with dividends or bonus issues, where the state and entitlement rules are easier to test. Pull a small filtered sample from the Drishti Sandbox, retain every null and source ID, and replay the same records until your postings are deterministic.

Then take on demergers. That is where you find out whether you built a feed—or a lifecycle.

Keep exploring

Related articles