Prerequisites & Authentication

The Mutual Fund API is a whitelabelled service for transacting in Indian mutual funds. This guide covers what you need before your first call, how authentication works, and the conventions (envelopes, errors, idempotency, pagination) that apply to every endpoint.

What you get

When your account is provisioned you receive:

Item	Description
`client_id`	Public identifier for your integration.
`client_secret`	Secret credential. Store it in a secret manager — it is shown only once and cannot be retrieved later.
Environment	`uat` for integration testing, `prod` for live money. Each has its own base URL and its own credential pair.

Account provisioning (member code, exchange credentials, callback URL, scopes) is handled by your onboarding contact. This guide assumes you already have an active account.

Base URL

https://<env-host>/api/<resource>/v1

Every resource group is versioned independently (/api/investors/v1, /api/orders/v1, …). Examples in this documentation use https://api.example.com as a placeholder.

Step 1 — Get a bearer token

curl -sX POST https://api.example.com/api/auth/v1/token \
  -H 'Content-Type: application/json' \
  -d '{ "client_id": "b1f0...", "client_secret": "..." }'

{
  "success": true,
  "data": {
    "access_token": "mfa_9f2c...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "investors:write mandates:write orders:write payments:write reports:read"
  }
}

expires_in is in seconds. Request a fresh token before it expires; there is no refresh token — call /token again with your credentials.
scope is the space-separated list of permissions your account holds. Calls that need a scope you don’t have return 403 FORBIDDEN.

POST /api/auth/v1/token is rate limited to 8 failed attempts per client_id per 15-minute window. Exceeding it returns 429 RATE_LIMITED with a Retry-After header. A failed attempt means bad credentials — successful calls don’t count.

Auth failures

Condition	Response
Bad credentials (or upstream identity disabled)	`401 UNAUTHORIZED` — “Invalid client credentials.”
Credentials valid but no active account	`403 NOT_PROVISIONED` — “No active account for these credentials.”
Too many failed attempts	`429 RATE_LIMITED`

Step 2 — Call the API

Send the token as a bearer header on every other endpoint:

curl -sX GET https://api.example.com/api/auth/v1/me \
  -H 'Authorization: Bearer mfa_9f2c...'

GET /api/auth/v1/me echoes back what your token can do:

{
  "success": true,
  "data": {
    "tenant_id": "...",
    "arn": "...",
    "member_code": "...",
    "environment": "uat",
    "scopes": ["investors:write", "orders:write", "payments:write"],
    "callback_url": "https://api.example.com/webhooks/nse/payments/...",
    "nse_credentials_configured": true
  }
}

nse_credentials_configured: false means the exchange credentials behind your account are incomplete — orders and payments will fail until that is resolved with your onboarding contact. Credential values are never returned, in any form.

Revoking a token

curl -sX POST https://api.example.com/api/auth/v1/revoke \
  -H 'Authorization: Bearer mfa_9f2c...'

Returns 204. The presented token is invalidated immediately.

Request conventions

Every endpoint in this API shares the following conventions.

Response envelope

Success:

{ "success": true, "data": { }, "message": "" }

Errors:

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Human-readable summary.",
    "details": [ { "field": "primary_holder.name", "issue": "required" } ],
    "provider_remark": "The exchange's own words, when the failure came from it.",
    "request_id": "req_01J8..."
  }
}

provider_remark is informational only. Never parse it — branch on code. Its wording can change without notice.

Error codes

`code`	HTTP	Meaning
`VALIDATION_FAILED`	400	Request shape or business rule failed locally.
`UNAUTHORIZED`	401	Missing / invalid / expired token.
`FORBIDDEN`	403	Valid token, missing scope.
`NOT_PROVISIONED`	403	No active account for these credentials.
`NOT_FOUND`	404	Not found within your account.
`IDEMPOTENCY_KEY_REUSED`	409	Same key, different body.
`INVALID_STATE`	409	Illegal state transition (e.g. cancelling an allotted order).
`INVALID_SCHEME`	422	Scheme doesn’t allow this transaction.
`KYC_INCOMPLETE`	422	Investor is not `REGISTERED` yet.
`MANDATE_NOT_ACTIVE`	422	Mandate isn’t usable.
`INSUFFICIENT_MANDATE_LIMIT`	422	Debit exceeds the mandate ceiling.
`UCC_REJECTED`	422	The exchange rejected an investor/mandate registration.
`ORDER_REJECTED`	422	The exchange rejected the order.
`PAYMENT_REJECTED`	422	The exchange rejected the payment.
`RATE_LIMITED`	429	Back off; `Retry-After` is set.
`PROVIDER_UNAVAILABLE`	502	Exchange unreachable or erroring; safe to retry.
`INTERNAL`	500	Unexpected server error.

Request ID

Send X-Request-Id: <your-uuid> and it is echoed back on the response and in every error envelope’s request_id. Omit it and the server generates one. Quote this value in support requests.

Idempotency

Send Idempotency-Key: <uuid> on unsafe (write) calls.

First call: the response is stored against (account, key, body fingerprint) for 24 hours.
Replay with the same body: the stored response is returned verbatim with Idempotency-Replayed: true.
Same key, different body: 409 IDEMPOTENCY_KEY_REUSED.

Idempotency is currently enforced on POST /api/orders/v1/ — the call where it matters most. Sending the header on other writes is harmless and forward-compatible.

Pagination

List endpoints take ?limit=<n>&cursor=<opaque> (max limit 200) and return:

{ "success": true, "data": [ ], "next_cursor": "..." }

Pass next_cursor back as cursor for the next page. Absence of next_cursor means the last page.

Types

Amounts are JSON numbers, never strings.
Dates are YYYY-MM-DD.
Timestamps are RFC3339 UTC.
Enums are SCREAMING_SNAKE.

Next steps

Create an investor

Create an investor and wait for status: REGISTERED.

Create an investment account

Create an investment account to group the investor’s products.

Create a mandate for auto-debit payments.

Place and pay for an order

Create a purchase order and settle it.

Atlas

API Guide

Prerequisites & Authentication

What you get

Base URL

Step 1 — Get a bearer token

Auth failures

Step 2 — Call the API

Revoking a token

Request conventions

Response envelope

Error codes

Request ID

Idempotency

Types

Next steps

​What you get

​Base URL

​Step 1 — Get a bearer token

​Auth failures

​Step 2 — Call the API

​Revoking a token

​Request conventions

​Response envelope

​Error codes

​Request ID

​Idempotency

​Pagination

​Types

​Next steps

What you get

Base URL

Step 1 — Get a bearer token

Auth failures

Step 2 — Call the API

Revoking a token

Request conventions

Response envelope

Error codes

Request ID

Idempotency

Pagination

Types

Next steps