API reference / CAS (portfolio fetch)

3.1 CAS Auto Request — one call

Opens the RTA session, completes its verification step and submits, retrying with a fresh session on a misread. One call, one price regardless of attempts.

POST/v1/cas/request/auto
Authentication
Bearer token
Scope
cas:request

Before you integrate

  • Does the CAPTCHA step for you. The price is the same however many attempts it takes.
  • Check the cas-providers call first: if the one-call request is not available, this returns a validation error and you must use the two-step flow.
  • Unknown fields in the body are rejected. If period is specific, from_date and to_date are both required.
  • A reply with accepted false is still a completed call and is charged.

Request body

FieldTypeRequiredDescription
sourcestringYesWhich issuer to request from: kfintech, cams, nsdl or cdsl. Only sources with request_automatable true work.
panstringYesInvestor PAN in capitals, for example ABCPE1234F; the fourth letter must be one of A, B, C, F, G, H, L, J, P, T.
emailstringYesWhere the issuer e-mails the statement; up to 120 characters.
statement_typestringNosummary or detailed. Defaults to summary (detailed adds every transaction).
periodstringNocurrent_fy, previous_fy or specific. Defaults to current_fy.
from_datestringNoStart date as DD/MM/YYYY. Required when period is specific.
to_datestringNoEnd date as DD/MM/YYYY. Required when period is specific.
cas_passwordstringYesPassword the PDF will be locked with: 8 to 12 characters with a capital letter, a small letter, a digit and a symbol.
include_zero_balance_foliosbooleanNoAlso list folios with no units left. Defaults to false.
max_attemptsintegerNoHow many times to retry with a fresh CAPTCHA, from 1 to 5. Defaults to 3.

Sample code

Set your key in the GRAPPI_API_KEY environment variable. Sample values are placeholders.

curl -sS -X POST 'https://grappi.ai/v1/cas/request/auto' \
  -H "Authorization: Bearer $GRAPPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "source": "kfintech",
  "pan": "ABCPA1234A",
  "email": "investor@example.com",
  "statement_type": "detailed",
  "period": "current_fy",
  "cas_password": "Grappi@2026",
  "max_attempts": 3
}'

Sample response

{
  "request_id": "req_01HZY3K8M2",
  "result": {
    "request_id": "casrq_1a2b3c4d5e6f7a8b",
    "source": "kfintech",
    "status": "submitted",
    "pan": "******234F",
    "email": "asha.rao@example.com",
    "statement_type": "detailed",
    "period": "current_fy",
    "from_date": null,
    "to_date": null,
    "rta_code": null,
    "message": "Your request has been received. The statement will be e-mailed shortly.",
    "created_at": "2026-11-06T09:30:00.000Z",
    "submitted_at": "2026-11-06T09:30:04.000Z",
    "accepted": true,
    "attempts": [
      {
        "attempt": 1,
        "outcome": "accepted"
      }
    ],
    "next": "The RTA mails the PDF to the investor. Pick it up with POST /v1/cas/read/mailbox/scan, or upload it to POST /v1/cas/read."
  }
}

Response fields

FieldTypeDescription
request_idstringId of this statement request; use it on the request history calls.
sourcestringWhich statement issuer the request went to.
statusstringsubmitted when accepted, rejected when refused, session_open or expired otherwise.
panstringThe investor's PAN, masked.
emailstringWhere the statement will be e-mailed.
statement_typestringsummary or detailed.
periodstringcurrent_fy, previous_fy or specific.
from_datestringStart date, DD/MM/YYYY; null unless period is specific.
to_datestringEnd date, DD/MM/YYYY; null unless period is specific.
rta_codestringThe issuer's own result code, if it sent one.
messagestringThe issuer's reply text, word for word.
created_atstringWhen the request was created, ISO 8601.
submitted_atstringWhen the issuer accepted it, ISO 8601; null if it did not.
acceptedbooleanTrue when the issuer accepted the request and will e-mail the statement.
reasonstringWhy it was refused: invalid_captcha, no_investment_found or rta_error. Present only when accepted is false.
nextstringWhat to do next, in plain words.
attemptsarrayOne entry per try.
attempts[].attemptintegerTry number, starting at 1.
attempts[].outcomestringaccepted, or the reason it was refused.

Errors

Every failure has the same shape. A call that fails on our side or at the data source is refunded to your wallet; a "no record found" answer is charged. See the error reference.