# Enrich

> POST /api/enrich — add fund returns, benchmarks, and allocation to parsed holdings.

Enrich a list of parsed holdings with 1Y/3Y/5Y fund returns from MFAPI, benchmark returns, AMC exposure, and asset allocation.

The endpoint takes the holdings themselves, not a `snapshot_id`. From a [Parse](https://docs.portfoliointel.co.in/api-reference/parse) response, map each `mutual_funds[]` entry to an instrument and rename `value` to `currentValue`. To enrich a stored snapshot by ID, run a [skill](https://docs.portfoliointel.co.in/skills) with `include_enrichment: true` (REST or the MCP `run_skill` tool). The MCP [`enrich` tool](https://docs.portfoliointel.co.in/mcp/tools) also takes a holdings array.

## Endpoint

`POST https://api.portfoliointel.co.in/api/enrich`

## Authentication

None. This is the endpoint the Portfolio Intel web and mobile apps call after parsing a statement on the device. Requests are rate-limited per client IP (30 per minute by default).

## Request body

| Field | Type | Required | Notes |
|---|---|---|---|
| `instruments` | object[] | yes | Holdings to enrich. At most 500. |
| `statementDate` | string | yes | Statement end date, `YYYY-MM-DD`. Returns and benchmarks are measured to this date. |
| `statementStartDate` | string | no | Statement start date, `YYYY-MM-DD`. Lets returns value units held before the period. |
| `statementType` | string | no | `SUMMARY` or `DETAILED`. |
| `folioCount` | number | yes | Number of folios on the statement. Echoed in the response. |
| `totalValue` | number | yes | Portfolio value. Used as the denominator for AMC exposure percentages. |
| `investorName` | string | no | Echoed in the response. Defaults to `Investor`. |
| `assetClassComposition` | object[] | no | NSDL e-CAS composition table. When present, it replaces the category-based asset allocation. |
| `valueTrend`, `dematAccounts` | object[] | no | NSDL e-CAS metadata, passed through unchanged. |

Each entry in `instruments`:

| Field | Type | Required | Notes |
|---|---|---|---|
| `name` | string | yes | Scheme name as printed on the statement. |
| `folio` | string | yes | Removed from the response. |
| `isin` | string | no | Improves scheme matching. Without it the name is matched against MFAPI. |
| `units` | number | yes | |
| `nav` | number | yes | |
| `currentValue` | number | yes | |
| `amc`, `category` | string | no | A `category` from the statement is kept; otherwise it is inferred. |
| `assetClass`, `productType`, … | — | no | NSDL multi-asset fields. Non-mutual-fund holdings are returned without returns or benchmarks. |

## Example

**cURL**

```bash
curl -X POST https://api.portfoliointel.co.in/api/enrich \
  -H "Content-Type: application/json" \
  -d '{
    "instruments": [{
      "name": "Axis Bluechip Fund - Direct Growth",
      "folio": "12345678",
      "isin": "INF846K01EW2",
      "units": 500.123,
      "nav": 52.34,
      "currentValue": 26174.44
    }],
    "statementDate": "2024-12-31",
    "folioCount": 1,
    "totalValue": 26174.44
  }'
```

**Node**

```ts
const res = await fetch('https://api.portfoliointel.co.in/api/enrich', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    instruments: [{
      name: 'Axis Bluechip Fund - Direct Growth',
      folio: '12345678',
      isin: 'INF846K01EW2',
      units: 500.123,
      nav: 52.34,
      currentValue: 26174.44,
    }],
    statementDate: '2024-12-31',
    folioCount: 1,
    totalValue: 26174.44,
  }),
});
const portfolio = await res.json();
```

**Python**

```python
r = requests.post(
    'https://api.portfoliointel.co.in/api/enrich',
    json={
        'instruments': [{
            'name': 'Axis Bluechip Fund - Direct Growth',
            'folio': '12345678',
            'isin': 'INF846K01EW2',
            'units': 500.123,
            'nav': 52.34,
            'currentValue': 26174.44,
        }],
        'statementDate': '2024-12-31',
        'folioCount': 1,
        'totalValue': 26174.44,
    },
)
```

## Response

The body is the enriched portfolio. It is not wrapped in `{ success, data }`.

```json
{
  "investorName": "Investor",
  "statementDate": "2024-12-31",
  "folioCount": 1,
  "totalValue": 26174.44,
  "instruments": [
    {
      "name": "Axis Bluechip Fund - Direct Growth",
      "isin": "INF846K01EW2",
      "units": 500.123,
      "nav": 52.34,
      "currentValue": 26174.44,
      "amc": "Axis Mutual Fund",
      "category": "Equity Scheme - Large Cap Fund",
      "returns": { "oneYear": 12.4, "threeYear": 10.1, "fiveYear": 14.8 },
      "oneYearReturn": 12.4,
      "benchmarkName": "Nifty 100 TRI",
      "benchmarkReturns": { "oneYear": 11.2, "threeYear": 11.9, "fiveYear": 15.3 },
      "benchmarkReturn": 11.2
    }
  ],
  "amcExposure": [{ "name": "Axis Mutual Fund", "value": 26174.44, "percentage": 100 }],
  "assetAllocation": [{ "name": "Equity", "value": 26174.44 }],
  "metadata": { "source": "Client-Side Parser", "extractionMethod": "Deterministic", "timestamp": "2025-01-02T10:00:00.000Z" }
}
```

- Returns are percentages. A field is absent when MFAPI has no data for that period or the holding is not a mutual fund.
- Fields prefixed with `_` (for example `_categorySource`) are diagnostics and may change without notice.

## Errors

| Status | Code | Cause |
|---|---|---|
| 400 | `INVALID_INPUT` | `instruments` is missing or not an array. |
| 413 | `TOO_MANY_INSTRUMENTS` | More than 500 instruments in one request. Split the list across requests. |
| 429 | `RATE_LIMITED` | Too many requests from this IP. |
| 500 | `INTERNAL_ERROR` | Enrichment failed. |

Error bodies have the shape `{ "success": false, "error": { "code": "...", "message": "..." } }`.

> **Note**
>
> Enrichment calls MFAPI for each mutual fund. Allow 2–5s for portfolios with many funds.

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