Corporate Actions API

Overview

The Corporate Actions API retrieves comprehensive corporate action data including dividends, bonuses, stock splits, rights issues, buybacks, and quarterly result announcements. The endpoint supports both historical (2 years back) and upcoming (2 months forward) data with date-based filtering. Source File: fetch_corporate_actions.py

Endpoint Details

URL

string

required

https://ow-scanx-analytics.dhan.co/customscan/fetchdt

Method

string

required

POST

Content-Type

string

required

application/json

Request Headers

{
  "Content-Type": "application/json",
  "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
  "Accept": "application/json, text/plain, */*",
  "Origin": "https://scanx.dhan.co",
  "Referer": "https://scanx.dhan.co/"
}

Request Payload

data.sort

string

default:"CorpAct.ExDate"

Field to sort by (typically ExDate for chronological order)

data.sorder

string

default:"asc"

Sort order - “asc” or “desc”

data.count

integer

default:"5000"

Number of results to return. Use 5000 to fetch all in one request.

data.fields

array

required

Fields to retrieve. Common fields: CorpAct.ActType, Sym, DispSym, CorpAct.ExDate, CorpAct.RecDate, CorpAct.Note

data.params

array

required

Filter parameters including segment, instrument type, date range, market cap, and action types

data.pgno

integer

default:"0"

Page number (0-indexed)

Example Payload (Historical)

{
  "data": {
    "sort": "CorpAct.ExDate",
    "sorder": "asc",
    "count": 5000,
    "fields": [
      "CorpAct.ActType",
      "Sym",
      "DispSym",
      "CorpAct.ExDate",
      "CorpAct.RecDate",
      "CorpAct.Note"
    ],
    "params": [
      {"field": "Seg", "op": "", "val": "E"},
      {"field": "OgInst", "op": "", "val": "ES"},
      {"field": "CorpAct.ExDate", "op": "lte", "val": "2024-01-14"},
      {"field": "CorpAct.ExDate", "op": "gte", "val": "2022-01-14"},
      {"field": "Mcapclass", "op": "", "val": "Largecap,Midcap,Smallcap,Microcap"},
      {"field": "CorpAct.ActType", "op": "", "val": "BONUS,DIVIDEND,QUARTERLY RESULT ANNOUNCEMENT,SPLIT,RIGHTS,BUYBACK"}
    ],
    "pgno": 0
  }
}

Example Payload (Upcoming)

{
  "data": {
    "sort": "CorpAct.ExDate",
    "sorder": "asc",
    "count": 5000,
    "fields": [
      "CorpAct.ActType",
      "Sym",
      "DispSym",
      "CorpAct.ExDate",
      "CorpAct.RecDate",
      "CorpAct.Note"
    ],
    "params": [
      {"field": "Seg", "op": "", "val": "E"},
      {"field": "OgInst", "op": "", "val": "ES"},
      {"field": "CorpAct.ExDate", "op": "gte", "val": "2024-01-15"},
      {"field": "CorpAct.ExDate", "op": "lte", "val": "2024-03-15"},
      {"field": "Mcapclass", "op": "", "val": "Largecap,Midcap,Smallcap,Microcap"},
      {"field": "CorpAct.ActType", "op": "", "val": "BONUS,DIVIDEND,QUARTERLY RESULT ANNOUNCEMENT,SPLIT,RIGHTS,BUYBACK"}
    ],
    "pgno": 0
  }
}

Example Request

curl -X POST https://ow-scanx-analytics.dhan.co/customscan/fetchdt \
  -H "Content-Type: application/json" \
  -H "Origin: https://scanx.dhan.co" \
  -H "Referer: https://scanx.dhan.co/" \
  -d '{
    "data": {
      "sort": "CorpAct.ExDate",
      "sorder": "asc",
      "count": 5000,
      "fields": ["CorpAct.ActType", "Sym", "DispSym", "CorpAct.ExDate", "CorpAct.RecDate", "CorpAct.Note"],
      "params": [
        {"field": "Seg", "op": "", "val": "E"},
        {"field": "CorpAct.ExDate", "op": "gte", "val": "2024-01-15"},
        {"field": "CorpAct.ExDate", "op": "lte", "val": "2024-03-15"},
        {"field": "CorpAct.ActType", "op": "", "val": "BONUS,DIVIDEND,SPLIT"}
      ],
      "pgno": 0
    }
  }'

Response Structure

data

array

Array of stock objects containing corporate action arrays

Stock Object Fields

Sym

string

Trading symbol

DispSym

string

Display name

CorpAct

array

Array of corporate action objects

Corporate Action Object Fields

ActType

string

Action type (BONUS, DIVIDEND, SPLIT, RIGHTS, BUYBACK, QUARTERLY RESULT ANNOUNCEMENT)

ExDate

string

Ex-date in YYYY-MM-DD format

RecDate

string

Record date in YYYY-MM-DD format

Note

string

Action details (e.g., “Rs 10 per share”, “1:1 bonus”)

Example Response

{
  "data": [
    {
      "Sym": "RELIANCE",
      "DispSym": "Reliance Industries Ltd.",
      "CorpAct": [
        {
          "ActType": "DIVIDEND",
          "ExDate": "2024-02-15",
          "RecDate": "2024-02-16",
          "Note": "Rs 8 per share"
        },
        {
          "ActType": "QUARTERLY RESULT ANNOUNCEMENT",
          "ExDate": "2024-01-18",
          "RecDate": "2024-01-18",
          "Note": "Q3 FY24"
        }
      ]
    }
  ]
}

Implementation Details

Configuration

Historical Range

string

2 years back from today

Upcoming Range

string

Today + 2 months forward

Page Size

integer

default:"5000"

Results per request (sufficient for all corporate actions)

Output Files

array

history_corporate_actions.json
upcoming_corporate_actions.json

Processing Flow

Calculate Dates: Compute date ranges in IST timezone
Fetch Historical: Request actions from 2 years ago to yesterday
Fetch Upcoming: Request actions from today to 2 months forward
Flatten Data: Extract CorpAct arrays from nested structure
Filter by Date: Strict filtering to ensure date range compliance
Sort: Order by ExDate ascending
Save: Write to separate history and upcoming files

Code Implementation

import requests
import json
from datetime import datetime, timedelta

url = "https://ow-scanx-analytics.dhan.co/customscan/fetchdt"

# Calculate dates in IST
utc_now = datetime.utcnow()
ist_now = utc_now + timedelta(hours=5, minutes=30)
today_str = ist_now.strftime("%Y-%m-%d")
two_years_ago = (ist_now - timedelta(days=365 * 2)).strftime("%Y-%m-%d")
two_months_forward = (ist_now + timedelta(days=60)).strftime("%Y-%m-%d")
yesterday = (ist_now - timedelta(days=1)).strftime("%Y-%m-%d")

common_fields = [
    "CorpAct.ActType", "Sym", "DispSym", 
    "CorpAct.ExDate", "CorpAct.RecDate", "CorpAct.Note"
]

def get_data(start_date, end_date):
    payload = {
        "data": {
            "sort": "CorpAct.ExDate",
            "sorder": "asc",
            "count": 5000,
            "fields": common_fields,
            "params": [
                {"field": "Seg", "op": "", "val": "E"},
                {"field": "OgInst", "op": "", "val": "ES"},
                {"field": "CorpAct.ExDate", "op": "lte", "val": end_date},
                {"field": "CorpAct.ExDate", "op": "gte", "val": start_date},
                {"field": "Mcapclass", "op": "", "val": "Largecap,Midcap,Smallcap,Microcap"},
                {"field": "CorpAct.ActType", "op": "", "val": "BONUS,DIVIDEND,QUARTERLY RESULT ANNOUNCEMENT,SPLIT,RIGHTS,BUYBACK"}
            ],
            "pgno": 0
        }
    }
    
    response = requests.post(url, json=payload, headers=headers)
    raw_data = response.json().get('data', [])
    
    # Flatten nested CorpAct arrays
    flattened = []
    for stock in raw_data:
        symbol = stock.get('Sym')
        name = stock.get('DispSym')
        actions = stock.get('CorpAct', [])
        
        for action in actions:
            ex_date = action.get('ExDate')
            # Strict filtering by date range
            if start_date <= ex_date <= end_date:
                flattened.append({
                    "Symbol": symbol,
                    "Name": name,
                    "Type": action.get('ActType'),
                    "ExDate": ex_date,
                    "RecordDate": action.get('RecDate'),
                    "Details": action.get('Note')
                })
    
    # Sort by ExDate
    return sorted(flattened, key=lambda x: x['ExDate'])

# Fetch historical (2 years back to yesterday)
history = get_data(two_years_ago, yesterday)
with open("history_corporate_actions.json", "w") as f:
    json.dump(history, f, indent=4)

# Fetch upcoming (today to 2 months forward)
upcoming = get_data(today_str, two_months_forward)
with open("upcoming_corporate_actions.json", "w") as f:
    json.dump(upcoming, f, indent=4)

Output File Structure

history_corporate_actions.json

[
  {
    "Symbol": "RELIANCE",
    "Name": "Reliance Industries Ltd.",
    "Type": "DIVIDEND",
    "ExDate": "2022-02-10",
    "RecordDate": "2022-02-11",
    "Details": "Rs 7 per share"
  },
  {
    "Symbol": "TCS",
    "Name": "Tata Consultancy Services Ltd.",
    "Type": "BONUS",
    "ExDate": "2022-06-15",
    "RecordDate": "2022-06-16",
    "Details": "1:1"
  }
]

upcoming_corporate_actions.json

[
  {
    "Symbol": "HDFCBANK",
    "Name": "HDFC Bank Ltd.",
    "Type": "DIVIDEND",
    "ExDate": "2024-03-10",
    "RecordDate": "2024-03-11",
    "Details": "Rs 19 per share"
  }
]

Corporate Action Types

BONUS

string

Bonus share issuance (e.g., “1:1”, “1:2”)

DIVIDEND

string

Dividend payment (e.g., “Rs 10 per share”)

SPLIT

string

Stock split (e.g., “1:10 split”)

RIGHTS

string

Rights issue announcement

BUYBACK

string

Share buyback program

QUARTERLY RESULT ANNOUNCEMENT

string

Earnings announcement date

Date Filtering Parameters

Operators

"gte": Greater than or equal to (start date)
"lte": Less than or equal to (end date)
"eq": Equal to (exact date)
"gt": Greater than
"lt": Less than

Example Date Filters

// Last 30 days
{"field": "CorpAct.ExDate", "op": "gte", "val": "2024-01-01"}
{"field": "CorpAct.ExDate", "op": "lte", "val": "2024-01-30"}

// Specific date
{"field": "CorpAct.ExDate", "op": "eq", "val": "2024-02-15"}

Use Cases

Dividend Tracking: Monitor dividend ex-dates for portfolio stocks
Calendar Events: Build corporate action calendar
Bonus/Split Analysis: Track stock split and bonus announcements
Earnings Calendar: Identify quarterly result dates
Ex-Date Strategies: Plan trades around ex-dates
Historical Analysis: Analyze past corporate action patterns

Performance Metrics

Historical Actions: 5,000-10,000 actions (2 years)
Upcoming Actions: 500-1,500 actions (2 months)
Request Time: 2-5 seconds per scenario
Total Time: ~10 seconds for both files
Success Rate: >99%

Filtering Examples

Dividends Only

# Filter for dividend announcements
dividends = [
    action for action in history
    if action["Type"] == "DIVIDEND"
]

High Value Dividends

import re

# Extract dividend amount and filter
high_dividends = []
for action in history:
    if action["Type"] == "DIVIDEND":
        match = re.search(r'Rs (\d+\.?\d*)', action["Details"])
        if match and float(match.group(1)) >= 10:
            high_dividends.append(action)

Upcoming Week

from datetime import datetime, timedelta

today = datetime.now()
next_week = today + timedelta(days=7)

week_actions = [
    action for action in upcoming
    if today <= datetime.strptime(action["ExDate"], "%Y-%m-%d") <= next_week
]

Important Dates

ExDate

string

Ex-dividend/ex-bonus date - stock trades without the benefit

RecordDate

string

Record date - shareholders must be on record to receive benefit

Rule: To receive corporate action benefit, buy before ex-date.

Notes

Dates are in IST (Indian Standard Time, UTC+5:30)
Historical range: 2 years back from today
Upcoming range: Today + 2 months forward
The API returns nested structures; implementation flattens for usability
Strict date filtering prevents duplicates across scenarios
Market cap filter includes all classes (Large/Mid/Small/Micro)
Results are sorted by ExDate ascending (chronological order)
Some actions may have null RecordDate (use ExDate as fallback)
Details field format varies by action type
Run daily to keep upcoming actions current

Endpoints

Output Fields

Overview

Endpoint Details

Request Headers

Request Payload

Example Payload (Historical)

Example Payload (Upcoming)

Example Request

Response Structure

Stock Object Fields

Corporate Action Object Fields

Example Response

Implementation Details

Configuration

Processing Flow

Code Implementation

Output File Structure

history_corporate_actions.json

upcoming_corporate_actions.json

Corporate Action Types

Date Filtering Parameters

Operators

Example Date Filters

Use Cases

Performance Metrics

Filtering Examples

Dividends Only

High Value Dividends

Upcoming Week

Important Dates

Notes

Build docs developers (and LLMs) love

Endpoints

Output Fields

​Overview

​Endpoint Details

​Request Headers

​Request Payload

​Example Payload (Historical)

​Example Payload (Upcoming)

​Example Request

​Response Structure

​Stock Object Fields

​Corporate Action Object Fields

​Example Response

​Implementation Details

​Configuration

​Processing Flow

​Code Implementation

​Output File Structure

​history_corporate_actions.json

​upcoming_corporate_actions.json

​Corporate Action Types

​Date Filtering Parameters

​Operators

​Example Date Filters

​Use Cases

​Performance Metrics

​Filtering Examples

​Dividends Only

​High Value Dividends

​Upcoming Week

​Important Dates

​Notes

Build docs developers (and LLMs) love

Overview

Endpoint Details

Request Headers

Request Payload

Example Payload (Historical)

Example Payload (Upcoming)

Example Request

Response Structure

Stock Object Fields

Corporate Action Object Fields

Example Response

Implementation Details

Configuration

Processing Flow

Code Implementation

Output File Structure

history_corporate_actions.json

upcoming_corporate_actions.json

Corporate Action Types

Date Filtering Parameters

Operators

Example Date Filters

Use Cases

Performance Metrics

Filtering Examples

Dividends Only

High Value Dividends

Upcoming Week

Important Dates

Notes