> ## 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.

# Change of Broker (Beta)

> Move an existing folio to a different distributor (ARN) or RIA. Beta — behaviour may change.

<Warning>
  **Beta.** Change of Broker is built on the exchange's Non-Financial
  Transaction (NFT) API, which is thinly specified and has not yet been verified
  end to end against the live exchange. Request/response shapes, statuses and
  error codes may change without notice. Do not build a production flow on it
  without testing it in the sandbox and with your account manager.
</Warning>

A **broker change** asks the exchange to re-map an existing folio to a new
distributor code (ARN, optionally with a sub-broker code and EUIN) or to an
RIA. It is a *non-financial* request: no money moves, and no order is created.

## Endpoint

```http theme={null}
POST /api/broker-changes/v1/
Authorization: Bearer <token>
Idempotency-Key: <unique key>
Content-Type: application/json
```

```json theme={null}
{
  "investor_id": "I_SI_IND_000042",
  "amc_code": "H",
  "folio_no": "1234567",
  "auth_mode": "TWO_FACTOR",
  "two_fa_channel": "BOTH",
  "mobile": "9876543210",
  "broker_code": "ARN-12345",
  "euin": "E123456",
  "client_ref": "cob-1"
}
```

Response `201`:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "bkc_4a1b2c",
    "investor_id": "I_SI_IND_000042",
    "amc_code": "H",
    "folio_no": "1234567",
    "pan": "AB******4F",
    "auth_mode": "TWO_FACTOR",
    "two_fa_channel": "BOTH",
    "broker_code": "ARN-12345",
    "euin": "E123456",
    "status": "SUBMITTED",
    "provider_remark": "NFT - Change of broker record Added successfully.",
    "created_at": "2026-10-01T09:00:00Z",
    "updated_at": "2026-10-01T09:00:00Z"
  }
}
```

## Fields

| Field | Required | Format / values | Notes |
| - | - | - | - |
| `investor_id` | yes | friendly investor ID | Must be registered with the exchange. Its PAN is the primary-holder PAN on the filing. |
| `amc_code` | yes | max 3 chars | The folio's fund-house code. |
| `folio_no` | yes | max 25 chars | The existing folio to re-map. |
| `holder_name` | no | max 40 chars | Primary holder name as on the folio. |
| `auth_mode` | yes | `TWO_FACTOR` \| `WET_SIGNATURE` | How the investor authorises the change — see below. |
| `two_fa_channel` | for `TWO_FACTOR` | `MOBILE` \| `EMAIL` \| `BOTH` | Which of the investor's registered contacts the exchange uses for 2FA. |
| `email` | for `WET_SIGNATURE` | max 120 chars | Primary holder email. |
| `mobile` | no | max 15 chars | Primary holder mobile. |
| `broker_code` | one of | max 20 chars, e.g. `ARN-12345` | New distributor ARN. Give this **or** `ria_code`. |
| `sub_broker_code` | no | max 15 chars | |
| `euin` | no | max 7 chars | |
| `ria_code` | one of | max 20 chars | New RIA code, for a move to an RIA. |
| `client_ref` | no | your reference | Echoed back. |

## Authorisation modes

* **`TWO_FACTOR`** — the exchange authorises the change with the investor
  through the channel you chose. The request is `SUBMITTED` immediately. How
  the investor completes the 2FA is handled by the exchange and is not
  reported back through this API.
* **`WET_SIGNATURE`** — the request is filed as `PENDING_DOCUMENT`. Upload the
  signed change-of-broker form as a multipart `file` (max 10 MB):

  ```http theme={null}
  POST /api/broker-changes/v1/:id/image
  Authorization: Bearer <token>
  Content-Type: multipart/form-data
  ```

  On success the request moves to `SUBMITTED` and the updated record is
  returned. Uploading again after that returns `INVALID_STATE`.

## Status

| Status | Meaning |
| - | - |
| `PENDING_DOCUMENT` | Wet-signature request accepted by the exchange; signed form not uploaded yet. |
| `SUBMITTED` | Filed with the exchange (and, for wet signature, the form uploaded). |
| `REJECTED` | The exchange refused the filing; `provider_remark` has the reason. File a new request. |

<Note>
  The exchange publishes no final-outcome report for these requests, so
  `SUBMITTED` is the last status you will see. Confirm completion on the folio
  (for example via the AMC statement) until a status feed is available.
</Note>

## Reading requests

* `GET /api/broker-changes/v1/:id` — one request.
* `GET /api/broker-changes/v1/?investor_id=&status=&limit=&cursor=` — list.

## Webhooks

`broker_change.submitted` and `broker_change.rejected`, each with
`{ broker_change_id, status, provider_remark }`. A wet-signature request emits
`broker_change.submitted` only once the form is uploaded. See
[Webhooks](/api-documentation/webhooks).