# Mutual Fund — Fund API (frontend integration)

Use this file to build the Fund list, dropdown, create, edit, and delete screens.

**Base URL:** `{APP_URL}/api`  
**Example:** `http://127.0.0.1:8000/api`  
**Controller:** `MfFundController`  
**Update method:** `POST` (not PUT)  
**Auth:** these MF routes currently use only the `api` middleware (no JWT). Send `Accept: application/json`. Pass `users_id` on create/update when a back-office user is logged in.

---

## Response envelope

Every JSON body looks like this:

```json
{
  "status": true,
  "message": "optional text",
  "data": {},
  "pagination": {},
  "errors": {},
  "error": "server error text"
}
```

| HTTP | When |
|------|------|
| 200 | List, show, dropdown, update, delete |
| 201 | Create |
| 404 | Empty list (`No funds found`) or unknown id |
| 409 | Delete blocked because related rows exist |
| 422 | Validation failed — read `errors.{field}[]` |
| 500 | Unexpected server error |

Treat `status === false` as failure even if HTTP is 200.

---

## Screens and endpoints

| Screen | Method | Path |
|--------|--------|------|
| List | GET | `/mf-fund/mf-fund-index` |
| Dropdown (selects) | GET | `/mf-fund/mf-fund-dropdown` |
| Detail / edit load | GET | `/mf-fund/mf-fund-show/{id}` |
| Create | POST | `/mf-fund/mf-fund-store` |
| Update | POST | `/mf-fund/mf-fund-update/{id}` |
| Delete | DELETE | `/mf-fund/mf-fund-delete/{id}` |

---

## List screen

`GET /mf-fund/mf-fund-index`

### Query

| Param | Type | Default | UI |
|-------|------|---------|----|
| `per_page` | 1–100 | 10 | Page size |
| `amc_id` | int | — | Filter select from AMC dropdown |
| `fund_category_id` | int | — | Filter select from category dropdown |
| `risk_profile_id` | int | — | Filter select from risk-profile dropdown |
| `status` | `A` / `I` | — | Active / Inactive |
| `is_transactional` | `0` / `1` | — | Display / Partner |
| `q` | string ≤ 255 | — | Search box (name or slug) |

### Success

```json
{
  "status": true,
  "data": [ { "...fund object..." } ],
  "pagination": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 10,
    "total": 27
  }
}
```

Sort is `fund_name` ascending. Bind pagination to `pagination.*`.

Suggested table columns: **Name**, **Slug**, **AMC** (`amc.name`), **Category** (`fund_category.category_name`), **Risk** (`risk_profile.risk_tag_name`), **Transactional**, **Status**, **Latest NAV date**.

---

## Dropdown (other forms)

`GET /mf-fund/mf-fund-dropdown`

Use this on NAV, dividend, holdings, sector allocation, and selling-agent screens.

| Param | Default | Notes |
|-------|---------|--------|
| `status` | `A` | `A`, `I`, or `all` |
| `amc_id` | — | Optional |
| `fund_category_id` | — | Optional |
| `risk_profile_id` | — | Optional |
| `is_transactional` | — | `0` or `1` |

Each row:

```json
{
  "id": 1,
  "fund_name": "Ekush First Unit Fund",
  "slug": "EFUF",
  "amc_id": 1,
  "fund_category_id": 1,
  "risk_profile_id": 1,
  "is_transactional": "1",
  "status": "A"
}
```

Select **label:** `{fund_name} ({slug})`  
Select **value:** `id`

---

## Create / edit form

Load mapping dropdowns first:

| Field | Dropdown API |
|-------|----------------|
| `amc_id` | `GET /mf-amc/mf-amc-dropdown` |
| `fund_category_id` | `GET /mf-fund-category/mf-fund-category-dropdown` |
| `risk_profile_id` | `GET /mf-risk-profile/mf-risk-profile-dropdown` |

Then `GET /mf-fund/mf-fund-show/{id}` to fill the edit form.

Content-Type: `application/json`.  
Always send **`users_id`** (logged-in `fintra_back_users.user_id`).

### Form sections (match these groups in the UI)

#### Identity — required

| Field | Type | Rules | UI |
|-------|------|-------|----|
| `fund_name` | string ≤ 255 | **required** | Text |
| `slug` | string ≤ 255 | Unique ticker. Omit to auto-generate from name | Text, optional |
| `fund_url` | string ≤ 255 | optional | URL |
| `status` | `A` / `I` | default `A` | Toggle / select |

#### Mapping — required (selects)

| Field | Type | Rules | UI |
|-------|------|-------|----|
| `amc_id` | int | **required**, must exist | AMC dropdown |
| `fund_category_id` | int | **required**, must exist | Category dropdown |
| `risk_profile_id` | int | **required**, must exist | Risk-profile dropdown |

#### Classification

| Field | Type | Rules | UI |
|-------|------|-------|----|
| `fund_type` | string ≤ 255 | optional | Text |
| `nature` | string ≤ 255 | optional | Text |
| `sponsor` | string ≤ 255 | optional | Text |
| `currency` | string ≤ 10 | default `BDT` | Text |
| `is_transactional` | `0` / `1` | **required** | Select: `0` Display, `1` Partner |
| `fund_start_date` | date `YYYY-MM-DD` | **required** | Date picker |

#### Structure and parties

| Field | Type | UI |
|-------|------|----|
| `life_size_of_fund` | string ≤ 255 | Text |
| `initial_size_of_fund` | string ≤ 255 | Text |
| `face_value_per_unit` | string ≤ 255 | Text (usually `10`) |
| `trustee` | string ≤ 255 | Text |
| `custodian` | string ≤ 255 | Text |
| `life_and_size` | string ≤ 255 | Text |

All optional.

#### Investment profile

| Field | Type | UI |
|-------|------|----|
| `investment_universe` | string ≤ 255 | Text |
| `objective` | string ≤ 255 | Text |
| `overview` | text | Textarea |
| `investment_strategy` | text | Textarea |
| `suitable_for` | text | Textarea |
| `dividend` | string ≤ 255 | Text |
| `transferibility` | string ≤ 255 | Text |
| `surrender_encashment` | text | Textarea |
| `tax_benefit` | text | Textarea |
| `expense_ratio` | number 0–9999.99 | Number |

All optional.

#### Transaction amounts

| Field | Type | Default | UI |
|-------|------|---------|----|
| `min_sip_amount` | number ≥ 0 | `1000` | Number |
| `min_lumpsum_amount` | number ≥ 0 | `5000` | Number |
| `min_institution_amount` | number ≥ 0 | `50000` | Number |

#### NAV and returns (optional on create)

These can be sent, but after NAV/dividend entry the return-series job overwrites `current_nav`, `composite_nav`, `inception_return`, `cagr`, `series_basis`, `series_start_date`, `latest_nav_date`. Prefer **read-only** on the fund form after launch.

| Field | Type | Rules |
|-------|------|--------|
| `current_nav` | number ≥ 0 | optional |
| `current_buy_price` | number ≥ 0 | optional |
| `current_sell_price` | number ≥ 0 | optional |
| `composite_nav` | number ≥ 0 | optional |
| `inception_return` | number | optional |
| `cagr` | number | optional; null if fund age &lt; 1 year |
| `series_basis` | `COMPOSITE` / `HYBRID` / `DIVIDENDS` / `NAV` | optional |
| `series_start_date` | date | optional |
| `latest_nav_date` | date | optional |

#### AUM and allocation (optional)

| Field | Type | Rules |
|-------|------|--------|
| `fund_size_bdt` | number ≥ 0 | AUM |
| `fund_size_text` | string ≤ 255 | Display text |
| `fund_size_as_of` | date | |
| `market_value_of_grand_total_of_capital_market_securities` | number ≥ 0 | |
| `bank_term_deposits_investment_value` | number ≥ 0 | |
| `total_cash_at_bank` | number ≥ 0 | |
| `equity_percentage` | number 0–100 | |
| `debt_percentage` | number 0–100 | |
| `cash_percentage` | number 0–100 | |

#### Portfolio files (optional)

| Field | Type | UI |
|-------|------|----|
| `portfolio_pdf_url_net` | string ≤ 512 | URL |
| `portfolio_pdf_url_local` | string ≤ 512 | URL |
| `portfolio_date` | date | Date picker |

#### Audit (do not send as form fields)

Returned on list/show only: `create_by`, `update_by`, `create_at`, `update_at`, `created_by`, `updated_by`.  
Send `users_id` instead.

---

## Create / update payload example

`POST /mf-fund/mf-fund-store`  
`POST /mf-fund/mf-fund-update/{id}`

```json
{
  "amc_id": 1,
  "fund_category_id": 1,
  "risk_profile_id": 1,
  "fund_name": "Ekush First Unit Fund",
  "slug": "EFUF",
  "fund_url": "https://example.com/efuf",
  "is_transactional": "1",
  "fund_start_date": "2020-03-18",
  "status": "A",
  "currency": "BDT",
  "face_value_per_unit": "10",
  "min_sip_amount": 1000,
  "min_lumpsum_amount": 5000,
  "min_institution_amount": 50000,
  "users_id": 1
}
```

Omit unused optional keys (they store as `null`). Do not send empty strings for numeric/date fields — omit them or send `null`.

`is_transactional` is a **string** `"0"` or `"1"`, not a boolean.

---

## Fund object (list / show)

Nested mapping objects are included so the UI does not need extra calls for labels.

```json
{
  "id": 1,
  "fund_name": "Ekush First Unit Fund",
  "slug": "EFUF",
  "status": "A",
  "amc_id": 1,
  "fund_category_id": 1,
  "risk_profile_id": 1,
  "amc": {
    "id": 1,
    "name": "Ekush Wealth Management Limited",
    "slug": "ekush",
    "partner_code": "EKUSH",
    "status": "A"
  },
  "fund_category": {
    "id": 1,
    "category_name": "Equity",
    "short_code": "EQTY",
    "is_active": "A"
  },
  "risk_profile": {
    "id": 1,
    "risk_level": "High",
    "risk_tag_name": "Aggressive",
    "is_active": "A"
  },
  "created_by": { "user_id": 1, "name": "Admin" },
  "updated_by": null
}
```

Plus every column in the form sections above.

AMC icon (if you show a logo next to the fund):  
`GET /mf-amc/mf-amc-icon-view/{amc_id}` — use as `<img src>`. Do **not** use `/storage/...`.

---

## Delete

`DELETE /mf-fund/mf-fund-delete/{id}`

If the fund has child rows the API returns **409**:

```json
{
  "status": false,
  "message": "Cannot delete fund because it has related records",
  "related": {
    "settings": 0,
    "orders": 0,
    "sip_plans": 0,
    "nav_history": 12,
    "holdings": 0,
    "dividends": 2,
    "unit_adjustments": 0,
    "sector_allocations": 0,
    "exit_load_rules": 0
  }
}
```

Show the `related` counts. Offer **Inactivate** (`status: "I"` via update) instead of delete.

---

## Frontend checklist

1. List with filters + pagination. Empty list is **404** — show an empty state, not a crash.
2. Create/edit form in the field groups above. Required: mapping ids, `fund_name`, `is_transactional`, `fund_start_date`.
3. Load AMC / category / risk-profile dropdowns before the form.
4. Update is **POST** to `/mf-fund/mf-fund-update/{id}`.
5. Keep NAV/return fields read-only after NAVs exist; they are rebuilt by the return-series service.
6. On 422, map `errors` onto the matching inputs.
7. On 409 delete, switch to inactivate.

Related: `MF_Fund.md`, `MF_Return_Series.md`, `curl/mutual_fund_api_curl.md`.
