All Payouts by Date Range
Retrieve payout information for all stocks within a specified date range.
GET/3.0/payouts/date-range
Description
This endpoint returns comprehensive payout records (dividends, splits, bonus, rights) for all companies within a specified date range. It's useful for analyzing payout activity in a specific period and identifying all corporate actions that occurred during that timeframe.
Request
Authentication
- Type: Bearer Token
- Required: Yes
Parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
date_from | string | Yes | Start date for payout records (YYYY-MM-DD) | 2024-01-01 |
date_to | string | Yes | End date for payout records (YYYY-MM-DD) | 2024-12-31 |
Response
Success Response (200)
{
"status": "ok",
"message": "",
"data": [
{
"id": "246953",
"title": "Financial results for Year ended December 31, 2024",
"form_type": "FRYEV1003",
"quarter": "YEAR",
"period_ended": "2024-12-31",
"date": "2025-02-06T08:29:53Z",
"pdf": "",
"docs": [
"246953.pdf"
],
"images": [
"246953-1.gif"
],
"payouts": {
"book_closure_from": "2025-03-18",
"book_closure_to": "2025-03-27",
"entitlement_date": "2025-03-17",
"ex_date": "2025-03-14",
"dividend": 9,
"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
}
},
{
"id": "246953",
"title": "Financial results for Year ended December 31, 2024",
"form_type": "FRYEV1003",
"quarter": "YEAR",
"period_ended": "2024-12-31",
"date": "2025-03-03T04:10:01Z",
"pdf": "",
"docs": [
"248951.pdf"
],
"images": [
"248951-1.gif"
],
"payouts": {
"book_closure_from": "2025-03-18",
"book_closure_to": "2025-03-25",
"entitlement_date": "2025-03-17",
"ex_date": "2025-03-14",
"dividend": 8,
"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 | Payout announcement ID |
title | string | Payout announcement title |
form_type | string | Form type designation |
quarter | string | Quarter designation if applicable |
period_ended | string | Period end date if applicable |
date | string | Announcement publication date (ISO 8601 format) |
pdf | string | Primary PDF document filename |
docs | array | Array of document filenames |
images | array | Array of image filenames (if any) |
payouts | object | Payout details including dividends and bonus View |
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 |
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 Payouts for a Specific Period
curl -X GET "https://csapis.com/3.0/payouts/date-range?date_from=2024-01-01&date_to=2024-12-31" \
-H "Authorization: Bearer YOUR_API_TOKEN"
Use Cases
- Period Analysis: Analyze all payouts in a specific time period
- Corporate Action Calendar: Build a corporate action calendar for a period
- Payout History: Track all payout events chronologically
- Market Activity: Monitor overall market payout activity
- Dividend Season Analysis: Analyze dividend patterns during specific seasons
- Event-Based Strategies: Identify and analyze payout-related trading opportunities