API reference / CAS (portfolio fetch)
3.2 CAS Auto Read — mailbox scan
Finds the RTA's mail over IMAP, pulls the attachment, decrypts and parses it. Use an app password.
POST
/v1/cas/read/mailbox/scan- Authentication
- Bearer token
- Scope
cas:read
Before you integrate
- Send either cas_password (CAMS, KFintech statements) or pan (NSDL, CDSL statements) so the PDF can be opened. Unknown fields in the body are rejected.
- Mailbox login details are used for this call only and are not stored.
- Each call is charged to your wallet, and works only once this API is activated for your account.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
host | string | Yes | Mail server host, 3 to 200 characters, for example imap.gmail.com. |
port | integer | No | Mail server port, 1 to 65535. Defaults to 993. |
secure | boolean | No | Use an encrypted connection. Defaults to true. |
user | string | Yes | Mailbox login, 3 to 200 characters. |
password | string | Yes | Mailbox password, 1 to 300 characters. Use an app password, not the main account password. |
mailbox | string | No | Folder to search, 1 to 100 characters. Uses the account's main inbox when left out. |
since_days | integer | No | How far back to look, from 1 to 730 days. Defaults to 120. |
max_messages | integer | No | Most messages to check, from 1 to 100. Defaults to 25. |
extra_senders | array | No | Up to 10 extra sender addresses or domains to accept, each 3 to 200 characters. |
cas_password | string | No | The password chosen when the statement was requested (CAMS, KFintech); up to 64 characters. Send this or pan. |
pan | string | No | The investor's PAN, which opens NSDL and CDSL statements. Send this or cas_password. |
dob | string | No | Date of birth as YYYY-MM-DD, for statements that need it. |
limit | integer | No | How many of the newest statements to read, from 1 to 10. Defaults to 1. |
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/read/mailbox/scan' \
-H "Authorization: Bearer $GRAPPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"host": "imap.gmail.com",
"port": 993,
"secure": true,
"user": "investor@gmail.com",
"password": "app-specific-password",
"cas_password": "Grappi@2026",
"since_days": 120
}'Sample response
{
"request_id": "req_01HZY3K8M2",
"result": {
"found": 1,
"parsed": 1,
"documents": [
{
"email": {
"from": "statements@example.com",
"subject": "Your Consolidated Account Statement",
"received_at": "2026-11-02T06:10:00.000Z",
"filename": "cas_statement.pdf"
},
"source": "cams",
"statement_type": "detailed",
"investor_name": "ASHA RAO",
"investor_email": "asha.rao@example.com",
"pan": "******234F",
"period_from": "2023-04-01",
"period_to": "2024-03-31",
"holding_count": 1,
"transaction_count": 1,
"total_value_minor": 4412035,
"folios": [
{
"folio": "1234567/89",
"amc": "Sample Mutual Fund",
"scheme": "Sample Liquid Fund - Growth",
"isin": "INF123K01014",
"units": 124.239,
"nav_minor": 35512,
"value_minor": 4412035,
"cost_minor": 4000250,
"as_of": "2024-03-31"
}
],
"demat": [],
"transactions": [
{
"folio": "1234567/89",
"scheme": "Sample Liquid Fund - Growth",
"isin": "INF123K01014",
"date": "2023-06-12",
"description": "Purchase",
"type": "purchase",
"amount_minor": 4000250,
"units": 124.239,
"nav_minor": 32198,
"balance_units": 124.239
}
],
"confidence": 0.97,
"review_required": false,
"warnings": []
}
]
}
}Response fields
| Field | Type | Description |
|---|---|---|
found | integer | Statements found in the mailbox. |
parsed | integer | Statements read; absent when none were found. |
documents | array | The statements that were read. |
documents[].email | object | The e-mail the statement came from. |
documents[].email.from | string | Sender address. |
documents[].email.subject | string | Subject line. |
documents[].email.received_at | string | When it arrived, ISO 8601. |
documents[].email.filename | string | Attachment file name. |
documents[].source | string | Who issued the statement: kfintech, cams, nsdl or cdsl; null if it could not be told. |
documents[].statement_type | string | summary or detailed; null if unknown. |
documents[].investor_name | string | Investor name printed on the statement. |
documents[].investor_email | string | Investor email printed on the statement. |
documents[].pan | string | The investor's PAN, masked. |
documents[].period_from | string | Statement period start. |
documents[].period_to | string | Statement period end. |
documents[].holding_count | integer | Number of mutual-fund folios plus demat holdings found. |
documents[].transaction_count | integer | Number of transactions found; 0 on a summary statement. |
documents[].total_value_minor | integer | Total market value in paise, when the statement prints one. |
documents[].folios | array | Mutual-fund folio lines. |
documents[].folios[].folio | string | Folio number. |
documents[].folios[].amc | string | Fund house name. |
documents[].folios[].scheme | string | Scheme name. |
documents[].folios[].isin | string | Scheme ISIN. |
documents[].folios[].units | number | Units held. |
documents[].folios[].nav_minor | integer | NAV per unit in paise. |
documents[].folios[].value_minor | integer | Market value in paise. |
documents[].folios[].cost_minor | integer | Cost of holding in paise, when printed. |
documents[].folios[].as_of | string | Valuation date. |
documents[].demat | array | Demat holding lines (NSDL and CDSL statements). |
documents[].demat[].dp_id | string | Depository participant id. |
documents[].demat[].client_id | string | Demat client id. |
documents[].demat[].isin | string | Security ISIN. |
documents[].demat[].security | string | Security name. |
documents[].demat[].quantity | number | Quantity held. |
documents[].demat[].price_minor | integer | Price per unit in paise. |
documents[].demat[].value_minor | integer | Market value in paise. |
documents[].demat[].asset_class | string | Asset class as printed on the statement. |
documents[].demat[].as_of | string | Valuation date. |
documents[].transactions | array | Transactions; only present on a detailed statement. |
documents[].transactions[].folio | string | Folio number, for mutual-fund transactions. |
documents[].transactions[].scheme | string | Scheme name. |
documents[].transactions[].isin | string | ISIN. |
documents[].transactions[].date | string | Transaction date. |
documents[].transactions[].description | string | Description as printed. |
documents[].transactions[].type | string | For example purchase, redemption, switch_in, switch_out or dividend. |
documents[].transactions[].amount_minor | integer | Amount in paise. |
documents[].transactions[].units | number | Units bought or sold. |
documents[].transactions[].nav_minor | integer | NAV per unit in paise. |
documents[].transactions[].balance_units | number | Unit balance after the transaction. |
documents[].confidence | number | How sure the reading is, from 0 to 1. |
documents[].review_required | boolean | True when confidence is low and a person should check the figures. |
documents[].warnings | array | Plain-text issues found while reading, if any. |
hint | string | Present only when nothing was found: what to check. |
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.