> ## 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 Investment Account

> Group an investor's products under a named, friendly-ID account that every order, mandate and payment references.

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

```http theme={null}
POST /api/investment-accounts/v1/
Authorization: Bearer <token>
Content-Type: application/json
```

```json theme={null}
{ "investor_id": "I_SI_IND_000042", "code": "RT", "name": "Retirement" }
```

Response `201`:

```json theme={null}
{
  "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`.

<Note>
  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.
</Note>

## Read endpoints

```http theme={null}
GET /api/investment-accounts/v1/:id
GET /api/investment-accounts/v1?investor_id=&limit=&cursor=
```

## Next step

[Create a mandate](/mandates) for auto-debit, or go straight to
[creating a purchase order](/purchase-orders).