> ## Documentation Index
> Fetch the complete documentation index at: https://pamm-api.exuratech.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Investor endpoints

> Contracts for listing, provisioning, registering, and retrieving PAMM Investors.

## List Investors

`GET /api/v1/investor/directory`

| Query parameter | Type | Required | Description |
| - | - | - | - |
| `engine` | enum | No | Defaults to `ALL`; explicitly send `PAMM`. |
| `page` | integer | No | Defaults to `1`; minimum `1`; used for PAMM pagination. |
| `limit` | integer | No | Defaults to `50`; range `1..100`. |
| `search` | string | No | Searches Investor login or name. |
| `search_by` | enum | No | `login` or `name`; omitted means both. |
| `sort_by` | enum | No | `id`, `mt5_login`, `name`, or `created_at` (default). |
| `sort_dir` | enum | No | `asc` or `desc` (default). |
| `exclude_subscribed` | boolean | No | Defaults to `false`; excludes PAMM Investors with subscription history. |
| `branch_id` | integer | No | Filters by the account owner's branch. |
| `metatrader_account_product_id` | integer | No | Filters by configured account product. |
| `cursor` | string | No | Opaque cursor for `engine=ALL` only. |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://pamm-api.example.com/api/v1/investor/directory?engine=PAMM&limit=50" \
  -H "Authorization: Bearer YOUR_CRM_API_KEY"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "engine": "PAMM",
      "id": 410,
      "mt5_login": "146600",
      "name": "Investor Demo",
      "created_at": "2026-07-21T13:10:00"
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "total": 1,
  "page": 1
}
```

### Directory response fields

| Field | Type | Meaning |
| - | - | - |
| `items` | array | Investor records on this page. |
| `items[].engine` | string | `PAMM` in this workflow. |
| `items[].id` | integer | Internal Investor ID. |
| `items[].mt5_login` | string | Investor MT5 login. |
| `items[].name` | string | Stored account name or alias. |
| `items[].created_at` | datetime | Registration time. |
| `items[].current_master_login` | string or null | Master from the selected current or historical subscription. |
| `items[].current_subscription_status` | string or null | `ACTIVE`, `PAUSED`, `CANCELLED`, or null when there is no subscription. |
| `items[].branch_id`, `branch_name` | integer or null, string or null | Owner branch metadata. |
| `total` | integer or null | Total matching Investors. |
| `page` | integer or null | Requested page for PAMM. |
| `has_more` | boolean | Whether another page exists. |
| `next_cursor` | string or null | Used with `ALL`, normally null with PAMM. |

## Register an existing Investor

`POST /api/v1/investor/add`

| Body field | Type | Required | Description |
| - | - | - | - |
| `mt5_login` | string | Yes | Positive numeric login of an existing MT5 account. |
| `name` | string | Yes | Investor name or alias. |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "mt5_login": "146600",
  "name": "Investor Demo"
}
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "engine": "PAMM",
  "id": 410,
  "mt5_login": "146600",
  "name": "Investor Demo",
  "created_at": "2026-07-21T13:10:00"
}
```

A duplicate login returns `409`. Registration does not credit funds or create a subscription.

## Create a new Investor

`POST /api/v1/investor/create`

| Body field | Type | Required | Description |
| - | - | - | - |
| `first_name` | string | Yes | MT5 holder first name. |
| `last_name` | string | Yes | MT5 holder last name. |
| `name` | string | Yes | Investor alias. |
| `username` | email | Yes | Email associated with MT5 provisioning. |
| `platform_group` | string | Yes | Broker-agreed Investor MT5 group. |
| `leverage` | string | No | Defaults to `100`. |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "first_name": "Carlos",
  "last_name": "Perez",
  "name": "Investor Demo",
  "username": "carlos.perez@example.com",
  "platform_group": "<MT5_INVESTOR_GROUP>",
  "leverage": "100"
}
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": 410,
  "mt5_login": "146600",
  "name": "Investor Demo",
  "created_at": "2026-07-21T13:10:00",
  "password": "<MT5_MAIN_PASSWORD>",
  "investor_password": "<MT5_INVESTOR_PASSWORD>"
}
```

The new account has no balance and no Master assignment.

### Investor response fields

Registration returns `engine`, `id`, `mt5_login`, `name`, and `created_at` with the meanings above. Optional directory metadata can be null. Creation also returns:

| Field | Type | Meaning |
| - | - | - |
| `password` | string | Main password for the created MT5 account; secret. |
| `investor_password` | string | Read-only password; secret. |

## Update the Investor name

`PATCH /api/v1/investor/{investor_id}`

| Parameter | Location | Type | Required | Meaning |
| - | - | - | - | - |
| `investor_id` | Path | integer | Yes | Internal ID, not the MT5 login. |
| `name` | JSON body | string | Yes | Trimmed non-empty alias, at most 120 characters. |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "Investor Demo Updated"
}
```

Returns the Investor record without passwords, using the registration response fields above. This updates the local PAMM alias, not the MT5 user's name. Missing records return `404`; invalid names return `422`.

## Retrieve sensitive Investor details

`GET /api/v1/info/investor/{investor_login}`

| Path parameter | Type | Required | Description |
| - | - | - | - |
| `investor_login` | string | Yes | Investor MT5 login. |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": 410,
  "mt5_login": "146600",
  "name": "Investor Demo",
  "mt5_password": "<MT5_MAIN_PASSWORD>",
  "mt5_investor_password": "<MT5_INVESTOR_PASSWORD>",
  "created_at": "2026-07-21T13:10:00"
}
```

> [!WARNING]
>
> Call this route only from an authorized administrative backend. Treat both passwords as secrets and never log the complete response.

### Sensitive response fields

| Field | Type | Meaning |
| - | - | - |
| `engine`, `type` | string | `PAMM` and `INVESTOR`. |
| `id`, `mt5_login`, `name`, `created_at` | integer, string, string, datetime | Registration identity and time. |
| `mt5_password`, `mt5_investor_password` | string or null | Stored MT5 credentials. |
| `user_id` | integer or null | Linked platform user, when available. |

> [card] [Previous: Master endpoints](https://pamm-api.exuratech.com/reference/masters.md)
>
> Return to Master provisioning contracts.

> [card] [Next: Subscription endpoints](https://pamm-api.exuratech.com/reference/subscriptions.md)
>
> Open assignment and relationship queries.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.