> ## 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.

# Form Lookup Tables

> Dropdown values for the investor creation form — tax statuses, states, countries and every coded enum, served as option lists you can bind straight to a select input.

The [investor creation](/api-documentation/create-investor) request has a
number of fields the exchange validates against fixed lookup tables —
`tax_status`, `address.state`, `fatca.birth_country`, bank account types,
nominee relationships and more. Free text works for none of them: a value
outside the exchange's table either silently falls into a default bucket or
comes back as a rejection.

The masters endpoints here return those tables as option lists
(`{ "value", "label" }`) sized for UI dropdowns — `value` is exactly what
you send in the request, `label` is what you display.

<Note>
  These are served from static tables we keep in sync with the exchange's own
  masters — no exchange call, nothing to paginate. Fetch them once when your
  form loads and cache them.
</Note>

## Investor form options

```http theme={null}
GET /api/masters/v1/investor-options
Authorization: Bearer <token>
```

One call with every enum the creation form needs:

```json theme={null}
{
  "success": true,
  "data": {
    "holding_types": [
      { "value": "SINGLE", "label": "Sole holder" },
      { "value": "JOINT", "label": "Joint holders" },
      { "value": "ANYONE_OR_SURVIVOR", "label": "Anyone or survivor" }
    ],
    "tax_statuses": [
      { "value": "INDIVIDUAL", "label": "Resident Indian", "group": "RESIDENT" },
      { "value": "NRI_REPATRIABLE", "label": "NRE — repatriable", "group": "NRI" },
      { "value": "NRI_NON_REPATRIABLE", "label": "NRO — non-repatriable", "group": "NRI" }
    ],
    "genders": [ { "value": "M", "label": "Male" }, "…" ],
    "kyc_types": [ { "value": "KRA", "label": "KRA" }, "…" ],
    "occupations": [ { "value": "BUSINESS", "label": "Business" }, "…" ],
    "contact_relations": [ { "value": "SELF", "label": "Self" }, "…" ],
    "bank_account_types": [
      { "value": "SB", "label": "Saving bank (SB)" },
      { "value": "CB", "label": "Current bank (CB)" },
      { "value": "NE", "label": "NRE account (NE)" },
      { "value": "NO", "label": "NRO account (NO)" }
    ],
    "demat_modes": [
      { "value": "PHYSICAL", "label": "Physical (statement of account)" },
      { "value": "CDSL", "label": "CDSL demat" },
      { "value": "NSDL", "label": "NSDL demat" }
    ],
    "nominee_relationships": [ { "value": "SPOUSE", "label": "Spouse" }, "…" ],
    "guardian_relations": [
      { "value": "FATHER", "label": "Father" },
      { "value": "MOTHER", "label": "Mother" },
      { "value": "COURT_APPOINTED", "label": "Court-appointed legal guardian" }
    ],
    "wealth_sources": [ { "value": "SALARY", "label": "Salary" }, "…" ],
    "income_slabs": [
      { "value": "31", "label": "Below ₹1 lakh" },
      { "value": "32", "label": "₹1–5 lakh" },
      { "value": "33", "label": "₹5–10 lakh" },
      { "value": "34", "label": "₹10–25 lakh" },
      { "value": "35", "label": "₹25 lakh–1 crore" },
      { "value": "36", "label": "Above ₹1 crore" }
    ],
    "fatca_occupation_types": [ { "value": "SERVICE", "label": "Service" }, "…" ],
    "pep_options": [
      { "value": "NO", "label": "No" },
      { "value": "YES", "label": "Yes — politically exposed person" },
      { "value": "RELATED", "label": "Related to a politically exposed person" }
    ]
  }
}
```

| Field                    | Feeds                                                |
| ------------------------ | ---------------------------------------------------- |
| `holding_types`          | `holding_type`                                       |
| `tax_statuses`           | `tax_status` — grouped, see the cascade below        |
| `genders`                | `primary_holder.gender`                              |
| `kyc_types`              | `primary_holder.kyc_type`                            |
| `occupations`            | `primary_holder.occupation`                          |
| `contact_relations`      | `contact.email_relation` / `contact.mobile_relation` |
| `bank_account_types`     | `bank_accounts[].account_type`                       |
| `demat_modes`            | `demat.mode`                                         |
| `nominee_relationships`  | `nominees[].relationship`                            |
| `guardian_relations`     | `nominees[].guardian.relation`                       |
| `wealth_sources`         | `fatca.source_of_wealth`                             |
| `income_slabs`           | `fatca.income_slab`                                  |
| `fatca_occupation_types` | `fatca.occupation_type`                              |
| `pep_options`            | `fatca.pep`                                          |

`tax_statuses` today covers the three statuses the creation form supports —
Resident Individual and the two NRI variants. The request enum also accepts
`MINOR`, `HUF`, `COMPANY` and `TRUST`, but those need guardian/entity fields
we don't catalog here yet; they'll be added to this endpoint when the form
scope grows.

### The resident / NRI cascade

`tax_statuses` carries a `group` so you can render the same two-step pick
most onboarding forms use:

1. **Investor type** — `RESIDENT` or `NRI`.
2. **Account variant** — enabled only for `NRI`, listing that group's
   options: NRE (`NRI_REPATRIABLE`) or NRO (`NRI_NON_REPATRIABLE`).

The two NRI variants take exactly the same field set as a resident — they
differ only in the `tax_status` sent and the bank account the exchange
requires: an NRE investor must include at least one `NE` account, an NRO
investor at least one `NO` account. Defaulting the first bank row's account
type to the variant's `NE`/`NO` when the user picks NRE/NRO saves the most
common validation failure.

## States

```http theme={null}
GET /api/masters/v1/states
```

```json theme={null}
{
  "success": true,
  "data": [
    { "value": "Maharashtra", "label": "Maharashtra" },
    { "value": "Delhi", "label": "Delhi" },
    { "value": "Puducherry", "label": "Puducherry" }
  ]
}
```

`value` is the exact string `address.state` accepts — the same list as the
[valid state values table](/api-documentation/create-investor#valid-state-values),
so you don't have to maintain it by hand.

<Warning>
  The exchange maps any state it doesn't recognize to its `OTHERS` bucket —
  **silently**, not with an error. Pin your state dropdown to these values
  rather than accepting free text.
</Warning>

## Countries

```http theme={null}
GET /api/masters/v1/countries
```

The exchange's FATCA Country Code master — 252 entries, `value` being the
ISO 3166-1 alpha-2 code the FATCA fields take:

```json theme={null}
{
  "success": true,
  "data": [
    { "value": "AD", "label": "ANDORRA" },
    { "value": "AE", "label": "UNITED ARAB EMIRATES" },
    { "value": "IN", "label": "INDIA" }
  ]
}
```

Feeds `fatca.birth_country` and `fatca.tax_residency`.

<Note>
  `address.country` is **not** a dropdown from this table — the domestic
  address block is always registered as India regardless of what you send, so
  hard-code it. This table is for the FATCA fields only.
</Note>