{"components":{"headers":{"X-Request-ID":{"description":"Unique request identifier for tracking and support.\nFormat: `req_<alphanumeric>` (e.g., `req_2xYz7KpL8mN3Ab`)\n\nUse this ID when:\n- Contacting support about a specific request\n- Correlating API calls with usage logs\n- Debugging issues in your application\n\nYou can also provide your own `X-Request-ID` header in the request\n(must start with `req_`) to use your own tracking ID.\n","schema":{"example":"req_2xYz7KpL8mN3Ab","pattern":"^req_[A-Za-z0-9]+$","type":"string"}}},"requestBodies":{"CASParseRequest":{"content":{"application/json":{"schema":{"description":"Provide either `pdf_file` OR `pdf_url` (one is required)","properties":{"password":{"description":"Password for the PDF file (if required)","type":"string"},"pdf_file":{"description":"Base64 encoded CAS PDF file (required if pdf_url not provided)","format":"base64","type":"string"},"pdf_url":{"description":"URL to the CAS PDF file (required if pdf_file not provided)","format":"uri","type":"string"}},"type":"object"}},"multipart/form-data":{"schema":{"description":"Provide either `pdf_file` OR `pdf_url` (one is required)","properties":{"password":{"description":"Password for the PDF file (if required)","type":"string"},"pdf_file":{"description":"CAS PDF file to parse (required if pdf_url not provided)","format":"binary","type":"string"},"pdf_url":{"description":"URL to the CAS PDF file (required if pdf_file not provided)","format":"uri","type":"string"}},"type":"object"}}},"required":true},"ContractNoteParseRequest":{"content":{"application/json":{"schema":{"oneOf":[{"required":["pdf_file","password"]},{"required":["pdf_url","password"]}],"properties":{"broker_type":{"description":"Optional broker type override. If not provided, system will auto-detect.","enum":["zerodha","groww","upstox","icici"],"example":"zerodha","type":"string"},"password":{"description":"Password for the PDF file (usually PAN number for Zerodha)","example":"FAXAK2545F","type":"string"},"pdf_file":{"description":"Base64 encoded contract note PDF file","example":"JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo...","format":"base64","type":"string"},"pdf_url":{"description":"URL to the contract note PDF file","example":"https://example.com/contract_note.pdf","format":"uri","type":"string"}},"type":"object"}},"multipart/form-data":{"schema":{"properties":{"broker_type":{"description":"Optional broker type override","enum":["zerodha","groww","upstox","icici"],"type":"string"},"password":{"description":"Password for the PDF file (usually PAN number)","type":"string"},"pdf_file":{"description":"Contract note PDF file to parse","format":"binary","type":"string"}},"required":["pdf_file","password"],"type":"object"}}},"required":true}},"responses":{"Forbidden":{"content":{"application/json":{"example":{"msg":"Authentication failed: API quota exceeded or invalid API key. Please check your API key or quota limits.","status":"error"},"schema":{"$ref":"#/components/schemas/AuthErrorResponse"}}},"description":"Forbidden. This can happen if the API key is invalid or the quota has been exceeded."},"InternalError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"},"ParseBadRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request (Invalid PDF file, missing parameters, or invalid password)"},"ParseSuccess":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnifiedResponse"}}},"description":"Successful operation"},"Unauthorized":{"content":{"application/json":{"example":{"msg":"Authentication failed: API key is missing. Please provide a valid API key in the x-api-key header.","status":"error"},"schema":{"$ref":"#/components/schemas/AuthErrorResponse"}}},"description":"Unauthorized. This can happen if the `x-api-key` header is missing."}},"schemas":{"AIF":{"properties":{"additional_info":{"description":"Additional information specific to the AIF","properties":{"close_units":{"description":"Closing balance units for the statement period (beta)","format":"float","type":["number","null"]},"open_units":{"description":"Opening balance units for the statement period (beta)","format":"float","type":["number","null"]}},"type":"object"},"isin":{"description":"ISIN code of the AIF","type":"string"},"name":{"description":"Name of the AIF","type":"string"},"transactions":{"description":"List of transactions for this holding (beta)","items":{"$ref":"#/components/schemas/Transaction"},"type":"array"},"units":{"description":"Number of units held","format":"float","type":"number"},"value":{"description":"Current market value of the holding","format":"float","type":"number"}},"type":"object"},"AuthErrorResponse":{"properties":{"msg":{"description":"A descriptive message explaining the error.","example":"Authentication failed: API key is missing.","type":"string"},"status":{"description":"The status of the error.","example":"error","type":"string"}},"required":["status","msg"],"type":"object"},"ContractNoteResponse":{"properties":{"broker_info":{"properties":{"broker_type":{"description":"Auto-detected or specified broker type","enum":["zerodha","groww","upstox","icici","unknown"],"example":"zerodha","type":"string"},"name":{"description":"Broker company name","example":"Zerodha Broking Limited","type":"string"},"sebi_registration":{"description":"SEBI registration number of the broker","example":"INZ000031633","type":"string"}},"type":"object"},"charges_summary":{"description":"Breakdown of various charges and fees","properties":{"cgst":{"description":"Central GST amount","format":"float","type":"number"},"exchange_transaction_charges":{"description":"Exchange transaction charges","format":"float","type":"number"},"igst":{"description":"Integrated GST amount","format":"float","type":"number"},"net_amount_receivable_payable":{"description":"Final net amount receivable or payable","format":"float","type":"number"},"pay_in_pay_out_obligation":{"description":"Net pay-in/pay-out obligation","format":"float","type":"number"},"sebi_turnover_fees":{"description":"SEBI turnover fees","format":"float","type":"number"},"securities_transaction_tax":{"description":"Securities Transaction Tax","format":"float","type":"number"},"sgst":{"description":"State GST amount","format":"float","type":"number"},"stamp_duty":{"description":"Stamp duty charges","format":"float","type":"number"},"taxable_value_brokerage":{"description":"Taxable brokerage amount","format":"float","type":"number"}},"type":"object"},"client_info":{"properties":{"address":{"description":"Client address","type":"string"},"gst_state_code":{"description":"GST state code","example":"7","type":"string"},"name":{"description":"Client name","example":"VIRENDER KUMAR","type":"string"},"pan":{"description":"Client PAN number","example":"FAXAK2545F","type":"string"},"place_of_supply":{"description":"GST place of supply","example":"DELHI","type":"string"},"ucc":{"description":"Unique Client Code","example":"YS3654","type":"string"}},"type":"object"},"contract_note_info":{"properties":{"contract_note_number":{"description":"Contract note reference number","example":"CNT-25/26-73436720","type":"string"},"settlement_date":{"description":"Settlement date for the trades","example":"2025-08-06","format":"date","type":"string"},"settlement_number":{"description":"Settlement reference number","example":"2025149","type":"string"},"trade_date":{"description":"Date when trades were executed","example":"2025-08-05","format":"date","type":"string"}},"type":"object"},"derivatives_transactions":{"description":"Summary of derivatives transactions","items":{"properties":{"brokerage_per_unit":{"description":"Brokerage charged per unit","format":"float","type":"number"},"buy_sell_bf_cf":{"description":"Transaction type (Buy/Sell/Bring Forward/Carry Forward)","example":"B","type":"string"},"closing_rate_per_unit":{"description":"Closing rate per unit","format":"float","type":"number"},"contract_description":{"description":"Derivatives contract description","example":"NIFTY24802410DPE","type":"string"},"net_total":{"description":"Net total amount","format":"float","type":"number"},"quantity":{"description":"Quantity traded","format":"float","type":"number"},"wap_per_unit":{"description":"Weighted Average Price per unit","format":"float","type":"number"}},"type":"object"},"type":"array"},"detailed_trades":{"description":"Detailed breakdown of all individual trades","items":{"properties":{"brokerage":{"description":"Brokerage charged for this trade","format":"float","type":"number"},"buy_sell":{"description":"Transaction type (B for Buy, S for Sell)","example":"B","type":"string"},"closing_rate_per_unit":{"description":"Closing rate per unit","format":"float","type":"number"},"exchange":{"description":"Exchange name","example":"NSE","type":"string"},"net_rate_per_unit":{"description":"Net rate per unit","format":"float","type":"number"},"net_total":{"description":"Net total for this trade","format":"float","type":"number"},"order_number":{"description":"Order reference number","example":"1000000042939390","type":"string"},"order_time":{"description":"Time when order was placed","example":"13:13:13","type":"string"},"quantity":{"description":"Quantity traded","format":"float","type":"number"},"remarks":{"description":"Additional remarks or notes","type":"string"},"security_description":{"description":"Security name with exchange and ISIN","example":"CASTROLIND-EQ/INE172A01027","type":"string"},"trade_number":{"description":"Trade reference number","example":"4006567","type":"string"},"trade_time":{"description":"Time when trade was executed","example":"13:13:13","type":"string"}},"type":"object"},"type":"array"},"equity_transactions":{"description":"Summary of equity transactions grouped by security","items":{"properties":{"buy_quantity":{"description":"Total quantity purchased","format":"float","type":"number"},"buy_total_value":{"description":"Total value of buy transactions","format":"float","type":"number"},"buy_wap":{"description":"Weighted Average Price for buy transactions","format":"float","type":"number"},"isin":{"description":"ISIN code of the security","example":"INE172A01027","type":"string"},"net_obligation":{"description":"Net amount payable/receivable for this security","format":"float","type":"number"},"security_name":{"description":"Name of the security","example":"CASTROLIND","type":"string"},"security_symbol":{"description":"Trading symbol","example":"CASTROLIND","type":"string"},"sell_quantity":{"description":"Total quantity sold","format":"float","type":"number"},"sell_total_value":{"description":"Total value of sell transactions","format":"float","type":"number"},"sell_wap":{"description":"Weighted Average Price for sell transactions","format":"float","type":"number"}},"type":"object"},"type":"array"}},"type":"object"},"CorporateBond":{"properties":{"additional_info":{"description":"Additional information specific to the corporate bond","properties":{"close_units":{"description":"Closing balance units for the statement period (beta)","format":"float","type":["number","null"]},"open_units":{"description":"Opening balance units for the statement period (beta)","format":"float","type":["number","null"]}},"type":"object"},"isin":{"description":"ISIN code of the corporate bond","type":"string"},"name":{"description":"Name of the corporate bond","type":"string"},"transactions":{"description":"List of transactions for this holding (beta)","items":{"$ref":"#/components/schemas/Transaction"},"type":"array"},"units":{"description":"Number of units held","format":"float","type":"number"},"value":{"description":"Current market value of the holding","format":"float","type":"number"}},"type":"object"},"DematAccount":{"properties":{"additional_info":{"description":"Additional information specific to the demat account type","properties":{"bo_status":{"description":"Beneficiary Owner status (CDSL)","type":"string"},"bo_sub_status":{"description":"Beneficiary Owner sub-status (CDSL)","type":"string"},"bo_type":{"description":"Beneficiary Owner type (CDSL)","type":"string"},"bsda":{"description":"Basic Services Demat Account status (CDSL)","type":"string"},"email":{"description":"Email associated with the demat account (CDSL)","format":"email","type":"string"},"linked_pans":{"description":"List of linked PAN numbers (NSDL)","items":{"type":"string"},"type":"array"},"nominee":{"description":"Nominee details (CDSL)","type":"string"},"status":{"description":"Account status (CDSL)","type":"string"}},"type":"object"},"bo_id":{"description":"Beneficiary Owner ID (primarily for CDSL)","type":"string"},"client_id":{"description":"Client ID","type":"string"},"demat_type":{"description":"Type of demat account","enum":["NSDL","CDSL"],"type":"string"},"dp_id":{"description":"Depository Participant ID","type":"string"},"dp_name":{"description":"Depository Participant name","type":"string"},"holdings":{"properties":{"aifs":{"items":{"$ref":"#/components/schemas/AIF"},"type":"array"},"corporate_bonds":{"items":{"$ref":"#/components/schemas/CorporateBond"},"type":"array"},"demat_mutual_funds":{"items":{"$ref":"#/components/schemas/DematMutualFund"},"type":"array"},"equities":{"items":{"$ref":"#/components/schemas/Equity"},"type":"array"},"government_securities":{"items":{"$ref":"#/components/schemas/GovernmentSecurity"},"type":"array"}},"type":"object"},"linked_holders":{"description":"List of account holders linked to this demat account","items":{"$ref":"#/components/schemas/LinkedHolder"},"type":"array"},"value":{"description":"Total value of the demat account","format":"float","type":"number"}},"type":"object"},"DematMutualFund":{"properties":{"additional_info":{"description":"Additional information specific to the mutual fund","properties":{"close_units":{"description":"Closing balance units for the statement period (beta)","format":"float","type":["number","null"]},"open_units":{"description":"Opening balance units for the statement period (beta)","format":"float","type":["number","null"]}},"type":"object"},"isin":{"description":"ISIN code of the mutual fund","type":"string"},"name":{"description":"Name of the mutual fund","type":"string"},"transactions":{"description":"List of transactions for this holding (beta)","items":{"$ref":"#/components/schemas/Transaction"},"type":"array"},"units":{"description":"Number of units held","format":"float","type":"number"},"value":{"description":"Current market value of the holding","format":"float","type":"number"}},"type":"object"},"EmailCASFile":{"description":"A CAS file found in the user's email inbox","properties":{"cas_type":{"description":"Detected CAS provider based on sender email","enum":["cdsl","nsdl","cams","kfintech"],"example":"cdsl","type":"string"},"expires_in":{"description":"URL expiration time in seconds. Defaults vary by source:\n- Gmail Inbox Import: 86400 (24h)\n- Inbound Email with `callback_url` set: 172800 (48h)\n- Inbound Email without `callback_url`: aligned with the session TTL (~30 min)\n","example":86400,"type":"integer"},"filename":{"description":"Standardized filename (provider_YYYYMMDD_uniqueid.pdf)","example":"cdsl_20250115_a1b2c3d4.pdf","type":"string"},"message_date":{"description":"Date the email was received","example":"2025-01-15","format":"date","type":"string"},"message_id":{"description":"Unique identifier for the email message (use for subsequent API calls)","example":"18d4a2b3c4d5e6f7","type":"string"},"original_filename":{"description":"Original attachment filename from the email","example":"CDSL_CAS_Statement.pdf","type":"string"},"sender_email":{"description":"Email address of the CAS authority (CDSL, NSDL, CAMS, or KFintech) who originally sent this statement","example":"eCAS@cdslstatement.com","format":"email","type":"string"},"size":{"description":"File size in bytes","example":245000,"type":"integer"},"url":{"description":"Direct download URL (presigned, expires based on expires_in)","example":"https://cdn.casparser.in/email-cas/user123/cdsl_20250115_a1b2c3d4.pdf","format":"uri","type":"string"}},"type":"object"},"Equity":{"properties":{"additional_info":{"description":"Additional information specific to the equity","properties":{"close_units":{"description":"Closing balance units for the statement period (beta)","format":"float","type":["number","null"]},"open_units":{"description":"Opening balance units for the statement period (beta)","format":"float","type":["number","null"]}},"type":"object"},"isin":{"description":"ISIN code of the equity","type":"string"},"name":{"description":"Name of the equity","type":"string"},"transactions":{"description":"List of transactions for this holding (beta)","items":{"$ref":"#/components/schemas/Transaction"},"type":"array"},"units":{"description":"Number of units held","format":"float","type":"number"},"value":{"description":"Current market value of the holding","format":"float","type":"number"}},"type":"object"},"ErrorResponse":{"properties":{"msg":{"description":"A descriptive message explaining the error.","example":"Invalid PDF file or password.","type":"string"},"status":{"description":"The status of the error.","enum":["failed"],"example":"failed","type":"string"}},"required":["status","msg"],"type":"object"},"GovernmentSecurity":{"properties":{"additional_info":{"description":"Additional information specific to the government security","properties":{"close_units":{"description":"Closing balance units for the statement period (beta)","format":"float","type":["number","null"]},"open_units":{"description":"Opening balance units for the statement period (beta)","format":"float","type":["number","null"]}},"type":"object"},"isin":{"description":"ISIN code of the government security","type":"string"},"name":{"description":"Name of the government security","type":"string"},"transactions":{"description":"List of transactions for this holding (beta)","items":{"$ref":"#/components/schemas/Transaction"},"type":"array"},"units":{"description":"Number of units held","format":"float","type":"number"},"value":{"description":"Current market value of the holding","format":"float","type":"number"}},"type":"object"},"InboundEmail":{"description":"An inbound email address for receiving forwarded CAS emails","properties":{"allowed_sources":{"description":"Accepted CAS providers (empty = all)","example":["cdsl","nsdl"],"items":{"enum":["cdsl","nsdl","cams","kfintech"],"type":"string"},"type":"array"},"callback_url":{"description":"Webhook URL for email notifications. If set, we POST each parsed\nemail here. If omitted, files are only retrievable via\n`GET /v4/inbound-email/{id}/files`.\n","example":"https://api.yourapp.com/webhooks/cas-email","format":"uri","type":"string"},"created_at":{"description":"When the inbound email was created","example":"2025-02-21T10:30:00Z","format":"date-time","type":"string"},"email":{"description":"The inbound email address to forward CAS statements to","example":"ie_a1b2c3d4e5f6@import.casparser.in","format":"email","type":"string"},"inbound_email_id":{"description":"Unique inbound email identifier","example":"ie_a1b2c3d4e5f6","type":"string"},"metadata":{"additionalProperties":{"type":"string"},"description":"Custom key-value metadata","example":{"plan":"premium"},"type":"object"},"reference":{"description":"Your internal reference identifier","example":"user_12345","type":["string","null"]},"status":{"description":"Current inbound email lifecycle status","enum":["active","paused"],"example":"active","type":"string"},"updated_at":{"description":"When the inbound email was last updated","example":"2025-02-21T10:30:00Z","format":"date-time","type":"string"}},"type":"object"},"InboundEmailWebhookPayload":{"description":"Webhook payload sent to your callback_url when an investor forwards a CAS email","properties":{"count":{"description":"Number of files","example":1,"type":"integer"},"files":{"description":"CAS files from the email (matches EmailCASFile schema)","items":{"$ref":"#/components/schemas/EmailCASFile"},"type":"array"},"forwarded_by":{"description":"Email address of the investor who forwarded the CAS email","example":"investor@gmail.com","format":"email","type":"string"},"inbound_email_id":{"description":"The inbound email address ID that received this email","example":"ie_a1b2c3d4e5f6","type":"string"},"metadata":{"additionalProperties":{"type":"string"},"description":"Your metadata from inbound email creation","example":{"plan":"premium"},"type":"object"},"reference":{"description":"Your reference from inbound email creation","example":"user_12345","type":["string","null"]}},"type":"object"},"LifeInsurancePolicy":{"properties":{"additional_info":{"description":"Additional information specific to the policy","type":"object"},"life_assured":{"description":"Name of the life assured","type":"string"},"policy_name":{"description":"Name of the insurance policy","type":"string"},"policy_number":{"description":"Insurance policy number","type":"string"},"premium_amount":{"description":"Premium amount","format":"float","type":"number"},"premium_frequency":{"description":"Frequency of premium payment (e.g., Annual, Monthly)","type":"string"},"provider":{"description":"Insurance company name","type":"string"},"status":{"description":"Status of the policy (e.g., Active, Lapsed)","type":"string"},"sum_assured":{"description":"Sum assured amount","format":"float","type":"number"}},"type":"object"},"LinkedHolder":{"properties":{"name":{"description":"Name of the account holder","type":"string"},"pan":{"description":"PAN of the account holder","type":"string"}},"type":"object"},"MutualFundFolio":{"properties":{"additional_info":{"description":"Additional folio information","properties":{"kyc":{"description":"KYC status of the folio","type":"string"},"pan":{"description":"PAN associated with the folio","type":"string"},"pankyc":{"description":"PAN KYC status","type":"string"}},"type":"object"},"amc":{"description":"Asset Management Company name","type":"string"},"folio_number":{"description":"Folio number","type":"string"},"linked_holders":{"description":"List of account holders linked to this mutual fund folio","items":{"$ref":"#/components/schemas/LinkedHolder"},"type":"array"},"registrar":{"description":"Registrar and Transfer Agent name","type":"string"},"schemes":{"items":{"$ref":"#/components/schemas/MutualFundScheme"},"type":"array"},"value":{"description":"Total value of the folio","format":"float","type":"number"}},"type":"object"},"MutualFundScheme":{"properties":{"additional_info":{"description":"Additional information specific to the scheme","properties":{"advisor":{"description":"Financial advisor name (CAMS/KFintech)","type":"string"},"amfi":{"description":"AMFI code for the scheme (CAMS/KFintech)","type":"string"},"close_units":{"description":"Closing balance units for the statement period","format":"float","type":["number","null"]},"open_units":{"description":"Opening balance units for the statement period","format":"float","type":["number","null"]},"rta_code":{"description":"RTA code for the scheme (CAMS/KFintech)","type":"string"}},"type":"object"},"cost":{"description":"Cost of investment","format":"float","type":"number"},"gain":{"properties":{"absolute":{"description":"Absolute gain or loss","format":"float","type":"number"},"percentage":{"description":"Percentage gain or loss","format":"float","type":"number"}},"type":"object"},"isin":{"description":"ISIN code of the scheme","type":"string"},"name":{"description":"Scheme name","type":"string"},"nav":{"description":"Net Asset Value per unit","format":"float","type":"number"},"nominees":{"description":"List of nominees","items":{"type":"string"},"type":"array"},"transactions":{"items":{"$ref":"#/components/schemas/Transaction"},"type":"array"},"type":{"description":"Type of mutual fund scheme","enum":["Equity","Debt","Hybrid","Other"],"type":"string"},"units":{"description":"Number of units held","format":"float","type":"number"},"value":{"description":"Current market value of the holding","format":"float","type":"number"}},"type":"object"},"NPSAccount":{"properties":{"additional_info":{"description":"Additional information specific to the NPS account","type":"object"},"cra":{"description":"Central Record Keeping Agency name","type":"string"},"funds":{"items":{"$ref":"#/components/schemas/NPSFund"},"type":"array"},"linked_holders":{"description":"List of account holders linked to this NPS account","items":{"$ref":"#/components/schemas/LinkedHolder"},"type":"array"},"pran":{"description":"Permanent Retirement Account Number (PRAN)","type":"string"},"value":{"description":"Total value of the NPS account","format":"float","type":"number"}},"type":"object"},"NPSFund":{"properties":{"additional_info":{"description":"Additional information specific to the NPS fund","properties":{"manager":{"description":"Fund manager name","type":"string"},"tier":{"description":"NPS tier (Tier I or Tier II)","enum":[1,2,null],"type":"number"}},"type":"object"},"cost":{"description":"Cost of investment","format":"float","type":"number"},"name":{"description":"Name of the NPS fund","type":"string"},"nav":{"description":"Net Asset Value per unit","format":"float","type":"number"},"units":{"description":"Number of units held","format":"float","type":"number"},"value":{"description":"Current market value of the holding","format":"float","type":"number"}},"type":"object"},"ReceivedEmailCASFile":{"allOf":[{"$ref":"#/components/schemas/EmailCASFile"},{"properties":{"received_at":{"description":"ISO 8601 timestamp (microsecond precision) when the file was\npersisted. Use as the `since` cursor on subsequent polls.\n","example":"2025-02-21T10:45:12.000123+00:00","format":"date-time","type":"string"}},"type":"object"}],"description":"A CAS file that has arrived at an inbound email address.\nMatches `EmailCASFile` plus a `received_at` timestamp used as a\nmonotonic cursor for polling.\n"},"Transaction":{"description":"Unified transaction schema for all holding types (MF folios, equities, bonds, etc.)","properties":{"additional_info":{"description":"Additional transaction-specific fields that vary by source","properties":{"capital_withdrawal":{"description":"Capital withdrawal amount (CDSL MF transactions)","format":"float","type":"number"},"credit":{"description":"Units credited (demat transactions)","format":"float","type":"number"},"debit":{"description":"Units debited (demat transactions)","format":"float","type":"number"},"income_distribution":{"description":"Income distribution amount (CDSL MF transactions)","format":"float","type":"number"},"order_no":{"description":"Order/transaction reference number (demat transactions)","type":"string"},"price":{"description":"Price per unit (NSDL/CDSL MF transactions)","format":"float","type":"number"},"stamp_duty":{"description":"Stamp duty charged","format":"float","type":"number"}},"type":"object"},"amount":{"description":"Transaction amount in currency (computed from units \u00d7 price/NAV)","format":"float","type":["number","null"]},"balance":{"description":"Balance units after transaction","format":"float","type":"number"},"date":{"description":"Transaction date (YYYY-MM-DD)","format":"date","type":"string"},"description":{"description":"Transaction description/particulars","type":"string"},"dividend_rate":{"description":"Dividend rate (for DIVIDEND_PAYOUT transactions)","format":"float","type":["number","null"]},"nav":{"description":"NAV/price per unit on transaction date","format":"float","type":["number","null"]},"type":{"description":"Transaction type. Possible values are 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.","enum":["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"],"type":"string"},"units":{"description":"Number of units involved in transaction","format":"float","type":"number"}},"type":"object"},"UnifiedResponse":{"properties":{"demat_accounts":{"items":{"$ref":"#/components/schemas/DematAccount"},"type":"array"},"insurance":{"properties":{"life_insurance_policies":{"items":{"$ref":"#/components/schemas/LifeInsurancePolicy"},"type":"array"}},"type":"object"},"investor":{"properties":{"address":{"description":"Address of the investor","type":"string"},"cas_id":{"description":"CAS ID of the investor (only for NSDL and CDSL)","type":"string"},"email":{"description":"Email address of the investor","format":"email","type":"string"},"mobile":{"description":"Mobile number of the investor","type":"string"},"name":{"description":"Name of the investor","type":"string"},"pan":{"description":"PAN (Permanent Account Number) of the investor","type":"string"},"pincode":{"description":"Postal code of the investor's address","type":"string"}},"type":"object"},"meta":{"properties":{"cas_type":{"description":"Type of CAS detected and processed","enum":["NSDL","CDSL","CAMS_KFINTECH"],"type":"string"},"generated_at":{"description":"Timestamp when the response was generated","format":"date-time","type":"string"},"statement_period":{"properties":{"from":{"description":"Start date of the statement period","format":"date","type":"string"},"to":{"description":"End date of the statement period","format":"date","type":"string"}},"type":"object"}},"type":"object"},"mutual_funds":{"items":{"$ref":"#/components/schemas/MutualFundFolio"},"type":"array"},"nps":{"description":"List of NPS accounts","items":{"$ref":"#/components/schemas/NPSAccount"},"type":"array"},"summary":{"properties":{"accounts":{"properties":{"demat":{"properties":{"count":{"description":"Number of demat accounts","type":"integer"},"total_value":{"description":"Total value of demat accounts","format":"float","type":"number"}},"type":"object"},"insurance":{"properties":{"count":{"description":"Number of insurance policies","type":"integer"},"total_value":{"description":"Total value of insurance policies","format":"float","type":"number"}},"type":"object"},"mutual_funds":{"properties":{"count":{"description":"Number of mutual fund folios","type":"integer"},"total_value":{"description":"Total value of mutual funds","format":"float","type":"number"}},"type":"object"},"nps":{"properties":{"count":{"description":"Number of NPS accounts","type":"integer"},"total_value":{"description":"Total value of NPS accounts","format":"float","type":"number"}},"type":"object"}},"type":"object"},"total_value":{"description":"Total portfolio value across all accounts","format":"float","type":"number"}},"type":"object"}},"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"description":"Your API key for authentication.\nUse `sandbox-with-json-responses` as Sandbox key.\n","in":"header","name":"x-api-key","type":"apiKey"}}},"info":{"contact":{"email":"sameer@casparser.in","name":"Sameer Kumar"},"description":"API for parsing and analyzing CAS (Consolidated Account Statement) PDF files from NSDL, CDSL, and CAMS/KFintech, with a unified response format","title":"CAS Parser - Track Portfolios from CDSL, NSDL, CAMS, KFintech","version":"4.0.0"},"openapi":"3.1.0","paths":{"/v1/agent-auth/token/{token}":{"get":{"description":"Agent polls this endpoint to check if the user has approved the authorization.\n\nReturns `{\"status\": \"pending\"}` while waiting for user approval.\nReturns `{\"status\": \"approved\", \"api_key\": \"sk_...\", \"email\": \"...\"}` once approved.\n\n**One-shot delivery:** the API key is returned exactly once. After delivery, the token is deleted\nand subsequent polls return `{\"status\": \"pending\"}`.\n\n**Recommended polling interval:** 5 seconds. Token expires after 10 minutes.\n","operationId":"agentAuthPoll","parameters":[{"description":"The token the agent generated locally and included in the approval URL.","in":"path","name":"token","required":true,"schema":{"example":"a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6a7b8c9d0e1f2a3b4c5d6a7b8c9d0e1f2","maxLength":128,"minLength":16,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"oneOf":[{"example":{"status":"pending"},"properties":{"status":{"enum":["pending"],"type":"string"}},"title":"Pending","type":"object"},{"example":{"api_key":"sk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6","email":"user@example.com","status":"approved"},"properties":{"api_key":{"description":"The issued API key (sk_ prefix)","type":"string"},"email":{"description":"Email of the user who approved","type":"string"},"status":{"enum":["approved"],"type":"string"}},"title":"Approved","type":"object"}]}}},"description":"Current authorization status"},"400":{"content":{"application/json":{"schema":{"properties":{"detail":{"example":"Token must be 16-128 characters","type":"string"}},"type":"object"}}},"description":"Invalid token length"}},"summary":"Poll for Agent Authorization Result","tags":["Agent Auth"]}},"/v1/agent-auth/token/{token}/approve":{"post":{"description":"Called by the frontend after the user signs in.\n\nVerifies the identity token, creates or looks up the user's API key,\nand stores it against the token for the agent to poll via `GET /v1/agent-auth/token/{token}`.\n\n**This endpoint is called by the browser, not by agents directly.**\n","operationId":"agentAuthApprove","parameters":[{"description":"The token the agent generated and included in the approval URL. Must be 16-128 characters.","in":"path","name":"token","required":true,"schema":{"example":"a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6a7b8c9d0e1f2a3b4c5d6a7b8c9d0e1f2","maxLength":128,"minLength":16,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"client_name":{"description":"Name of the agent/application (stored in customer metadata for audit)","example":"Claude Code","type":"string"},"id_token":{"description":"Identity token obtained after the user signs in on the approval page","type":"string"}},"required":["id_token"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"email":{"example":"user@example.com","type":"string"},"status":{"example":"approved","type":"string"}},"type":"object"}}},"description":"Authorization approved. The API key is now available for the agent to poll."},"400":{"content":{"application/json":{"schema":{"properties":{"detail":{"example":"Token must be 16-128 characters","type":"string"}},"type":"object"}}},"description":"Invalid token length or invalid request"},"401":{"content":{"application/json":{"schema":{"properties":{"detail":{"example":"Invalid identity token","type":"string"}},"type":"object"}}},"description":"Invalid or expired identity token"},"403":{"content":{"application/json":{"schema":{"properties":{"detail":{"example":"Unsupported sign-in method","type":"string"}},"type":"object"}}},"description":"Unsupported sign-in method"},"409":{"content":{"application/json":{"schema":{"properties":{"detail":{"example":"Token already approved or storage unavailable","type":"string"}},"type":"object"}}},"description":"Token was already approved (only the first approval is accepted)"}},"summary":"Approve Agent Authorization","tags":["Agent Auth"]}},"/v1/credits":{"post":{"description":"Check your remaining API credits and usage for the current billing period.\n\nReturns:\n- Number of API calls used and remaining credits\n- Credit limit and reset date\n- List of enabled features for your plan\n\nCredits reset at the start of each billing period.\n","operationId":"checkCredits","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"enabled_features":{"description":"List of API features enabled for your plan","example":["cams_kfintech_cas_parser","cdsl_cas_parser","nsdl_cas_parser"],"items":{"type":"string"},"type":"array"},"is_unlimited":{"description":"Whether the account has unlimited credits","example":false,"type":"boolean"},"limit":{"description":"Total credit limit for billing period","example":50,"type":"integer"},"remaining":{"description":"Remaining credits (null if unlimited)","example":35.0,"type":["number","null"]},"resets_at":{"description":"When credits reset (ISO 8601)","example":"2026-02-15T00:00:00Z","format":"date-time","type":["string","null"]},"used":{"description":"Number of credits used this billing period","example":15.0,"type":"number"}},"type":"object"}}},"description":"Credits information retrieved successfully"},"400":{"content":{"application/json":{"schema":{"properties":{"detail":{"example":"Access tokens cannot be used for credits API. Use your API key instead.","type":"string"}},"type":"object"}}},"description":"Bad request (e.g., using access token instead of API key)"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"ApiKeyAuth":[]}],"summary":"Check API Credits","tags":["Authorization"]}},"/v1/token":{"post":{"description":"Generate a short-lived access token from your API key.\n\n**Use this endpoint from your backend** to create tokens that can be safely passed to frontend/SDK.\n\n**Legacy path:** `/v1/access-token` (still supported)\n\nAccess tokens:\n- Are prefixed with `at_` for easy identification\n- Valid for up to 60 minutes\n- Can be used in place of API keys on all v4 endpoints\n- Cannot be used to generate other access tokens\n","operationId":"generateAccessToken","requestBody":{"content":{"application/json":{"schema":{"properties":{"expiry_minutes":{"default":60,"description":"Token validity in minutes (max 60)","example":60,"maximum":60,"minimum":1,"type":"integer"}},"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"access_token":{"description":"The at_ prefixed access token","example":"at_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","type":"string"},"expires_in":{"description":"Token validity in seconds","example":3600,"type":"integer"},"token_type":{"description":"Always \"api_key\" - token is a drop-in replacement for x-api-key header","example":"api_key","type":"string"}},"type":"object"}}},"description":"Access token generated successfully"},"400":{"content":{"application/json":{"schema":{"properties":{"detail":{"example":"Cannot create access token from access token","type":"string"}},"type":"object"}}},"description":"Bad request (e.g., trying to create token from access token)"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"ApiKeyAuth":[]}],"summary":"Generate Access Token","tags":["Portfolio Connect"]}},"/v1/token/verify":{"post":{"description":"Verify an access token and check if it's still valid.\nUseful for debugging token issues.\n","operationId":"verifyAccessToken","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"error":{"description":"Error message (only shown if invalid)","example":"Token has expired","type":"string"},"masked_api_key":{"description":"Masked API key (only shown if valid)","example":"abc1****ef23","type":"string"},"valid":{"description":"Whether the token is valid","example":true,"type":"boolean"}},"type":"object"}}},"description":"Token verification result"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"ApiKeyAuth":[]}],"summary":"Verify Access Token","tags":["Portfolio Connect"]}},"/v1/usage":{"post":{"description":"Retrieve detailed API usage logs for your account.\n\nReturns a list of API calls with timestamps, features used, status codes, and credits consumed.\nUseful for monitoring usage patterns and debugging.\n\n**Legacy path:** `/logs` (still supported)\n","operationId":"getUsageLogs","requestBody":{"content":{"application/json":{"schema":{"properties":{"end_time":{"description":"End time filter (ISO 8601). Defaults to now.","example":"2026-01-31T23:59:59Z","format":"date-time","type":"string"},"limit":{"default":100,"description":"Maximum number of logs to return","maximum":500,"minimum":1,"type":"integer"},"start_time":{"description":"Start time filter (ISO 8601). Defaults to 30 days ago.","example":"2026-01-01T00:00:00Z","format":"date-time","type":"string"}},"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"count":{"description":"Number of logs returned","example":25,"type":"integer"},"logs":{"items":{"properties":{"credits":{"description":"Credits consumed for this request","example":1.0,"type":"number"},"feature":{"description":"API feature used","example":"cdsl_cas_parser","type":"string"},"path":{"description":"API endpoint path","example":"/v4/cdsl/parse","type":"string"},"request_id":{"description":"Unique request identifier","example":"req_2xYz7KpL8mN3Ab","type":"string"},"status_code":{"description":"HTTP response status code","example":200,"type":"integer"},"timestamp":{"description":"When the request was made","example":"2026-01-15T14:30:00Z","format":"date-time","type":"string"}},"type":"object"},"type":"array"},"status":{"example":"success","type":"string"}},"type":"object"}}},"description":"Usage logs retrieved successfully"},"400":{"content":{"application/json":{"schema":{"properties":{"detail":{"example":"Access tokens cannot be used for logs API. Use your API key instead.","type":"string"}},"type":"object"}}},"description":"Bad request (e.g., using access token)"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"ApiKeyAuth":[]}],"summary":"Get API Usage Logs","tags":["Authorization"]}},"/v1/usage/summary":{"post":{"description":"Get aggregated usage statistics grouped by feature.\n\nUseful for understanding which API features are being used most and tracking usage trends.\n\n**Legacy path:** `/logs/summary` (still supported)\n","operationId":"getUsageSummary","requestBody":{"content":{"application/json":{"schema":{"properties":{"end_time":{"description":"End time filter (ISO 8601). Defaults to now.","format":"date-time","type":"string"},"start_time":{"description":"Start time filter (ISO 8601). Defaults to start of current month.","format":"date-time","type":"string"}},"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"status":{"example":"success","type":"string"},"summary":{"properties":{"by_feature":{"description":"Usage breakdown by feature","items":{"properties":{"credits":{"description":"Credits consumed by this feature","example":15.0,"type":"number"},"feature":{"description":"API feature name","example":"cdsl_cas_parser","type":"string"},"requests":{"description":"Number of requests for this feature","example":15,"type":"integer"}},"type":"object"},"type":"array"},"total_credits":{"description":"Total credits consumed in the period","example":45.5,"type":"number"},"total_requests":{"description":"Total API requests made in the period","example":42,"type":"integer"}},"type":"object"}},"type":"object"}}},"description":"Usage summary retrieved successfully"},"400":{"content":{"application/json":{"schema":{"properties":{"detail":{"example":"Access tokens cannot be used for logs API. Use your API key instead.","type":"string"}},"type":"object"}}},"description":"Bad request (e.g., using access token)"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"ApiKeyAuth":[]}],"summary":"Get Usage Summary","tags":["Authorization"]}},"/v4/cams_kfintech/parse":{"post":{"description":"This endpoint specifically parses CAMS/KFintech CAS (Consolidated Account Statement) PDF files and returns data in a unified format.\nUse this endpoint when you know the PDF is from CAMS or KFintech.\n","operationId":"camsKfintechParse","requestBody":{"$ref":"#/components/requestBodies/CASParseRequest"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnifiedResponse"}}},"description":"Successful operation"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request (Invalid PDF file, missing parameters, invalid password, or incorrect CAS type)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"ApiKeyAuth":[]}],"summary":"Parse CAMS/KFintech CAS PDF","tags":["CAS Parser"]}},"/v4/cdsl/fetch":{"post":{"description":"**Step 1 of 2**: Request OTP for CDSL CAS fetch.\n\nThis endpoint:\n1. Solves reCAPTCHA automatically (~15-20 seconds)\n2. Submits login credentials to CDSL portal\n3. Triggers OTP to user's registered mobile number\n\nAfter user receives OTP, call `/v4/cdsl/fetch/{session_id}/verify` to complete.\n","operationId":"cdslFetchRequestOTP","requestBody":{"content":{"application/json":{"schema":{"properties":{"bo_id":{"description":"CDSL BO ID (16 digits)","example":"1234567890123456","type":"string"},"dob":{"description":"Date of birth (YYYY-MM-DD)","example":"1990-01-15","type":"string"},"pan":{"description":"PAN number","example":"ABCDE1234F","type":"string"}},"required":["pan","bo_id","dob"],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"msg":{"example":"OTP sent to registered mobile","type":"string"},"session_id":{"description":"Session ID for verify step","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"},"status":{"example":"success","type":"string"}},"type":"object"}}},"description":"OTP sent to registered mobile"},"400":{"$ref":"#/components/responses/ParseBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"ApiKeyAuth":[]}],"summary":"CDSL CAS Fetch - Step 1 (Request OTP)","tags":["CAS Fetch"]}},"/v4/cdsl/fetch/{session_id}/verify":{"post":{"description":"**Step 2 of 2**: Verify OTP and retrieve CDSL CAS files.\n\nAfter successful verification, CAS PDFs are fetched from CDSL portal,\nuploaded to cloud storage, and returned as direct download URLs.\n","operationId":"cdslFetchVerifyOTP","parameters":[{"description":"Session ID from Step 1","in":"path","name":"session_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"num_periods":{"default":6,"description":"Number of monthly statements to fetch (default 6)","example":6,"type":"integer"},"otp":{"description":"OTP received on mobile","example":"123456","type":"string"}},"required":["otp"],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"files":{"items":{"properties":{"filename":{"example":"CDSL_CAS_1234567890123456_NOV2025.pdf","type":"string"},"url":{"description":"Direct download URL (cloud storage)","example":"https://cdn.casparser.in/cdsl-cas/session-id/CDSL_CAS_1234567890123456_NOV2025.pdf","type":"string"}},"type":"object"},"type":"array"},"msg":{"example":"Fetched 6 CAS files","type":"string"},"status":{"example":"success","type":"string"}},"type":"object"}}},"description":"CAS files fetched successfully"},"400":{"$ref":"#/components/responses/ParseBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Session not found or expired"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"ApiKeyAuth":[]}],"summary":"CDSL CAS Fetch - Step 2 (Verify OTP & Get Files)","tags":["CAS Fetch"]}},"/v4/cdsl/parse":{"post":{"description":"This endpoint specifically parses CDSL CAS (Consolidated Account Statement) PDF files and returns data in a unified format.\nUse this endpoint when you know the PDF is from CDSL.\n","operationId":"cdslParse","requestBody":{"$ref":"#/components/requestBodies/CASParseRequest"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnifiedResponse"}}},"description":"Successful operation"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request (Invalid PDF file, missing parameters, invalid password, or incorrect CAS type)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"ApiKeyAuth":[]}],"summary":"Parse CDSL CAS PDF","tags":["CAS Parser"]}},"/v4/contract_note/parse":{"post":{"description":"This endpoint parses Contract Note PDF files from various brokers including Zerodha, Groww, Upstox, ICICI Securities, and others.\n\n**What is a Contract Note?**\nA contract note is a legal document that provides details of all trades executed by an investor. It includes:\n- Trade details with timestamps, quantities, and prices\n- Brokerage and charges breakdown\n- Settlement information\n- Regulatory compliance details\n\n**Supported Brokers:**\n- Zerodha Broking Limited\n- Groww Invest Tech Private Limited  \n- Upstox (RKSV Securities)\n- ICICI Securities Limited\n- Auto-detection for unknown brokers\n\n**Key Features:**\n- **Auto-detection**: Automatically identifies broker type from PDF content\n- **Comprehensive parsing**: Extracts equity transactions, derivatives transactions, detailed trades, and charges\n- **Flexible input**: Accepts both file upload and URL-based PDF input\n- **Password protection**: Supports password-protected PDFs\n\nThe API returns structured data including contract note information, client details, transaction summaries, and detailed trade-by-trade breakdowns.\n","operationId":"parseContractNote","requestBody":{"$ref":"#/components/requestBodies/ContractNoteParseRequest"},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/ContractNoteResponse"},"msg":{"example":"success","type":"string"},"status":{"example":"success","type":"string"}},"type":"object"}}},"description":"Successfully parsed contract note"},"400":{"$ref":"#/components/responses/ParseBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"ApiKeyAuth":[]}],"summary":"Parse Contract Note PDF","tags":["Contract Note Parser"]}},"/v4/inbound-email":{"get":{"description":"List all inbound emails associated with your API key.\nReturns active and paused inbound emails (deleted ones are excluded).\n","operationId":"listInboundEmails","parameters":[{"description":"Filter by status","in":"query","name":"status","schema":{"default":"all","enum":["active","paused","all"],"type":"string"}},{"description":"Maximum number of inbound emails to return","in":"query","name":"limit","schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}},{"description":"Pagination offset","in":"query","name":"offset","schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"inbound_emails":{"items":{"$ref":"#/components/schemas/InboundEmail"},"type":"array"},"limit":{"example":50,"type":"integer"},"offset":{"example":0,"type":"integer"},"status":{"example":"success","type":"string"},"total":{"description":"Total number of inbound emails (for pagination)","example":15,"type":"integer"}},"type":"object"}}},"description":"List of inbound emails"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"ApiKeyAuth":[]}],"summary":"List Inbound Emails","tags":["Inbound Email"]},"post":{"description":"Create a dedicated inbound email address for collecting CAS statements\nvia email forwarding. When an investor forwards a CAS email to this\naddress, we verify the sender and make the file available to you.\n\n`callback_url` is **optional**:\n- **Set it** \u2014 we POST each parsed email to your webhook as it arrives.\n- **Omit it** \u2014 retrieve files via `GET /v4/inbound-email/{id}/files`\n  without building a webhook consumer.\n","operationId":"createInboundEmail","requestBody":{"content":{"application/json":{"schema":{"properties":{"alias":{"description":"Optional custom email prefix (e.g.\n`john-portfolio@import.casparser.in`). 3-32 chars,\nalphanumeric + hyphens, must start/end with a letter or\nnumber. If omitted, a random ID is generated.\n","example":"john-portfolio","maxLength":32,"minLength":3,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$","type":"string"},"allowed_sources":{"description":"Filter emails by CAS provider. If omitted, accepts all providers.\n- `cdsl` \u2192 eCAS@cdslstatement.com\n- `nsdl` \u2192 NSDL-CAS@nsdl.co.in\n- `cams` \u2192 donotreply@camsonline.com\n- `kfintech` \u2192 samfS@kfintech.com\n","example":["cdsl","nsdl"],"items":{"enum":["cdsl","nsdl","cams","kfintech"],"type":"string"},"type":"array"},"callback_url":{"description":"Optional webhook URL where we POST parsed emails. Must be\nHTTPS in production (HTTP allowed for localhost). If omitted,\nretrieve files via `GET /v4/inbound-email/{id}/files`.\n","example":"https://api.yourapp.com/webhooks/cas-email","format":"uri","type":["string","null"]},"metadata":{"additionalProperties":{"type":"string"},"description":"Optional key-value pairs (max 10) to include in webhook payload.\nUseful for passing context like plan_type, campaign_id, etc.\n","example":{"plan":"premium","source":"onboarding"},"maxProperties":10,"type":"object"},"reference":{"description":"Your internal identifier (e.g., user_id, account_id).\nReturned in webhook payload for correlation.\n","example":"user_12345","maxLength":256,"type":"string"}},"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundEmail"}}},"description":"Inbound email created successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid request (malformed URL, invalid sources, etc.)"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"ApiKeyAuth":[]}],"summary":"Create Inbound Email","tags":["Inbound Email"]}},"/v4/inbound-email/{inbound_email_id}":{"delete":{"description":"Permanently delete an inbound email address. It will stop accepting emails.\n\n**Note:** Deletion is immediate and cannot be undone. Any emails received after\ndeletion will be rejected.\n","operationId":"deleteInboundEmail","parameters":[{"description":"Inbound Email ID to delete","in":"path","name":"inbound_email_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"msg":{"example":"Inbound email deleted successfully","type":"string"},"status":{"example":"success","type":"string"}},"type":"object"}}},"description":"Inbound email deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Inbound email not found"}},"security":[{"ApiKeyAuth":[]}],"summary":"Delete Inbound Email","tags":["Inbound Email"]},"get":{"description":"Retrieve details of a specific inbound email including statistics.\n","operationId":"getInboundEmail","parameters":[{"description":"Inbound Email ID","in":"path","name":"inbound_email_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundEmail"}}},"description":"Inbound email details"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Inbound email not found"}},"security":[{"ApiKeyAuth":[]}],"summary":"Get Inbound Email Details","tags":["Inbound Email"]}},"/v4/inbound-email/{inbound_email_id}/files":{"get":{"description":"Retrieve CAS files forwarded to this inbound email. Available for every\ninbound email, regardless of whether a `callback_url` was set \u2014 use it\nto avoid building a webhook consumer, to poll alongside a webhook, or\nto replay missed webhook deliveries.\n\nPass the `cursor` from the previous response as `since` to receive only\nnew files.\n","operationId":"listInboundEmailFiles","parameters":[{"description":"Inbound Email ID (e.g., ie_a1b2c3d4e5f6)","example":"ie_a1b2c3d4e5f6","in":"path","name":"inbound_email_id","required":true,"schema":{"type":"string"}},{"description":"ISO 8601 timestamp. Only files with `received_at` strictly greater\nthan this value are returned. Use the `cursor` value from the\nprevious response.\n","in":"query","name":"since","required":false,"schema":{"format":"date-time","type":"string"}},{"description":"Maximum files to return.","in":"query","name":"limit","required":false,"schema":{"default":20,"maximum":50,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"count":{"example":1,"type":"integer"},"cursor":{"description":"Pass as `since` on the next poll. `null` if no files and no prior cursor.","example":"2025-02-21T10:45:12.000123+00:00","format":"date-time","type":["string","null"]},"files":{"description":"Files received (sorted oldest-first)","items":{"$ref":"#/components/schemas/ReceivedEmailCASFile"},"type":"array"},"status":{"example":"success","type":"string"}},"type":"object"}}},"description":"Files received at this inbound email since the cursor"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Malformed query parameters"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Inbound email not found or expired"}},"security":[{"ApiKeyAuth":[]}],"summary":"List Files Received","tags":["Inbound Email"]}},"/v4/inbox/cas":{"post":{"description":"Search the user's email inbox for CAS files from known senders\n(CAMS, KFintech, CDSL, NSDL).\n\nFiles are uploaded to temporary cloud storage. **URLs expire in 24 hours.**\n\nOptionally filter by CAS provider and date range.\n\n**Billing:** 0.2 credits per request (charged regardless of success or number of files found).\n","operationId":"inboxCasList","parameters":[{"description":"The encrypted inbox token","in":"header","name":"x-inbox-token","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"cas_types":{"description":"Filter by CAS provider(s):\n- `cdsl` \u2192 eCAS@cdslstatement.com\n- `nsdl` \u2192 NSDL-CAS@nsdl.co.in\n- `cams` \u2192 donotreply@camsonline.com\n- `kfintech` \u2192 samfS@kfintech.com\n","example":["cdsl","nsdl"],"items":{"enum":["cdsl","nsdl","cams","kfintech"],"type":"string"},"type":"array"},"end_date":{"description":"End date in ISO format (YYYY-MM-DD). Defaults to today.","example":"2025-12-31","format":"date","type":"string"},"start_date":{"description":"Start date in ISO format (YYYY-MM-DD). Defaults to 30 days ago.","example":"2025-12-01","format":"date","type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"count":{"description":"Number of CAS files found","example":5,"type":"integer"},"files":{"items":{"$ref":"#/components/schemas/EmailCASFile"},"type":"array"},"status":{"example":"success","type":"string"}},"type":"object"}}},"description":"CAS files found in inbox"},"401":{"content":{"application/json":{"schema":{"properties":{"msg":{"example":"Email access revoked. Please reconnect.","type":"string"},"requires_reconnect":{"example":true,"type":"boolean"},"status":{"example":"error","type":"string"}},"type":"object"}}},"description":"Token invalid or revoked"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"ApiKeyAuth":[]}],"summary":"List CAS Files from Email Inbox","tags":["Email Import"]}},"/v4/inbox/connect":{"post":{"description":"Initiate OAuth flow to connect user's email inbox.\n\nReturns an `oauth_url` that you should redirect the user to. After authorization,\nthey are redirected back to your `redirect_uri` with the following query parameters:\n\n**On success:**\n- `inbox_token` - Encrypted token to store client-side\n- `email` - Email address of the connected account\n- `state` - Your original state parameter (for CSRF verification)\n\n**On error:**\n- `error` - Error code (e.g., `access_denied`, `token_exchange_failed`)\n- `state` - Your original state parameter\n\n**Store the `inbox_token` client-side** and use it for all subsequent inbox API calls.\n","operationId":"inboxConnect","requestBody":{"content":{"application/json":{"schema":{"properties":{"redirect_uri":{"description":"Your callback URL to receive the inbox_token (must be http or https)","example":"https://yourapp.com/oauth-callback","format":"uri","type":"string"},"state":{"description":"State parameter for CSRF protection (returned in redirect)","example":"abc123","type":"string"}},"required":["redirect_uri"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"expires_in":{"description":"Seconds until the OAuth URL expires (typically 10 minutes)","example":600,"type":"integer"},"oauth_url":{"description":"Redirect user to this URL to start OAuth flow","example":"https://accounts.google.com/o/oauth2/v2/auth?client_id=...","format":"uri","type":"string"},"status":{"example":"success","type":"string"}},"type":"object"}}},"description":"OAuth URL generated successfully"},"400":{"description":"Invalid or missing redirect_uri"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"ApiKeyAuth":[]}],"summary":"Connect Email Provider (Initiate OAuth)","tags":["Email Import"]}},"/v4/inbox/disconnect":{"post":{"description":"Revoke email access and invalidate the token.\n\nThis calls the provider's token revocation API (e.g., Google's revoke endpoint)\nto ensure the user's consent is properly removed.\n\nAfter calling this, the `inbox_token` becomes unusable.\n","operationId":"inboxDisconnect","parameters":[{"description":"The encrypted inbox token to revoke","in":"header","name":"x-inbox-token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"msg":{"example":"Email disconnected successfully","type":"string"},"status":{"example":"success","type":"string"}},"type":"object"}}},"description":"Successfully disconnected"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"ApiKeyAuth":[]}],"summary":"Disconnect Email Provider","tags":["Email Import"]}},"/v4/inbox/status":{"post":{"description":"Verify if an `inbox_token` is still valid and check connection status.\n\nUse this to check if the user needs to re-authenticate (e.g., if they\nrevoked access in their email provider settings).\n","operationId":"inboxStatus","parameters":[{"description":"The encrypted inbox token","in":"header","name":"x-inbox-token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"connected":{"description":"Whether the token is valid and usable","example":true,"type":"boolean"},"email":{"description":"Email address of the connected account","example":"user@gmail.com","format":"email","type":"string"},"provider":{"example":"gmail","type":"string"},"status":{"example":"success","type":"string"}},"type":"object"}}},"description":"Token status retrieved"},"401":{"content":{"application/json":{"schema":{"properties":{"msg":{"example":"Email access revoked. Please reconnect.","type":"string"},"requires_reconnect":{"example":true,"type":"boolean"},"status":{"example":"error","type":"string"}},"type":"object"}}},"description":"Token is invalid, expired, or revoked. User must reconnect."}},"security":[{"ApiKeyAuth":[]}],"summary":"Check Email Connection Status","tags":["Email Import"]}},"/v4/kfintech/generate":{"post":{"description":"Generate CAS via KFintech mailback. The CAS PDF will be sent to the investor's email.\n\nThis is an async operation - the investor receives the CAS via email within a few minutes.\nFor instant CAS retrieval, use CDSL Fetch (`/v4/cdsl/fetch`).\n","operationId":"kfintechGenerate","requestBody":{"content":{"application/json":{"schema":{"properties":{"email":{"description":"Email address to receive the CAS document","example":"user@example.com","type":"string"},"from_date":{"description":"Start date (YYYY-MM-DD)","example":"2023-01-01","type":"string"},"pan_no":{"description":"PAN number (optional)","example":"ABCDE1234F","type":"string"},"password":{"description":"Password for the PDF","example":"Abcdefghi12$","type":"string"},"to_date":{"description":"End date (YYYY-MM-DD)","example":"2023-12-31","type":"string"}},"required":["email","from_date","to_date","password"],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"msg":{"example":"CAS request submitted. Check email shortly.","type":"string"},"status":{"example":"success","type":"string"}},"type":"object"}}},"description":"Request submitted successfully"},"400":{"$ref":"#/components/responses/ParseBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"ApiKeyAuth":[]}],"summary":"KFintech CAS Generator (Email Mailback)","tags":["CAS Generator"]}},"/v4/nsdl/parse":{"post":{"description":"This endpoint specifically parses NSDL CAS (Consolidated Account Statement) PDF files and returns data in a unified format.\nUse this endpoint when you know the PDF is from NSDL.\n","operationId":"nsdlParse","requestBody":{"$ref":"#/components/requestBodies/CASParseRequest"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnifiedResponse"}}},"description":"Successful operation"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request (Invalid PDF file, missing parameters, invalid password, or incorrect CAS type)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"ApiKeyAuth":[]}],"summary":"Parse NSDL CAS PDF","tags":["CAS Parser"]}},"/v4/smart/parse":{"post":{"description":"This endpoint parses CAS (Consolidated Account Statement) PDF files from NSDL, CDSL, or CAMS/KFintech and returns data in a unified format.\nIt auto-detects the CAS type and transforms the data into a consistent structure regardless of the source.\n","operationId":"smartParse","requestBody":{"$ref":"#/components/requestBodies/CASParseRequest"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnifiedResponse"}}},"description":"Successful operation"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request (Invalid PDF file, missing parameters, or invalid password)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"ApiKeyAuth":[]}],"summary":"Smart Parse CAS PDF","tags":["CAS Parser"]}}},"servers":[{"description":"Production server","url":"https://api.casparser.in"},{"description":"Legacy production server (still supported)","url":"https://portfolio-parser.api.casparser.in"},{"description":"Local development server","url":"http://localhost:5000"}],"tags":[{"description":"Endpoints for parsing CAS PDF files from different sources.","name":"CAS Parser"},{"description":"Endpoints for generating new CAS documents via email mailback (KFintech).","name":"CAS Generator"},{"description":"Endpoints for fetching CAS documents with instant download.\nCurrently supports CDSL via OTP authentication.\n","name":"CAS Fetch"},{"description":"Endpoints for importing CAS files directly from user email inboxes.\n\n**Supported Providers:** Gmail (more coming soon)\n\n**How it works:**\n1. Call `POST /v4/inbox/connect` to get an OAuth URL\n2. Redirect user to the OAuth URL for consent\n3. User is redirected back to your `redirect_uri` with an encrypted `inbox_token`\n4. Use the token to list/fetch CAS files from their inbox (`/v4/inbox/cas`)\n5. Files are uploaded to temporary cloud storage (URLs expire in 24 hours)\n\n**Security:**\n- Read-only access (we cannot send emails)\n- Tokens are encrypted with server-side secret\n- User can revoke access anytime via `/v4/inbox/disconnect`\n","name":"Email Import"},{"description":"Create dedicated inbound email addresses for investors to forward their CAS statements.\n\n**Use Case:** Your app wants to collect CAS statements from users without requiring OAuth or file upload.\n\n**How it works:**\n1. Call `POST /v4/inbound-email` to create a unique inbound email address\n2. Display this email to your user: \"Forward your CAS statement to ie_xxx@import.casparser.in\"\n3. When user forwards a CAS email, we verify sender authenticity (SPF/DKIM) and call your webhook\n4. Your webhook receives email metadata + attachment download URLs\n\n**Sender Validation:**\n- Only emails from verified CAS authorities are processed:\n  - CDSL: `eCAS@cdslstatement.com`\n  - NSDL: `NSDL-CAS@nsdl.co.in`\n  - CAMS: `donotreply@camsonline.com`\n  - KFintech: `samfS@kfintech.com`\n- Emails failing SPF/DKIM/DMARC are rejected\n- Forwarded emails must contain the original sender in headers\n\n**Billing:** 0.2 credits per successfully processed valid email\n","name":"Inbound Email"},{"description":"Endpoints for parsing Contract Note PDF files from various SEBI brokers like Zerodha, Groww, Upstox, ICICI etc.","name":"Contract Note Parser"},{"description":"Endpoints for checking API quota and credits usage.\nThese endpoints help you monitor your API usage and remaining quota.\n","name":"Authorization"},{"description":"Endpoints for managing access tokens for the Portfolio Connect SDK.\nUse these to generate short-lived `at_` prefixed tokens that can be safely passed to frontend applications.\nAccess tokens can be used in place of API keys on all v4 endpoints.\n","name":"Portfolio Connect"},{"description":"Endpoints for coding agents to obtain API keys via a browser-based approval flow.\n\n**How it works:**\n1. Agent generates a random token locally (e.g. `openssl rand -hex 32`). No API call needed.\n2. Agent asks the user to open `https://app.casparser.in/agent-auth?token=<token>&client_name=<name>`\n3. User signs in via the browser and clicks Approve.\n4. Agent polls `GET /v1/agent-auth/token/{token}` every 5 seconds until the key is delivered.\n\n**Security:**\n- Token must be 16-128 characters (recommended: 64 hex chars / 256 bits)\n- Approved keys are delivered once (one-shot) and then deleted\n- Tokens expire after 10 minutes if not approved\n","name":"Agent Auth"}]}