Create an Investor - Anvitra Atlas

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

POST /api/investors/v1/
Authorization: Bearer <token>
Content-Type: application/json

Returns 201 with dto.InvestorData.

Example — resident individual, single holder

{
  "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": "[email protected]",
    "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:

{
  "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_<holding>_<tax status>_<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.

Example — NRI single holder (NRE / NRO)

Same shape, with two differences:

tax_status is NRI_REPATRIABLE (NRE) or NRI_NON_REPATRIABLE (NRO).
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”).

{
  "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": "[email protected]", "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:

{
  "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 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.

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.

​Scope of this guide

​Endpoint

​Example — resident individual, single holder

​Example — NRI single holder (NRE / NRO)

​Field reference

​Top level

​primary_holder

​contact

​address

​demat

​bank_accounts[]

​nominees[]

​fatca (optional but recommended)

​euin (optional)

​Validation

​Registration lifecycle

​Track progress

​Retry after a rejection

​Related endpoints

Scope of this guide

Endpoint

Example — resident individual, single holder

Example — NRI single holder (NRE / NRO)

Field reference

Top level

`primary_holder`

`contact`

`address`

`demat`

`bank_accounts[]`

`nominees[]`

`fatca` (optional but recommended)

`euin` (optional)

Validation

Registration lifecycle

Track progress

Retry after a rejection

Related endpoints