# Parse CAS

> POST /api/v1/parse — convert a CAS PDF into a structured snapshot.

Send a CAS PDF from CAMS, KFintech, or an NSDL e-CAS (which also covers CDSL
demat accounts). The parser is deterministic — no model reads the statement —
and returns a snapshot with holdings, units, NAV, cost and transactions.

## Endpoint

`POST https://api.portfoliointel.co.in/api/v1/parse`

## Authentication

`X-API-Key: sk_…` or `Authorization: Bearer sk_…`. Both `sk_test_` and
`sk_live_` keys can parse real PDFs here; each parse spends
[credits](#credits). No key yet? An agent can
[register one itself](https://docs.portfoliointel.co.in/api-reference/register).

| Client type | Auth model |
| --- | --- |
| Claude Desktop / ChatGPT | OAuth 2.1 + PKCE |
| Claude Code / Cursor / Copilot | Bearer token in config |
| REST clients | Bearer token or `X-API-Key` |

## Request

**cURL**

```bash
curl -X POST https://api.portfoliointel.co.in/api/v1/parse \
  -H "X-API-Key: $PI_KEY" \
  -F "file=@cas.pdf" \
  -F "password=$CAS_PASSWORD"
```

**Node**

```ts
const form = new FormData();
form.append('file', pdfBlob, 'cas.pdf');

const res = await fetch('https://api.portfoliointel.co.in/api/v1/parse', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.PI_KEY! },
  body: form,
});
```

**Python**

```python
r = requests.post(
    'https://api.portfoliointel.co.in/api/v1/parse',
    headers={'X-API-Key': os.environ['PI_KEY']},
    files={'file': open('cas.pdf', 'rb')},
)
```

### Body

Multipart (`file`) or JSON — send exactly one of `file`, `pdf_base64` or `pdf_url`.

| Field | Type | Notes |
| --- | --- | --- |
| `file` | file | Multipart only. |
| `pdf_base64` | string | JSON only. |
| `pdf_url` | string | Public HTTPS URL; the service fetches it. |
| `password` | string | For password-protected statements (usually the PAN in capitals). |
| `pi_redaction` | boolean | Default `true`: `investor_name` is returned as `"REDACTED"`. Send `false` to receive it. |

> **Caution**
>
> Agents that can't reach the user's file — most hosted chat clients — should use
> an [upload session](https://docs.portfoliointel.co.in/api-reference/upload-sessions) instead of asking the user
> to paste base64.

### Sandbox samples

Bundled sample statements live on the web host and need a **test** key. They
cost nothing and need no PDF.

```bash
curl -s -X POST https://portfoliointel.co.in/api/v1/parse \
  -H "X-API-Key: sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"pdf_ref":"sample_cams_2024"}'
```

`pdf_ref` is `sample_cams_2024` or `sample_kfintech_2024`. It is only accepted
on `portfoliointel.co.in`; the `api.` host answers it with `MISSING_PDF`. On
that sandbox host a test key can't upload a real file
(`SANDBOX_PDF_REF_REQUIRED`) — send real files to the `api.` host.

## Response

```json
{
  "success": true,
  "data": {
    "snapshot_id": "snap_…",
    "as_of_date": "2025-12-31",
    "statement_start_date": "2025-01-01",
    "statement_end_date": "2025-12-31",
    "source": "CAMS",
    "statement_type": "DETAILED",
    "file_name": "cas.pdf",
    "total_value": 1250000,
    "total_cost_value": 980000,
    "folio_count": 3,
    "investor_name": "REDACTED",
    "mutual_funds": [
      {
        "name": "Axis Bluechip Fund - Direct Growth",
        "isin": "INF846K01EW2",
        "folio": "…",
        "units": 500.123,
        "nav": 52.34,
        "value": 26174.44,
        "costValue": 20000,
        "transactions": [
          { "date": "10-Apr-2025", "type": "Purchase", "amount": 5000, "units": 97.6, "nav": 51.23, "balance": 500.123 }
        ]
      }
    ],
    "confidence": { "document": 0.95, "level": "HIGH" },
    "_parse_time_ms": 842,
    "_page_count": 6,
    "_credits_charged": 12
  }
}
```

- `snapshot_id` is the handle for [Snapshots](https://docs.portfoliointel.co.in/api-reference/snapshots),
  [Reports](https://docs.portfoliointel.co.in/api-reference/reports) and [Skills](https://docs.portfoliointel.co.in/skills). To call
  [Enrich](https://docs.portfoliointel.co.in/api-reference/enrich) directly, map each `mutual_funds[]` entry to
  an instrument (`value` becomes `currentValue`).
- For an NSDL e-CAS, every holding — mutual funds and demat holdings alike — is
  returned in `mutual_funds[]`.
- `confidence.level` is `HIGH`, `MEDIUM` or `LOW`, from the validation pass
  (field checks and units × NAV reconciliation).
- Transaction `type` is one of `Purchase`, `Redemption`, `Switch In`,
  `Switch Out`, `Dividend`, `SIP`, `Other`; dates keep the statement's
  `DD-Mon-YYYY` form.

## Credits

A parse costs **10 credits** for up to 5 pages, plus **2 credits for each
further block of 5 pages**: a 6-page statement costs 12, a 12-page one 14.
Credits are checked before parsing — a request that would overdraw returns
`402` without spending anything.

## Limits

| Limit | Value | Error |
| --- | --- | --- |
| File size | 10 MB | `413 FILE_TOO_LARGE` |
| Pages | 150 | `413 TOO_MANY_PAGES` |
| Time to open and parse | 45 seconds | `422 PARSE_TIMEOUT` |

Real CAS statements are well inside these. They exist so a small, crafted PDF
can't consume minutes of CPU.

## Errors

Errors are `{ "success": false, "error": { "code", "message" } }`.

| Status | Code | Meaning | Retry? |
| --- | --- | --- | --- |
| `400` | `MISSING_FILE`, `MISSING_PDF` | No PDF in the request (multipart / JSON), including `pdf_ref` sent to the `api.` host | Fix the request |
| `400` | `INVALID_REQUEST` | More than one of `file`, `pdf_base64`, `pdf_url` | Fix the request |
| `400` | `INVALID_FILE`, `INVALID_PDF_URL` | Not a PDF, or the URL couldn't be fetched | No |
| `400` | `PASSWORD_REQUIRED` | Encrypted and no, or the wrong, `password` | With the password |
| `401` | `UNAUTHORIZED` | Missing or invalid key | No |
| `402` | `INSUFFICIENT_CREDITS` | `data.required` and `data.remaining` say by how much | After topping up |
| `413` | `FILE_TOO_LARGE`, `TOO_MANY_PAGES` | See [Limits](#limits) | No |
| `422` | `PARSE_TIMEOUT` | The document took too long to read | No |
| `429` | `RATE_LIMITED` | Honour `Retry-After` | Yes |
| `503` | `SERVER_BUSY` | All parser workers busy | Yes, shortly |
| `500` | `PARSE_ERROR`, `INTERNAL_ERROR` | Unexpected failure | Once; then report the `X-Request-ID` |

> **Tip: Doesn't need to leave the device?**
>
> The same parser runs [in the browser and as a CLI](https://docs.portfoliointel.co.in/local/overview) with no
> upload at all.

## Next steps

- [Enrich](https://docs.portfoliointel.co.in/api-reference/enrich)
- [Reports](https://docs.portfoliointel.co.in/api-reference/reports)

Source: https://docs.portfoliointel.co.in/api-reference/parse/
