> ## 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. # Create an Investor > Register an investor asynchronously across the exchange and other enabled backends, then poll or listen for the registered status. An **investor** is the person (or entity) who owns the mutual fund holdings. Creating one registers a Unique Client Code (UCC) with the exchange and any other backend providers enabled for your account. Investor creation is **asynchronous**. `POST` returns `201` immediately with `status: PENDING`; registration with the exchange happens in the background. An investor must reach `status: REGISTERED` before you can place an order for them. ## Scope of this guide This guide covers the two most common holding / tax-status combinations: | Combination | `holding_type` | `tax_status` | | ------------------------------------------ | -------------- | --------------------- | | Resident individual, single holder | `SINGLE` | `INDIVIDUAL` | | NRI (NRE — repatriable), single holder | `SINGLE` | `NRI_REPATRIABLE` | | NRI (NRO — non-repatriable), single holder | `SINGLE` | `NRI_NON_REPATRIABLE` | Joint / anyone-or-survivor holding and the other tax statuses (`MINOR`, `HUF`, `COMPANY`, `TRUST`) are planned and will be documented later. ## Endpoint ```http theme={null} POST /api/investors/v1/ Authorization: Bearer Content-Type: application/json ``` Returns `201` with `dto.InvestorData`. ## Example — resident individual, single holder ```json theme={null} { "holding_type": "SINGLE", "tax_status": "INDIVIDUAL", "primary_holder": { "name": "Hiren Ahir", "pan": "ABCDE1234F", "dob": "1990-04-12", "kyc_type": "KRA", "gender": "M", "occupation": "SERVICE", "relationship": "SELF" }, "contact": { "email": "hiren@example.com", "email_relation": "SELF", "mobile": "9876543210", "mobile_relation": "SELF" }, "address": { "line1": "12 Exchange Plaza", "line2": "BKC", "city": "Mumbai", "state": "Maharashtra", "pincode": "400051", "country": "India" }, "nominees": [ { "name": "A Ahir", "relationship": "SPOUSE", "percentage": 100, "dob": "1992-01-01" } ], "bank_accounts": [ { "account_no": "311242065229", "ifsc": "KKBK0000872", "account_type": "SB", "is_default": true } ], "demat": { "mode": "CDSL", "dp_id": "12345678", "client_id": "87654321" }, "client_ref": "crm-9931" } ``` Response: ```json theme={null} { "success": true, "data": { "id": "I_SI_IND_000042", "providers": [ { "type": "NSE", "client_code": "H30350", "status": "ACTIVE" } ], "status": "PENDING", "provider": "NSE", "client_ref": "crm-9931", "created_at": "2026-09-06T10:04:11Z" } } ``` The `id` is a short, human-quotable code — `I___<6-digit sequence>` (`I_SI_IND_000042`) — minted for your account. It is the primary key, the foreign key every child resource (investment account, mandate, order, payment) references, and it never changes even if the tax status is later amended. See [friendly ID conventions](/investment-accounts#friendly-id-conventions). ## Example — NRI single holder (NRE / NRO) Same shape, with two differences: 1. `tax_status` is `NRI_REPATRIABLE` (NRE) or `NRI_NON_REPATRIABLE` (NRO). 2. At least one bank account must have `account_type` of `NE` (NRE) or `NO` (NRO) — otherwise the request is rejected with `VALIDATION_FAILED` ("NRI investors require an NRE (NE) or NRO (NO) account"). ```json theme={null} { "holding_type": "SINGLE", "tax_status": "NRI_REPATRIABLE", "primary_holder": { "name": "Priya Nair", "pan": "AAAPN5678Q", "dob": "1988-07-22", "kyc_type": "KRA", "gender": "F", "occupation": "SERVICE", "relationship": "SELF" }, "contact": { "email": "priya@example.com", "email_relation": "SELF", "mobile": "9812345678", "mobile_relation": "SELF" }, "address": { "line1": "Flat 4B, Marine Drive", "city": "Mumbai", "state": "Maharashtra", "pincode": "400020", "country": "India" }, "nominees": [ { "name": "R Nair", "relationship": "FATHER", "percentage": 100, "dob": "1955-03-01" } ], "bank_accounts": [ { "account_no": "50100812345678", "ifsc": "HDFC0000123", "account_type": "NE", "is_default": true } ], "demat": { "mode": "PHYSICAL" }, "client_ref": "crm-9932" } ``` `address` is the mandatory **domestic Indian** address and `country` is always sent to the exchange as India. A separate overseas address for NRIs isn't exposed yet. ## Field reference ### Top level | Field | Required | Format / values | Notes | | ---------------- | -------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- | | `holding_type` | yes | `SINGLE` \| `JOINT` \| `ANYONE_OR_SURVIVOR` | Only `SINGLE` is covered here. For `SINGLE`, `joint_holders` must be empty. | | `tax_status` | yes | `INDIVIDUAL` \| `NRI_REPATRIABLE` \| `NRI_NON_REPATRIABLE` \| `MINOR` \| `HUF` \| `COMPANY` \| `TRUST` | Only the first three are covered here. | | `primary_holder` | yes | object | See below. | | `joint_holders` | no | array | Must be empty for `SINGLE`. | | `contact` | yes | object | Primary email + mobile. | | `address` | yes | object | Domestic Indian address. | | `nominees` | no | array | If present, `percentage` values must sum to exactly 100. | | `bank_accounts` | no\* | array | \*Required for NRI: one entry must be `NE` or `NO`. | | `demat` | yes | object | Holding mode. | | `fatca` | no | object | Recommended; submitted right after UCC registration. | | `euin` | no | object | EUIN declaration. | | `client_ref` | no | string | Your own reference; echoed back everywhere. | ### `primary_holder` | Field | Required | Format / values | Notes | | -------------- | ----------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | `name` | yes | full name | Split into first / middle / last for the exchange. | | `pan` | yes | 10-character PAN | Encrypted at rest; always masked on read. | | `dob` | yes | `YYYY-MM-DD` | | | `kyc_type` | yes | `KRA` \| `CKYC` \| `EKYC` | | | `gender` | yes | `M` \| `F` \| `O` | Required for individuals and minors. | | `occupation` | recommended | `BUSINESS` \| `SERVICE` \| `PROFESSIONAL` \| `AGRICULTURE` \| `RETIRED` \| `HOUSEWIFE` \| `STUDENT` \| `OTHERS` | Anything unrecognised maps to `OTHERS`. | | `relationship` | yes | `SELF` | For the primary holder. | ### `contact` | Field | Required | Notes | | ----------------- | -------- | ------------------------------ | | `email` | yes | Primary email address. | | `email_relation` | yes | e.g. `SELF`. | | `mobile` | yes | 10-digit Indian mobile number. | | `mobile_relation` | yes | e.g. `SELF`. | ### `address` | Field | Required | Notes | | ---------------- | -------- | -------------------------------------------------------------------------------------------------------- | | `line1` | yes | | | `line2`, `line3` | no | | | `city` | yes | | | `state` | yes | Full Indian state / UT name, e.g. `Maharashtra`. Translated to the exchange's own state code internally. | | `pincode` | yes | | | `country` | yes | Always `India`. | ### `demat` | Field | Required | Values | Notes | | ----------- | ----------- | ------------------------------ | ----------------------------------------- | | `mode` | yes | `CDSL` \| `NSDL` \| `PHYSICAL` | | | `dp_id` | conditional | | Required when `mode` is `CDSL` or `NSDL`. | | `client_id` | conditional | | Required when `mode` is `CDSL` or `NSDL`. | ### `bank_accounts[]` | Field | Required | Values | Notes | | -------------- | -------- | ------------------------------------------------------------ | ------------------------------------------ | | `account_no` | yes | | Encrypted at rest; masked on read. | | `ifsc` | yes | | | | `account_type` | yes | `SB` (savings) \| `CB` (current) \| `NE` (NRE) \| `NO` (NRO) | NRIs must include an `NE` or `NO` account. | | `micr` | no | | | | `is_default` | yes | boolean | Exactly one account should be the default. | ### `nominees[]` | Field | Required | Notes | | -------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------- | | `name` | yes | | | `relationship` | yes | e.g. `SPOUSE`, `FATHER`, `MOTHER`, `SON`, `DAUGHTER`. Unrecognised values map to "others". | | `percentage` | yes | All nominees' percentages must sum to exactly 100. | | `dob` | conditional | Required when the nominee is a minor. | | `pan` | no | | | `guardian` | conditional | `{ name, pan, dob, relation }` — required for a minor nominee. `relation` is `FATHER` \| `MOTHER` \| `COURT_APPOINTED`. | ### `fatca` (optional but recommended) | Field | Values | | ------------------ | --------------------------------------------------------------------------------------------------------------------------- | | `birth_country` | ISO 3166-1 alpha-2, e.g. `IN` | | `birth_place` | free text | | `tax_residency` | ISO 3166-1 alpha-2 | | `tin` | tax identification number (optional) | | `source_of_wealth` | `SALARY` \| `BUSINESS_INCOME` \| `GIFT` \| `ANCESTRAL_PROPERTY` \| `RENTAL_INCOME` \| `PRIZE_MONEY` \| `ROYALTY` \| `OTHER` | | `income_slab` | `31` (under 1L) \| `32` (1–5L) \| `33` (5–10L) \| `34` (10–25L) \| `35` (25L–1Cr) \| `36` (over 1Cr) | | `occupation_type` | `BUSINESS` \| `SERVICE` \| `PROFESSIONAL` \| `AGRICULTURE` \| `RETIRED` \| `HOUSEWIFE` \| `STUDENT` \| `OTHERS` | | `pep` | `YES` \| `NO` \| `RELATED` (politically exposed person) | ### `euin` (optional) `{ "declaration": true, "euin": "E123456" }` — the Employee Unique Identification Number of the advising employee. ## Validation Rejected synchronously with `400 VALIDATION_FAILED` and a `details[]` array: * `primary_holder.name`, `primary_holder.dob`, `contact.email`, `contact.mobile`, `address.city`, `address.pincode` — required. * `holding_type` must be one of the three enum values. * `SINGLE` holding ⇒ `joint_holders` must be empty. * `demat.mode` `CDSL`/`NSDL` ⇒ `dp_id` and `client_id` required. * `nominees` present ⇒ `percentage` sums to 100; a nominee with a `guardian` but no `dob` is rejected. * NRI tax status ⇒ at least one `NE`/`NO` bank account. ## Registration lifecycle ``` PENDING ──▶ PROCESSING ──▶ REGISTERED └──▶ REJECTED ``` * **PENDING** — persisted locally, queued for the exchange. * **PROCESSING** — the exchange call is in flight. * **REGISTERED** — UCC registered. FATCA (if supplied) is submitted right after; a FATCA failure is recorded in `provider_steps` but does not block `REGISTERED`. * **REJECTED** — terminal and persisted (not discarded). The exchange's reason is in `provider_remark`, with a full attempt history in `provider_steps`. ### Track progress **Poll** `GET /api/investors/v1/:id`: ```json theme={null} { "success": true, "data": { "id": "I_SI_IND_000042", "status": "REGISTERED", "providers": [ { "type": "NSE", "client_code": "H30350", "status": "ACTIVE" } ], "provider_steps": [ { "step": "UCC", "status": "SUCCESS", "at": "2026-09-06T10:05:02Z" }, { "step": "FATCA", "status": "SUCCESS", "at": "2026-09-06T10:05:04Z" } ], "primary_holder": { "pan": "AB******4F", "...": "..." }, "created_at": "2026-09-06T10:04:11Z", "updated_at": "2026-09-06T10:05:04Z" } } ``` `GET` always returns PII **masked**. See [PII masking](/pii-masking) for how to reveal a single field. **Or listen** for webhook events `investor.registered` / `investor.rejected`. ### Retry after a rejection `PATCH /api/investors/v1/:id` with the corrected fields (same schema). While the investor is not yet `REGISTERED`, `PATCH` updates the stored draft and re-queues it. Once `REGISTERED`, `PATCH` performs a synchronous UCC modification instead. ## Related endpoints | Method + path | Purpose | | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | `GET /api/investors/v1/:id` | Full investor (PII masked). | | `GET /api/investors/v1?status=&pan=&client_code=&client_ref=&limit=&cursor=` | List / search. | | `GET /api/investors/v1/:id/kyc-status` | KRA KYC status for the PAN. | | `POST /api/investors/v1/:id/ekyc` | Body `{ "amc_code": "AXF" }` → a verification URL to send the investor. | | `POST /api/investors/v1/:id/fatca` | Submit / resubmit a FATCA declaration. | | `POST /api/investors/v1/:id/bank-accounts` | Add a bank account → `{ "id": "bnk_...", "status": "ADDED" }`. | | `GET /api/investors/v1/:id/bank-accounts` | List bank accounts (numbers masked). | | `DELETE /api/investors/v1/:id/bank-accounts/:accountId` | Remove a bank account → `204`. | | `POST /api/investors/v1/:id/documents` | Multipart `type` + `file` (max 5 MB); `type` ∈ `AOF` \| `FATCA` \| `ELOG` \| `POA` \| `CHEQUE` \| `BANK_ELOG`. | | `GET /api/investors/v1/:id/documents` | List uploaded documents. |