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

FieldTypeRequiredDescription
hoststringYesMail server host, 3 to 200 characters, for example imap.gmail.com.
portintegerNoMail server port, 1 to 65535. Defaults to 993.
securebooleanNoUse an encrypted connection. Defaults to true.
userstringYesMailbox login, 3 to 200 characters.
passwordstringYesMailbox password, 1 to 300 characters. Use an app password, not the main account password.
mailboxstringNoFolder to search, 1 to 100 characters. Uses the account's main inbox when left out.
since_daysintegerNoHow far back to look, from 1 to 730 days. Defaults to 120.
max_messagesintegerNoMost messages to check, from 1 to 100. Defaults to 25.
extra_sendersarrayNoUp to 10 extra sender addresses or domains to accept, each 3 to 200 characters.
cas_passwordstringNoThe password chosen when the statement was requested (CAMS, KFintech); up to 64 characters. Send this or pan.
panstringNoThe investor's PAN, which opens NSDL and CDSL statements. Send this or cas_password.
dobstringNoDate of birth as YYYY-MM-DD, for statements that need it.
limitintegerNoHow 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

FieldTypeDescription
foundintegerStatements found in the mailbox.
parsedintegerStatements read; absent when none were found.
documentsarrayThe statements that were read.
documents[].emailobjectThe e-mail the statement came from.
documents[].email.fromstringSender address.
documents[].email.subjectstringSubject line.
documents[].email.received_atstringWhen it arrived, ISO 8601.
documents[].email.filenamestringAttachment file name.
documents[].sourcestringWho issued the statement: kfintech, cams, nsdl or cdsl; null if it could not be told.
documents[].statement_typestringsummary or detailed; null if unknown.
documents[].investor_namestringInvestor name printed on the statement.
documents[].investor_emailstringInvestor email printed on the statement.
documents[].panstringThe investor's PAN, masked.
documents[].period_fromstringStatement period start.
documents[].period_tostringStatement period end.
documents[].holding_countintegerNumber of mutual-fund folios plus demat holdings found.
documents[].transaction_countintegerNumber of transactions found; 0 on a summary statement.
documents[].total_value_minorintegerTotal market value in paise, when the statement prints one.
documents[].foliosarrayMutual-fund folio lines.
documents[].folios[].foliostringFolio number.
documents[].folios[].amcstringFund house name.
documents[].folios[].schemestringScheme name.
documents[].folios[].isinstringScheme ISIN.
documents[].folios[].unitsnumberUnits held.
documents[].folios[].nav_minorintegerNAV per unit in paise.
documents[].folios[].value_minorintegerMarket value in paise.
documents[].folios[].cost_minorintegerCost of holding in paise, when printed.
documents[].folios[].as_ofstringValuation date.
documents[].dematarrayDemat holding lines (NSDL and CDSL statements).
documents[].demat[].dp_idstringDepository participant id.
documents[].demat[].client_idstringDemat client id.
documents[].demat[].isinstringSecurity ISIN.
documents[].demat[].securitystringSecurity name.
documents[].demat[].quantitynumberQuantity held.
documents[].demat[].price_minorintegerPrice per unit in paise.
documents[].demat[].value_minorintegerMarket value in paise.
documents[].demat[].asset_classstringAsset class as printed on the statement.
documents[].demat[].as_ofstringValuation date.
documents[].transactionsarrayTransactions; only present on a detailed statement.
documents[].transactions[].foliostringFolio number, for mutual-fund transactions.
documents[].transactions[].schemestringScheme name.
documents[].transactions[].isinstringISIN.
documents[].transactions[].datestringTransaction date.
documents[].transactions[].descriptionstringDescription as printed.
documents[].transactions[].typestringFor example purchase, redemption, switch_in, switch_out or dividend.
documents[].transactions[].amount_minorintegerAmount in paise.
documents[].transactions[].unitsnumberUnits bought or sold.
documents[].transactions[].nav_minorintegerNAV per unit in paise.
documents[].transactions[].balance_unitsnumberUnit balance after the transaction.
documents[].confidencenumberHow sure the reading is, from 0 to 1.
documents[].review_requiredbooleanTrue when confidence is low and a person should check the figures.
documents[].warningsarrayPlain-text issues found while reading, if any.
hintstringPresent 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.