Create an Investment Account

An investment account is a named bucket that groups an investor’s mutual fund products. Every order is filed under one; mandates and payments may reference one. It is a local grouping entity — creating it is synchronous and makes no exchange call.

Endpoint

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

{ "investor_id": "I_SI_IND_000042", "code": "RT", "name": "Retirement" }

Response 201:

{
  "success": true,
  "data": {
    "id": "A_RT_000001",
    "investor_id": "I_SI_IND_000042",
    "code": "RT",
    "name": "Retirement",
    "status": "ACTIVE",
    "created_at": "2026-09-06T10:12:00Z"
  }
}

Fields

Field	Required	Format / values	Notes
`investor_id`	yes	friendly investor ID, e.g. `I_SI_IND_000042`	Must be an investor in your account. The investor need not be `REGISTERED` yet, but an order under this account will require it.
`code`	yes	exactly 2 characters, `A-Z` or `0-9`	Caller-chosen. Becomes part of the account ID. Not required to be unique.
`name`	no	free text	Human-friendly label, e.g. `Retirement`, `Tax Saver`.

Validation

Condition	Response
`investor_id` missing	`400 VALIDATION_FAILED` — “investor_id is required”
`code` not `[A-Z0-9]{2}`	`400 VALIDATION_FAILED` — “code must be exactly two characters (A-Z, 0-9)“
Investor not found in your account	`404 NOT_FOUND` — “investor not found”

Friendly ID conventions

The API uses short, human-quotable IDs so your systems and staff can refer to a client without passing PII. They are our identifiers — the exchange’s internal client code is never exposed.

Entity	Pattern	Example
Investor	`I_<holding>_<tax status>_<6-digit sequence>`	`I_SI_IND_000042`
Investment account	`A_<code>_<6-digit sequence>`	`A_RT_000001`

Holding shorthand: SINGLE → SI, JOINT → JO, ANYONE_OR_SURVIVOR → AS. Tax-status shorthand: INDIVIDUAL → IND, NRI_REPATRIABLE → NRE, NRI_NON_REPATRIABLE → NRO, MINOR → MIN, HUF → HUF, COMPANY → COM, TRUST → TRU.

IDs are immutable. An investor ID keeps its creation-time holding and tax-status shorthand even if the tax status is later amended — exactly as the exchange’s own client code is immutable.

Read endpoints

GET /api/investment-accounts/v1/:id
GET /api/investment-accounts/v1?investor_id=&limit=&cursor=

Next step

Create a mandate for auto-debit, or go straight to creating a purchase order.

Atlas

API Guide

Create an Investment Account

Endpoint

Fields

Validation

Friendly ID conventions

Read endpoints

Next step

​Endpoint

​Fields

​Validation

​Friendly ID conventions

​Read endpoints

​Next step

Endpoint

Fields

Validation

Friendly ID conventions

Read endpoints

Next step