Announcements

Unified vertical timeline of dividends, rights, AGMs, mergers, and quarterly results — filterable by chip and date window

The announcements endpoint merges up to five corporate-action / financial-report sources into one event timeline. Rows sort descending by event date — the page shows the most recent disclosures first.

Method	Path	Cache TTL
`GET`	`/api/nepse/companies/{symbol}/fundamentals/announcements`	5 min

Request

curl "$BASE/api/nepse/companies/NABIL/fundamentals/announcements?types=dividends,rights&from=2024-01-01&to=2026-05-22&limit=50"

Query parameters

Param	Default	Notes
`types`	all 5	Comma-separated chip filter: `results,dividends,rights,agm,mergers`
`from`	—	Inclusive lower bound, `YYYY-MM-DD` (NPT)
`to`	—	Inclusive upper bound, `YYYY-MM-DD` (NPT)
`limit`	50	1 – 200

Unknown chips silently drop. An empty (or all-unknown) chip list expands to all 5 canonical types so the timeline never returns an accidentally-empty page.

Response

{
  "message": "ok",
  "data": {
    "symbol": "NABIL",
    "types": ["results", "dividends", "rights", "agm", "mergers"],
    "from": "2024-01-01",
    "to":   "2026-05-22",
    "limit": 50,
    "rows": [
      {
        "id": "018f5d0c-…",
        "date": "2024-08-15",
        "type": "dividends",
        "title": "Cash dividend 15% + bonus 5%",
        "fiscalYearBs": "2080/2081",
        "expand": {
          "cashPercent": 15,
          "bonusPercent": 5,
          "totalDistributionPercent": 20,
          "bookCloseDate": "2024-08-15",
          "distributionDate": "2024-09-10"
        }
      },
      {
        "id": "018f4ab2-…",
        "date": "2024-07-22",
        "type": "results",
        "title": "2080/2081 results (Q4)",
        "summary": "Results disclosed on 2024-07-22",
        "fiscalYearBs": "2080/2081",
        "expand": {
          "quarter": "Q4",
          "revenue": 18500000000,
          "netProfit": 4200000000,
          "eps": 42.0,
          "publicationDateAd": "2024-07-22",
          "disclosureFallback": false
        }
      }
    ],
    "hasMore": false,
    "note": "Quarterly results use the report's updated_at timestamp until publication dates land via Phase A backfill.",
    "dataAsOf": "2024-08-15T00:00:00+05:45",
    "servedAt": "2026-05-23T14:56:30+05:45"
  }
}

Row types

The type field discriminates the expand object. Each type has its own shape.

`dividends`

type ExpandDividends = {
  cashPercent: number;
  bonusPercent: number;
  totalDistributionPercent: number;
  bookCloseDate?: string;     // YYYY-MM-DD AD
  distributionDate?: string;
};

title is generated:

Cash + Bonus: Cash dividend X% + bonus Y%
Cash only: Cash dividend X%
Bonus only: Bonus share X%
Neither: Dividend declared

`rights`

type ExpandRights = {
  ratio: string;                  // e.g. "1:5"
  unitsAllotted?: number;
  pricePerUnit?: number;
  openingDate?: string;
  closingDate?: string;
  extendedDate?: string;
};

title: Rights offering + ( <ratio> when present).

`agm`

type ExpandAGM = {
  meetingType: string;            // AGM / EGM / SGM
  venueTime?: string;
  bookCloseDate?: string;
  agenda?: string;
};

title: <meetingType> + ( — <meetingName> when set). summary: first 280 runes of the agenda, ellipsis-suffixed when truncated.

`mergers`

type ExpandMergers = {
  newCompanyName: string;
  newCompanySymbol?: string;
  swapRatio?: string;
  action?: string;
  mouDate?: string;
  jointDate?: string;
  finalApprovalDate?: string;
  isCompleted: boolean;
  isTrading: boolean;
  constituentCompanies?: any;     // pass-through JSONB
};

title: Merger or Merger → <newCompanyName>.

`results`

type ExpandResults = {
  quarter: string;                // Q1 / Q2 / Q3 / Q4
  revenue?: number;
  netProfit?: number;
  eps?: number;
  publicationDateAd?: string;
  disclosureFallback: boolean;    // true when no publication date — date defaulted to updated_at
};

title: <fiscalYearBs> results (Q<n>). summary:

Results disclosed on <date> when publicationDateAd is set.
Reported EPS <eps> (disclosure date pending) otherwise, when EPS is known.
Disclosure date pending otherwise.

results.expand.revenue, netProfit, eps are taxonomy lookups against the report's items_map. The endpoint's note field warns FE that quarterly results use the report's updated_at timestamp as their event date until publication dates land via Phase A backfill — the chip date may be a few days off from the press release.

Pagination

limit clamps to [1, 200] with a default of 50. Each source is queried for limit+1 rows so the merge can detect overflow:

hasMore = mergedRowCount > limit
rows    = rows[:limit]      # after sort

hasMore only flags that at least one source had more rows than the cap — not which source. FE should bump limit to load more.

Sort order

1. date DESC
2. type ASC          # deterministic tiebreaker
3. id ASC

Two events on the same date stay in a stable order across requests.

`dataAsOf`

The most recent event in the timeline — not the nightly sync timestamp — so the "data as of" tooltip reflects the staleness bound by the most recent disclosure FE is showing.

Falls back to servedAt when the timeline is empty.

Caching

Key	TTL
`nepse:fundamentals:announcements:{SYMBOL}:t{sortedTypes}:f{from}:x{to}:l{limit}`	5 min

Type list is sorted before forming the cache key, so ?types=results,dividends and ?types=dividends,results hit the same entry.

Errors

Code	Reason
`200`	OK (including the empty-timeline case)
`404`	Symbol not in `nepse_companies`
`500`	DB error during any of the up-to-5 source queries

Announcements

On this page