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
| Field | Type | Required | Description |
|---|---|---|---|
source | string | Yes | Which issuer to request from: kfintech, cams, nsdl or cdsl. Only sources with request_automatable true work. |
pan | string | Yes | Investor PAN in capitals, for example ABCPE1234F; the fourth letter must be one of A, B, C, F, G, H, L, J, P, T. |
email | string | Yes | Where the issuer e-mails the statement; up to 120 characters. |
statement_type | string | No | summary or detailed. Defaults to summary (detailed adds every transaction). |
period | string | No | current_fy, previous_fy or specific. Defaults to current_fy. |
from_date | string | No | Start date as DD/MM/YYYY. Required when period is specific. |
to_date | string | No | End date as DD/MM/YYYY. Required when period is specific. |
cas_password | string | Yes | Password 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_folios | boolean | No | Also list folios with no units left. Defaults to false. |
max_attempts | integer | No | How 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
| Field | Type | Description |
|---|---|---|
request_id | string | Id of this statement request; use it on the request history calls. |
source | string | Which statement issuer the request went to. |
status | string | submitted when accepted, rejected when refused, session_open or expired otherwise. |
pan | string | The investor's PAN, masked. |
email | string | Where the statement will be e-mailed. |
statement_type | string | summary or detailed. |
period | string | current_fy, previous_fy or specific. |
from_date | string | Start date, DD/MM/YYYY; null unless period is specific. |
to_date | string | End date, DD/MM/YYYY; null unless period is specific. |
rta_code | string | The issuer's own result code, if it sent one. |
message | string | The issuer's reply text, word for word. |
created_at | string | When the request was created, ISO 8601. |
submitted_at | string | When the issuer accepted it, ISO 8601; null if it did not. |
accepted | boolean | True when the issuer accepted the request and will e-mail the statement. |
reason | string | Why it was refused: invalid_captcha, no_investment_found or rta_error. Present only when accepted is false. |
next | string | What to do next, in plain words. |
attempts | array | One entry per try. |
attempts[].attempt | integer | Try number, starting at 1. |
attempts[].outcome | string | accepted, 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.