API reference / CAS (portfolio fetch)

3.3 CAS Auto Import — import parsed CAS

Folds a parsed CAS into the portfolio: one stable key per position (so next month updates rather than duplicates), cost/value/gain rolled up, XIRR when available.

POST/v1/cas/import/document
Authentication
Bearer token
Scope
cas:import

Before you integrate

  • Use this when you already have the statement as JSON, for example from the read call. A body with no folios and no demat lines is refused.
  • Importing the next month's statement updates existing positions by key instead of adding duplicates.

Request body

FieldTypeRequiredDescription
sourcestringNoWho issued the statement: kfintech, cams, nsdl or cdsl.
statement_typestringNosummary or detailed.
period_fromstringNoStatement period start, up to 20 characters.
period_tostringNoStatement period end, up to 20 characters.
foliosarrayNoMutual-fund folio lines, up to 2000. Send at least one folio or one demat line.
folios[].foliostringNoFolio number, up to 60 characters.
folios[].amcstringNoFund house, up to 160 characters.
folios[].schemestringNoScheme name, up to 240 characters.
folios[].isinstringNoScheme ISIN, up to 20 characters.
folios[].unitsnumberNoUnits held. Defaults to 0.
folios[].nav_minorintegerNoNAV per unit in paise.
folios[].value_minorintegerNoMarket value in paise.
folios[].cost_minorintegerNoCost in paise.
folios[].as_ofstringNoValuation date, up to 20 characters.
dematarrayNoDemat holding lines, up to 2000.
demat[].dp_idstringNoDepository participant id, up to 30 characters.
demat[].client_idstringNoDemat client id, up to 30 characters.
demat[].isinstringNoSecurity ISIN, up to 20 characters.
demat[].securitystringNoSecurity name, up to 240 characters.
demat[].quantitynumberNoQuantity held. Defaults to 0.
demat[].price_minorintegerNoPrice per unit in paise.
demat[].value_minorintegerNoMarket value in paise.
demat[].asset_classstringNoAsset class, up to 40 characters.
demat[].as_ofstringNoValuation date, up to 20 characters.
transactionsarrayNoTransactions, up to 20000. Needed for an XIRR.
transactions[].foliostringNoFolio number, up to 60 characters.
transactions[].schemestringNoScheme name, up to 240 characters.
transactions[].isinstringNoISIN, up to 20 characters.
transactions[].datestringYesTransaction date, up to 20 characters; required for each transaction you send.
transactions[].descriptionstringNoDescription, up to 300 characters.
transactions[].typestringNoFor example purchase, redemption, switch_in, switch_out or dividend. Defaults to other.
transactions[].amount_minorintegerNoAmount in paise.
transactions[].unitsnumberNoUnits bought or sold.
transactions[].nav_minorintegerNoNAV per unit in paise.
transactions[].balance_unitsnumberNoUnit balance after the transaction.
review_requiredbooleanNoMark the data as needing a human check. Defaults to false.
warningsarrayNoUp to 200 notes, each up to 500 characters, kept with the import.

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/import/document' \
  -H "Authorization: Bearer $GRAPPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "source": "cams",
  "statement_type": "detailed",
  "period_to": "2024-03-31",
  "folios": [
    {
      "folio": "1234567/89",
      "scheme": "Test Liquid Fund - Growth",
      "isin": "INF209K01XX1",
      "units": 124.239,
      "nav_minor": 35512,
      "value_minor": 4412035,
      "cost_minor": 4000250
    }
  ]
}'

Sample response

{
  "request_id": "req_01HZY3K8M2",
  "result": {
    "import_id": "casim_1a2b3c4d5e6f7a8b",
    "source": "cams",
    "imported_at": "2026-11-06T09:30:00.000Z",
    "holding_count": 1,
    "created": 1,
    "updated": 0,
    "unchanged": 0,
    "total_value_minor": 4412035,
    "total_cost_minor": 4000250,
    "total_gain_minor": 411785,
    "xirr_percent": null,
    "holdings": [
      {
        "key": "mutual_fund:INF123K01014:1234567/89",
        "kind": "mutual_fund",
        "name": "Sample Liquid Fund - Growth",
        "isin": "INF123K01014",
        "folio": "1234567/89",
        "units": 124.239,
        "value_minor": 4412035,
        "cost_minor": 4000250,
        "gain_minor": 411785,
        "as_of": "2024-03-31"
      }
    ],
    "warnings": []
  }
}

Response fields

FieldTypeDescription
import_idstringId of this import run.
sourcestringWho issued the statement, if known.
imported_atstringWhen the import ran, ISO 8601.
holding_countintegerNumber of positions in the portfolio after this import.
createdintegerPositions added by this import.
updatedintegerExisting positions whose figures changed.
unchangedintegerExisting positions that stayed the same.
total_value_minorintegerTotal market value in paise.
total_cost_minorintegerTotal cost in paise.
total_gain_minorintegerTotal gain in paise.
xirr_percentnumberAnnualised return in percent across all dated transactions; null unless the statement is detailed.
holdingsarrayThe positions.
holdings[].keystringStable id of the position; the same position gets the same key every month.
holdings[].kindstringmutual_fund or demat.
holdings[].namestringScheme or security name.
holdings[].isinstringISIN, if known.
holdings[].foliostringFolio or demat client id.
holdings[].unitsnumberUnits or quantity held.
holdings[].value_minorintegerMarket value in paise.
holdings[].cost_minorintegerCost in paise.
holdings[].gain_minorintegerGain in paise.
holdings[].as_ofstringValuation date.
warningsarrayPlain-text issues found, if any.

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.