> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mf-atlas.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Investor Holdings

> Read folio-level holdings by investor or by PAN, as reported daily by the registrars (CAMS and KFintech).

**Holdings** are the folios and units a customer currently owns, as reported by
the registrars — **CAMS** and **KFintech**. They are refreshed **once a day**
from the registrars' own reports, so they are a daily snapshot, not a live
portfolio. They are *not* derived from the orders you placed through this API:
they cover every folio under your distributor code, including customers you have
not onboarded here yet.

There are two ways to read them:

* **By investor** — `GET /api/investors/v1/{investor_id}/holdings`, for a customer
  you have registered.
* **By PAN** — `POST /api/holdings/v1/lookup`, for any customer, onboarded or not.

## By investor

```http theme={null}
GET /api/investors/v1/{investor_id}/holdings
Authorization: Bearer <token>
```

Response `200`:

```json theme={null}
{
  "success": true,
  "data": {
    "investor_id": "I_SI_IND_000042",
    "holdings": [
      {
        "source": "KFIN",
        "folio_no": "91014085595",
        "amc_code": "116",
        "amc_name": "Bankofindiamutualfund Mf",
        "scheme_code": "BAMPRG-GR",
        "isin": "INF761K01FI9",
        "rta_code": "MPRGG",
        "fund_name": "BANK OF INDIA FLEXI CAP FUND - REGULAR PLAN - GROWTH",
        "units": 1049.386,
        "nav": 38.34,
        "market_value": 40233.46,
        "as_of": "2026-10-06"
      },
      {
        "source": "CAMS",
        "folio_no": "11449736/44",
        "amc_code": "D",
        "amc_name": "Dsp Mf",
        "fund_name": "DSP NIFTY 500 INDEX FUND - REGULAR - GROWTH",
        "isin": "INF740KA1XV5",
        "rta_code": "2047",
        "units": 2136.777,
        "nav": 9.2217,
        "market_value": 19705.14,
        "as_of": "2026-10-06"
      }
    ],
    "summary": {
      "total_market_value": 59938.6,
      "sources": [
        { "source": "CAMS", "as_of": "2026-10-06" },
        { "source": "KFIN", "as_of": "2026-10-06" }
      ]
    }
  }
}
```

## By PAN

Use this for an existing customer who isn't an investor on the platform yet. The
PAN goes in the request **body** (never the URL, so it stays out of logs and
proxies) and comes back **masked**.

```http theme={null}
POST /api/holdings/v1/lookup
Authorization: Bearer <token>
Content-Type: application/json
```

```json theme={null}
{ "pan": "ABCDE1234F" }
```

Response `200` — the same positions and `summary` as above, with `pan` in place of
`investor_id`:

```json theme={null}
{
  "success": true,
  "data": {
    "pan": "AB******4F",
    "holdings": [ { "source": "CAMS", "folio_no": "11449736/44", "amc_code": "D", "amc_name": "Dsp Mf", "fund_name": "DSP NIFTY 500 INDEX FUND - REGULAR - GROWTH", "isin": "INF740KA1XV5", "rta_code": "2047", "units": 2136.777, "nav": 9.2217, "market_value": 19705.14, "as_of": "2026-10-06" } ],
    "summary": { "total_market_value": 19705.14, "sources": [ { "source": "CAMS", "as_of": "2026-10-06" } ] }
  }
}
```

Nothing reported for the PAN returns `200` with `"holdings": []`.

## Fields

| Field | Notes |
| - | - |
| `source` | Registrar that reported the position: `CAMS` or `KFIN`. |
| `folio_no` | Folio number as printed by the registrar. CAMS folios may carry a `/NN` check suffix. |
| `amc_code` | The registrar's own AMC code. |
| `amc_name` | AMC name, mapped from the registrar's AMC code. May be empty when the AMC could not be mapped. |
| `scheme_code` | **NSE scheme code** — the one to use with the schemes and orders APIs. When a product has several order-tier listings (`-L0`/`-L1`), the **base scheme without a tier suffix** is used. **Empty when the product spans several variants** of the fund (growth vs IDCW payout vs IDCW reinvest, different IDCW frequencies) or matched nothing (see below). |
| `isin` | Scheme ISIN — from the scheme master when every matching scheme agrees on it, else from the registrar report (KFintech only). May be empty. |
| `rta_code` | The registrar's scheme code — from the scheme master when every matching scheme agrees, else the report's own product code. |
| `fund_name` | Scheme name — from the best-matching scheme of your account's plan (regular by default). **Not necessarily the exact plan/option** (see below). |
| `units` | Units held at the balance date. |
| `nav` | NAV as reported (`KFIN`); for `CAMS` it is derived as `market_value / units`. |
| `market_value` | Value of the position in INR at the balance date. |
| `as_of` | Balance date, `YYYY-MM-DD`. Always show this alongside the value. |
| `summary.total_market_value` | Sum of `market_value` across all positions. |
| `summary.sources[].as_of` | Latest balance date for each registrar that has data for this investor. |

## How positions are matched to the scheme and AMC masters

The registrars identify a position by their own codes, so each position is
matched to our masters when the data is loaded, letting you process holdings by
whichever identifier your system uses.

* A position is matched only to schemes of **your account's plan** — **regular**
  by default, or **direct** if your account is set up for direct plans (a scheme of
  the other plan never matches) — by **ISIN** first (KFintech reports carry one), then by the
  **registrar's product code**.
* A registrar product code usually corresponds to **several** scheme listings, for
  two different reasons:
  * **Order-tier duplicates** — the same scheme listed with and without an `-L0` /
    `-L1` order-tier suffix. The **base scheme (no tier suffix)** is used and, if
    several remain, the one with the **lowest minimum purchase**. Its NSE code is
    returned as `scheme_code`.
  * **Different variants of the fund** — growth, IDCW payout and IDCW reinvest
    options, and each IDCW frequency, each with its own ISIN. The registrar's
    product code does not say which one the investor holds, so `scheme_code` is
    **left empty** rather than guessing an option that could place an order on the
    wrong plan. Resolving the exact variant and ISIN is planned once transaction data
    is available.
* `fund_name` identifies the fund but **not necessarily the exact plan/option**, and
  in rare cases it can be a sibling fund of the same AMC that shares the code.
  `isin` / `rta_code` are filled only when **all** matching listings agree on them
  (tier duplicates do). **An empty `scheme_code` is normal**, not an error.
* `amc_name` is mapped from the registrar's `amc_code` via our AMC master. When
  nothing matches it is empty and `amc_code` is still returned.
* Matching is redone on every daily load, so positions improve as the masters do.

## Things to know

* **Daily refresh.** A new day's report replaces the previous one; a folio that
  disappears from the report (fully redeemed or transferred) disappears from the
  list.
* **Empty is normal.** `holdings` is `[]` until a registrar report covering the
  PAN has been processed — for a newly registered investor this can take a day or
  more. It is not an error.
* **Primary-holder folios only.** The registrar reports identify a folio by its
  primary holder's PAN. A joint folio therefore appears under the primary
  holder's PAN, never a secondary holder's, and investors registered with a joint
  holding type always return an empty list on the by-investor endpoint.
* **No cost or invested amount** — the registrar reports don't include it.
* **Not live.** Orders placed today won't show until the registrars report them.

## Errors

| Condition | Response |
| - | - |
| Investor not found in your account (by investor) | `404 NOT_FOUND` — "investor not found" |
| `pan` missing or not a valid 10-character PAN (by PAN) | `400 VALIDATION_FAILED` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.