Announcements by Date Range

Retrieve announcements within a specified date range.

GET/3.0/announcements/date-range

Description

This endpoint retrieves corporate announcements filtered by a specified date range. Useful for analyzing announcements during specific periods and understanding corporate activity timelines.

Request

Authentication

• Type: Bearer Token
• Required: Yes

Parameters

Name	Type	Required	Description	Example
date_from	string	Yes	Start date filter (YYYY-MM-DD)	2024-01-01
date_to	string	Yes	End date filter (YYYY-MM-DD)	2024-12-31
offset	integer	No	Pagination offset for results	0

Response

Success Response (200)

{
  "status": "ok",
  "offset": 0,
  "count": 50,
  "total": 9733,
  "data": [
      {
          "id": "256580",
          "status": 1,
          "category": "E",
          "sector_code": "",
          "form_type": "PSX_NOTICE",
          "symbol": "EXCHANGE",
          "title": "FOR ALL MARKET PARTICIPANTS - PRIMARY MARKET AUCTION OF GOP IJARAH SUKUK (GIS)",
          "quarter": "",
          "date": "2025-07-17T12:22:31Z",
          "last_action": "2025-07-17T12:22:54Z",
          "is_revised": false,
          "pdf": "",
          "docs": [
              "256580-1.pdf"
          ],
          "images": null,
          "period_ended": null,
          "meeting": null,
          "results": null,
          "payouts": {
              "book_closure_from": "",
              "book_closure_to": "",
              "entitlement_date": "",
              "ex_date": "",
              "dividend": 0,
              "bonus": 0,
              "right_price": 0,
              "right_issue": 0,
              "split_num": 0,
              "split_den": 0,
              "rsplit_num": 0,
              "rsplit_den": 0,
              "sdiv_num": 0,
              "sdiv_den": 0
          }
      }
  ]
}

Response Fields

Data Array Fields

Field	Type	Description
id	string	Unique notice identifier
status	integer	Notice status
category	string	Notice category. See Notice Categories for possible values.
sector_code	string	Company sector classification code
form_type	string	Form type designation. See Form Types for possible values.
symbol	string	Stock symbol/ticker code
title	string	Notice title or announcement headline
quarter	string	Quarter designation if applicable
date	string	Notice publication date (ISO 8601 format)
last_action	string	Timestamp of last update/action (ISO 8601 format)
is_revised	boolean	Whether the notice has been revised
pdf	string	Primary PDF document filename
docs	array	Array of document filenames
images	array	Array of image filenames (if any)
period_ended	string	Period end date if applicable
meeting	object	Meeting details if applicable View
results	object	Financial results details if applicable View
payouts	object	Payout details including dividends and bonus View

Meeting Object Fields

Field	Type	Description
date	string	Meeting date (YYYY-MM-DD format)
time	string	Meeting time
location	string	Meeting location/venue
agenda	string	Meeting agenda details
accounts_ended	string	Accounts period end (Annual or Quarterly)
revised_date	string | null	Revised meeting date (if any)
revised_time	string | null	Revised meeting time (if any)

Results Object Fields

Field	Type	Description
eps	number	Earnings per share for the period
eps_sply	number	EPS for same period last year
sales	number	Sales/revenue amount
pat	number	Profit after tax amount

Payouts Object Fields

Field	Type	Description
book_closure_from	string	Book closure start date
book_closure_to	string	Book closure end date
entitlement_date	string	Entitlement date for dividend/bonus
ex_date	string	Ex-dividend/ex-bonus date
dividend	number	Dividend amount per share
bonus	number	Bonus ratio (bonus shares)
right_price	number	Rights issue price
right_issue	number	Rights issue ratio
split_num	number	Stock split numerator
split_den	number	Stock split denominator
rsplit_num	number	Reverse split numerator
rsplit_den	number	Reverse split denominator
sdiv_num	number	Specie dividend numerator
sdiv_den	number	Specie dividend denominator

Notice Categories

Code	Description
A	CDC Notices
B	SECP Notices
C	Company Notices
D	NCCPL Notices
E	Exchange Notices

Form Types

Code	Description
BMV1001	Board Meeting
MIV1025	Material Information
BMRV1001	Board Meeting Rescheduled
BMOTFRV1001	Board Meeting Other Than Financial Results
BMIPV1001	Board Meeting in Progress
FRV1007	Quarterly Financials
AGMV1002	Approval of Date and Time for Holding the Annual General Meeting
NAGMV1004	Notice for Annual General Meeting
AETAGMV1012	Approval of Extension in Time for Holding the Annual General Meeting / Annual Review Meeting for the Year
FRYEV1003	Annual Financials
DARYEV1005	Dispatch of Annual Report
MAGMV1006	Minutes of AGM
MAGMV10061	Minutes of EOGM
DQAV1008	Dispatch of Quarterly Report
DIDWV1009	Dispatch of Interim Dividend Warrants
DFDWV1010	Dispatch of Final Dividend Warrants
DBSCV1011	Dispatch of Bonus Certificate
CBSCV10111	Credit of Bonus Certificate
ETAGMV1012	Extension of Time for Holding AGM
DICBOCV1013	Declaration of Interim Payouts
DRSV1014	Declaration of Right Shares
DLRV1015	Dispatch of Letters of Rights
SRIV1016	Credit / Delivery of Shares - Right Issue
NEGMV1017	Notice of Extra Ordinary General Meeting
CCIV1018	Change of Company Information
NAPV1019	Appointment of Chairman / CEO / MD / Company Secretary
COPV1020	Change of Chairman / CEO / MD / Director / Company Secretary
COMV1021	Change of Management
SHOLDV001	List of Shareholders
LCERTV001	Loss of Certificates
FFSV001	Free Float of Shares
INTDISC001	Interest Disclosure in Shares of Company
MISV001	Miscellaneous Information
PSX_NOTICE	PSX Exchange Notice

Error Responses

For detailed Common Error responses, see the Error Handling.

Missing Parameters (200)

{
  "status": "error",
  "message": "no `date_from` and `date_to` provided"
}

Examples

Get Announcements in Date Range

curl -X GET "https://csapis.com/3.0/announcements/date-range?date_from=2024-01-01&date_to=2024-12-31" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Cases

• Period Analysis: Analyze announcements in specific periods
• Historical Review: Review corporate activity in a time period
• Timeline Construction: Build corporate action timelines
• Event History: Track announcement history
• Quarterly Analysis: Analyze announcements by quarter
• Annual Review: Review all announcements in a fiscal year