Response Schema

Overview

All CAS parsing endpoints return a unified JSON structure regardless of source (CDSL, NSDL, CAMS, KFintech).

Top-Level Structure

{
  "meta": { ... },
  "investor": { ... },
  "summary": { ... },
  "demat_accounts": [ ... ],
  "mutual_funds": [ ... ],
  "insurance": { ... },
  "nps": [ ... ]
}

Meta Object

Contains metadata about the CAS document and parsing operation.

{
  "meta": {
    "cas_type": "CDSL",
    "statement_period": {
      "from": "2024-01-01",
      "to": "2024-01-31"
    },
    "generated_at": "2024-02-01T10:30:00Z"
  }
}

Field	Type	Description
`cas_type`	string	`CDSL`, `NSDL`, or `CAMS_KFINTECH` (uppercase)
`statement_period`	object	Period covered by the statement
`statement_period.from`	string	Start date of statement (YYYY-MM-DD)
`statement_period.to`	string	End date of statement (YYYY-MM-DD)
`generated_at`	string	When the response was generated (ISO 8601)

Investor Object

Contains personal details of the investor extracted from the CAS.

{
  "investor": {
    "name": "John Doe",
    "pan": "ABCDE1234F",
    "email": "john@example.com",
    "address": "123 Main St, Mumbai 400001",
    "pincode": "400001",
    "mobile": "9876543210",
    "cas_id": "CAS123456"
  }
}

Field	Type	Description
`name`	string	Full name of investor
`pan`	string	PAN (Permanent Account Number)
`email`	string	Email address (may be null)
`address`	string	Full postal address (may be null)
`pincode`	string	Postal/ZIP code (may be null)
`mobile`	string	Mobile number (may be null)
`cas_id`	string	CAS ID (only for NSDL and CDSL, may be null)

Summary Object

Provides aggregated portfolio metrics and account counts.

{
  "summary": {
    "total_value": 2547832.50,
    "accounts": {
      "demat": {
        "count": 2,
        "total_value": 1500000.00
      },
      "mutual_funds": {
        "count": 5,
        "total_value": 950000.00
      },
      "insurance": {
        "count": 1,
        "total_value": 50000.00
      },
      "nps": {
        "count": 1,
        "total_value": 47832.50
      }
    }
  }
}

Field	Type	Description
`total_value`	number	Total portfolio value across all accounts
`accounts`	object	Breakdown by account type
`accounts.demat.count`	integer	Number of demat accounts
`accounts.demat.total_value`	number	Total value of demat holdings
`accounts.mutual_funds.count`	integer	Number of mutual fund folios
`accounts.mutual_funds.total_value`	number	Total value of MF holdings
`accounts.insurance.count`	integer	Number of insurance policies
`accounts.insurance.total_value`	number	Total value of insurance
`accounts.nps.count`	integer	Number of NPS accounts
`accounts.nps.total_value`	number	Total value of NPS holdings

Demat Accounts Array

Array of demat (dematerialized) accounts holding equities, bonds, ETFs, and other securities.

{
  "demat_accounts": [
    {
      "demat_type": "CDSL",
      "dp_id": "12345678",
      "dp_name": "HDFC Bank Limited",
      "client_id": "1234567890123456",
      "bo_id": "1234567890123456",
      "value": 1500000.00,
      "linked_holders": [
        {
          "name": "John Doe",
          "pan": "ABCDE1234F"
        }
      ],
      "holdings": {
        "equities": [ ... ],
        "corporate_bonds": [ ... ],
        "government_securities": [ ... ],
        "aifs": [ ... ],
        "demat_mutual_funds": [ ... ]
      },
      "additional_info": {
        "bo_status": "Active",
        "bo_type": "Individual",
        "bsda": "No",
        "email": "john@example.com",
        "status": "Active",
        "nominee": "Jane Doe"
      }
    }
  ]
}

Demat Account Fields

Field	Type	Description
`demat_type`	string	`NSDL` or `CDSL`
`dp_id`	string	Depository Participant ID
`dp_name`	string	DP name (e.g., “HDFC Bank”)
`client_id`	string	Client ID
`bo_id`	string	Beneficiary Owner ID (primarily for CDSL)
`value`	number	Total value of this demat account
`linked_holders`	array	Account holders linked to this account
`holdings`	object	Holdings grouped by asset class
`additional_info`	object	Account-specific metadata (varies by type)

Equity Object

Holdings in equities (stocks).

{
  "isin": "INE002A01018",
  "name": "Reliance Industries Ltd",
  "units": 100.0,
  "value": 250000.00,
  "transactions": [
    {
      "date": "2023-06-15",
      "type": "PURCHASE",
      "description": "Purchase",
      "units": 50.0,
      "nav": 2400.00,
      "amount": 120000.00,
      "balance": 100.0
    }
  ],
  "additional_info": {
    "open_units": 50.0,
    "close_units": 100.0
  }
}

Field	Type	Description
`isin`	string	ISIN code (12 characters)
`name`	string	Security name
`units`	number	Number of shares currently held
`value`	number	Current market value
`transactions`	array	Transaction history (beta feature)
`additional_info`	object	Opening/closing units for statement period

Corporate Bond Object

Holdings in corporate bonds.

{
  "isin": "INE123A01234",
  "name": "HDFC Ltd 8.5% Bond",
  "units": 10.0,
  "value": 10500.00,
  "transactions": [ ... ],
  "additional_info": {
    "open_units": 10.0,
    "close_units": 10.0
  }
}

Field	Type	Description
`isin`	string	ISIN code
`name`	string	Bond name/description
`units`	number	Number of units held
`value`	number	Current market value
`transactions`	array	Transaction history (beta feature)
`additional_info`	object	Opening/closing units for statement period

Mutual Funds Array

Array of mutual fund folios with schemes and transactions.

{
  "mutual_funds": [
    {
      "folio_number": "1234567890",
      "amc": "HDFC Mutual Fund",
      "registrar": "Computer Age Management Services",
      "value": 451000.88,
      "linked_holders": [
        {
          "name": "John Doe",
          "pan": "ABCDE1234F"
        }
      ],
      "schemes": [
        {
          "isin": "INF179K01234",
          "name": "HDFC Equity Fund - Growth",
          "type": "Equity",
          "units": 1000.50,
          "nav": 450.75,
          "value": 451000.88,
          "cost": 400000.00,
          "gain": {
            "absolute": 51000.88,
            "percentage": 12.75
          },
          "transactions": [ ... ],
          "nominees": ["Jane Doe"],
          "additional_info": {
            "advisor": "XYZ Advisors",
            "rta_code": "HDC001",
            "amfi": "100123",
            "open_units": 900.50,
            "close_units": 1000.50
          }
        }
      ],
      "additional_info": {
        "pan": "ABCDE1234F",
        "pankyc": "OK",
        "kyc": "OK"
      }
    }
  ]
}

Mutual Fund Folio Fields

Field	Type	Description
`folio_number`	string	Folio number
`amc`	string	Asset Management Company name
`registrar`	string	Registrar and Transfer Agent name
`value`	number	Total value of the folio
`linked_holders`	array	Account holders linked to this folio
`schemes`	array	List of schemes in this folio
`additional_info`	object	PAN, KYC status, etc.

Scheme Object

Field	Type	Description
`isin`	string	ISIN code
`name`	string	Scheme name
`type`	string	`Equity`, `Debt`, `Hybrid`, or `Other`
`units`	number	Units held
`nav`	number	Net Asset Value per unit
`value`	number	Current value (units × NAV)
`cost`	number	Cost of investment
`gain`	object	Gain/loss metrics
`gain.absolute`	number	Absolute gain or loss
`gain.percentage`	number	Percentage gain or loss
`transactions`	array	Transaction history
`nominees`	array	List of nominee names
`additional_info`	object	Advisor, RTA code, AMFI code, opening/closing units

Transaction Object

Unified transaction schema for all holdings (mutual funds, equities, bonds, etc.).

{
  "date": "2023-06-15",
  "description": "Purchase",
  "type": "PURCHASE",
  "amount": 10000.00,
  "units": 22.18,
  "nav": 450.86,
  "balance": 1000.50,
  "dividend_rate": null,
  "additional_info": {
    "stamp_duty": 5.00,
    "order_no": "ORD123456"
  }
}

Field	Type	Description
`date`	string	Transaction date (YYYY-MM-DD)
`description`	string	Transaction description/particulars
`type`	string	Transaction type (see below)
`amount`	number	Transaction amount in currency (may be null)
`units`	number	Number of units involved
`nav`	number	NAV/price per unit on transaction date (may be null)
`balance`	number	Balance units after transaction
`dividend_rate`	number	Dividend rate (for DIVIDEND_PAYOUT, may be null)
`additional_info`	object	Additional transaction-specific fields

Transaction Types: PURCHASE, PURCHASE_SIP, REDEMPTION, SWITCH_IN, SWITCH_IN_MERGER, SWITCH_OUT, SWITCH_OUT_MERGER, DIVIDEND_PAYOUT, DIVIDEND_REINVEST, SEGREGATION, STAMP_DUTY_TAX, TDS_TAX, STT_TAX, MISC, REVERSAL, UNKNOWN

Insurance Object

Contains insurance policies (currently only life insurance).

{
  "insurance": {
    "life_insurance_policies": [
      {
        "policy_number": "POL123456",
        "provider": "HDFC Life",
        "policy_name": "Click 2 Protect Life",
        "life_assured": "John Doe",
        "status": "Active",
        "sum_assured": 10000000,
        "premium_amount": 15000,
        "premium_frequency": "Annual",
        "additional_info": { }
      }
    ]
  }
}

Field	Type	Description
`policy_number`	string	Insurance policy number
`provider`	string	Insurance company name
`policy_name`	string	Name of the insurance policy
`life_assured`	string	Name of the life assured
`status`	string	Policy status (e.g., Active, Lapsed)
`sum_assured`	number	Sum assured amount
`premium_amount`	number	Premium amount
`premium_frequency`	string	Frequency (Annual, Monthly, etc.)
`additional_info`	object	Additional policy-specific information

NPS Array

National Pension System accounts (only available in NSDL CAS).

{
  "nps": [
    {
      "pran": "123456789012",
      "cra": "NSDL",
      "value": 228472.84,
      "funds": [
        {
          "name": "SBI Equity Fund",
          "units": 5000.50,
          "nav": 45.67,
          "value": 228472.84,
          "cost": 200000.00,
          "additional_info": {
            "tier": 1,
            "manager": "SBI Pension Funds"
          }
        }
      ],
      "linked_holders": [
        {
          "name": "John Doe",
          "pan": "ABCDE1234F"
        }
      ],
      "additional_info": { }
    }
  ]
}

Field	Type	Description
`pran`	string	Permanent Retirement Account Number
`cra`	string	Central Record Keeping Agency name
`value`	number	Total value of the NPS account
`funds`	array	List of NPS funds
`linked_holders`	array	Account holders linked to this NPS account
`additional_info`	object	Additional NPS account metadata

NPS Fund Object

Field	Type	Description
`name`	string	Name of the NPS fund
`units`	number	Number of units held
`nav`	number	Net Asset Value per unit
`value`	number	Current market value
`cost`	number	Cost of investment
`additional_info.tier`	number	NPS tier (1, 2, or null)
`additional_info.manager`	string	Fund manager name

Error Response

When parsing fails, the API returns a failed status with a descriptive error message.

{
  "status": "failed",
  "msg": "Invalid password for PDF"
}

Field	Type	Description
`status`	string	Always `failed` for errors (or `error` for system errors)
`msg`	string	Human-readable error message

Note: All responses include an X-Request-ID header (format: req_<alphanumeric>) for debugging and support.

Common Error Messages

Message	Cause	Solution
`Invalid password for PDF`	Wrong PDF password	Verify password format (often PAN-based)
`Invalid PDF file`	Corrupted or scanned PDF	Use original digitally-generated PDF
`Unsupported CAS type`	Wrong endpoint for CAS type	Use `/v4/smart/parse` to auto-detect
`API quota exceeded`	Credit limit reached	Upgrade plan or wait for reset
`Authentication failed`	Missing/invalid API key	Check `x-api-key` header

Getting Started

Quickstart

Learn

Resources

Overview

Top-Level Structure

Meta Object

Investor Object

Summary Object

Demat Accounts Array

Demat Account Fields

Equity Object

Corporate Bond Object

Mutual Funds Array

Mutual Fund Folio Fields

Scheme Object

Transaction Object

Insurance Object

NPS Array

NPS Fund Object

Error Response

Common Error Messages

Next Steps

Quickstart

Error Handling

Getting Started

Quickstart

Learn

Resources

​Overview

​Top-Level Structure

​Meta Object

​Investor Object

​Summary Object

​Demat Accounts Array

​Demat Account Fields

​Equity Object

​Corporate Bond Object

​Mutual Funds Array

​Mutual Fund Folio Fields

​Scheme Object

​Transaction Object

​Insurance Object

​NPS Array

​NPS Fund Object

​Error Response

​Common Error Messages

​Next Steps

Quickstart

Error Handling

Overview

Top-Level Structure

Meta Object

Investor Object

Summary Object

Demat Accounts Array

Demat Account Fields

Equity Object

Corporate Bond Object

Mutual Funds Array

Mutual Fund Folio Fields

Scheme Object

Transaction Object

Insurance Object

NPS Array

NPS Fund Object

Error Response

Common Error Messages

Next Steps