> For the complete documentation index, see [llms.txt](https://guide.traderevolution.com/traderevolution-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.traderevolution.com/traderevolution-api/traderevolution-apis/backoffice-api/user-management.md).

# User management

This section describes the User creation process with a minimal required set of parameters. 

{% hint style="success" %}
A full list of parameters available for user creation can be found here:

<https://sandbox.traderevolution.com:8443/proftrading/rest/swagger-ui.html#/Users/createUserMethodUsingPOST>
{% endhint %}

The newly created user should be assigned at least one trading account, so the request body contains user details and a section for specifying the account details. Please note that creating a user with minimal parameters requires only a name for your trading account. If a trader should have multiple accounts with different rules it is worth considering the account preset entity. If this is the case, during the account creation you need to specify the preset ID and it will automatically be applied to a newly created account.&#x20;

You can check the list of all presets created on a server using the <mark style="color:blue;">`GET`</mark>`/accountPresets` method or refer to a corresponding section of this doc for a more detailed description.&#x20;

Also, the user should be allocated to a specific user group, please note that in this case, the user and his accounts inherit all settings from it.

The account is created with a server currency by default (Configuration > Settings > General) and is in an Active state (ready for trade after the deposit). New currency settings will be applied if they are overridden on the higher level.&#x20;

In response, you will receive the ID of the newly created user/account, keep it on your side, because the account ID will be used in your following requests, i.e. to perform deposit or other account operations.  Remember, that you can always get the account ID and other user details by User ID.&#x20;

## Create User

<mark style="color:green;">`POST`</mark> `/users`

The method is used to create a new user. This example describes a minimal set of parameters required for this process. For the full set of parameters available for a new user, please refer to Swagger.&#x20;

**Body**

<table><thead><tr><th width="240">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>email</code></td><td>string</td><td>Email of new user</td></tr><tr><td><code>firstName</code></td><td>string</td><td>Name of new user</td></tr><tr><td><code>lastName</code></td><td>string</td><td>Last name of new user</td></tr><tr><td><code>login</code></td><td>string</td><td>Login of new user</td></tr><tr><td><code>password</code></td><td>string</td><td>Password for new user</td></tr><tr><td><code>userGroup</code></td><td>integer</td><td>ID of the user group to which this user will be assigned</td></tr><tr><td><code>accounts</code></td><td></td><td>Section with account details</td></tr><tr><td><code>accountName</code></td><td>string</td><td>Name of the account that will be created for this user</td></tr></tbody></table>

**Request body**

```json
{
  "accounts": [
    {
      "accountName": "Account1223"
    }
  ],
  "email": "email@example.com",
  "firstName": "Name1123",
  "lastName": "Last123",
  "login": "Login1232",
  "password": "12345",
  "userGroup": 570789
}
```

**CURL**

{% code overflow="wrap" %}

```json
curl -X POST "http://sandbox.traderevolution.com:8443/proftrading/rest/users" -H "accept: application/json" -H "Authorization: Bearer eyItMjI2OTkxMTE4Ij...S2wnd2wVKqnE3QypO3xI7LJkLEiuMnd4_epgBqF3z_TRGULkAIAAA.4P7Xssd4FUvIWg2F3Evfd7YGInHwQ-rGfBsBOWbJpPo" -H "Content-Type: application/json" -d "{ \"accounts\": [ { \"accountName\": \"Account1223\" } ], \"email\": \"email@example.com\", \"firstName\": \"Name1123\", \"lastName\": \"Last123\", \"login\": \"Login1232\", \"password\": \"12345\", \"userGroup\": 570789}"
```

{% endcode %}

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "accounts": [
    {
      "id": 680172,
      "name": "Account1223"
    }
  ],
  "id": 1158399,
  "login": "Login1232"
}
```

{% endtab %}
{% endtabs %}

As a result, you will get a user ID, login name, account ID, and account name in response. Standard errors can be received as well.&#x20;

## Find user (by login, e-mail, etc.)

<mark style="color:blue;">`GET`</mark>`/users`

This method is used to get the names of available users and their IDs. All users can be filtered using various parameters like *brandingId*, *email*, *userGroupId*. The required parameter should be simply specified in the *query*.&#x20;

**Query**

<table><thead><tr><th width="389">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>brandingId</code></td><td>string</td><td>Branding identifier.</td></tr><tr><td><code>email</code></td><td>string</td><td>Filter users by e-mail.</td></tr><tr><td><code>login</code></td><td>string</td><td>Filter records by user login. Several logins can be specified using comma separator. </td></tr><tr><td><code>offset</code></td><td>string</td><td>Defines the initial index number of outputting records.</td></tr><tr><td><code>planId</code></td><td>string</td><td>Identifier of the plan. Any type of plan can be set here (Risk plan, Swap plan, etc.).</td></tr><tr><td><code>userGroupId</code></td><td>string</td><td>Identifier of the user group.</td></tr></tbody></table>

**CURL example (users are filtered by&#x20;*****userGroupId*****)**

{% code overflow="wrap" %}

```json
curl -X GET "https://sandbox.traderevolution.com:8443/proftrading/rest/users?userGroupId=570789" -H "accept: application/json" -H "Authorization: Bearer eyItMTg5Njc5OTc0OSI6LTE4OTY3OTk3NDksI...UIec_uAAAA.IPtdm_dV1fI1G2tMdJ7CXQSBnGMmZlAG2eMw03ceL0E"
```

{% endcode %}

**Response**

{% tabs %}
{% tab title="200" %}

```json
[
  {
    "id": 146695,
    "login": "User1"
  },
  {
    "id": 570790,
    "login": "User2"
  }
]
```

{% endtab %}
{% endtabs %}

As a result, you will get a user ID and login name of the users assigned to the group specified in the request (ID 570789). Standard errors can be received as well.&#x20;

{% hint style="success" %}
A full list of parameters that are available for `GET /users` can be found here:

<https://sandbox.traderevolution.com:8443/proftrading/rest/swagger-ui.html#/Users/getUsersUsingGET>
{% endhint %}

## Move user between groups

<mark style="color:yellow;">`PATCH`</mark> `/users/{id}`

The <mark style="color:yellow;">`PATCH`</mark> method is used to update specific user settings by his ID. This section describes moving users between groups. Transferring a user to another group can be useful in that the user will inherit the trading rules of this group or another scheduler tasks set will be applied to him.&#x20;

{% hint style="success" %}
A full list of parameters that are available for `PATCH /users` can be found here:

<https://sandbox.traderevolution.com:8443/proftrading/rest/swagger-ui.html#/Users/patchUserMethodUsingPATCH>
{% endhint %}

**Request example**

```json
{
  "userGroup": 42495
}
```

Please note that the request *body* contains the ID of the user group to which this user will be moved (so in the example our user will be moved to the group whose ID is 42495). The ID of the user, who will be transferred to another group, should be specified in the *path*, see CURL.

**CURL**

{% code overflow="wrap" %}

```json
curl -X PATCH "https://sandbox.traderevolution.com:8443/proftrading/rest/users/570790" -H "accept: application/json" -H "Authorization: Bearer eyItMTg5Njc5OTc0OSI6LTE4OTY3OTk3NDksIjU1NTMzMzU2MiI6NTU1MzMzNTYyLCIxNzg3NzA4MTcxIjoxNzg3NzA4MTcxLCIxNzAyNDYyMjQwIjoxNz...OAefLxUIec_uAAAA.IPtdm_dV1fI1G2tMdJ7CXQSBnGMmZlAG2eMw03ceL0E" -H "Content-Type: application/json" -d "{ \"userGroup\": 42495}"
```

{% endcode %}

**Response**

You will get a 204 message in response. This means that the user is moved successfully.&#x20;

## User status management

<mark style="color:yellow;">`PATCH`</mark> `/users/{id}`

The <mark style="color:yellow;">`PATCH`</mark> method is used to update specific user settings by his ID. This section describes the updating status of certain users. The following statuses are available: *Locked, Unlocked, Locked after brute force, Need activation* and *Expired*.

**Path**

| Name | Type    | Description                                     |
| ---- | ------- | ----------------------------------------------- |
| `id` | integer | Identifier of the user whose status is changed. |

**Body**

```json
{
  "rules": [
    {
      "ruleName": "STATUS_BLOCKED",
      "ruleValue": "2",
      "restriction": 0,
      "isOverridden": true
    }
  ]
}
```

**CURL**

{% code overflow="wrap" %}

```json
curl -X PATCH "http://sandbox.traderevolution.com:8443/proftrading/rest/users/570790" -H "accept: application/json" -H "Authorization: Bearer eyIyMzI0ODk2MiI6MjMyNDg5NjIsI...NRRxLPsj6F5xX-C9hTN2iVW370Tk" -H "Content-Type: application/json" -d "{ \"rules\": [ { \"ruleName\": \"STATUS_BLOCKED\", \"ruleValue\": \"2\", \"restriction\": 0, \"isOverridden\": true } ]}"
```

{% endcode %}

The following values are available for the `ruleValue` parameter:

* 0 - `Unlocked`
* 1 - `Locked`
* 2 - `Locked after brute force`
* 3 - `Need activation`
* 4 - `Expired`

**Response**

In case the status is changed successfully, you will simply receive the `204` code in the response.&#x20;

{% hint style="success" %}
A full list of parameters that are available for `PATCH /users` can be found here:

<https://sandbox.traderevolution.com:8443/proftrading/rest/swagger-ui.html#/Users/patchUserMethodUsingPATCH>
{% endhint %}

## Change password

<mark style="color:yellow;">`PATCH`</mark>`/users/{id}/changePassword`

This API call is used to change passwords. The new password will be updated with the specified value for the user whose ID is added to the request path.&#x20;

**Path**

| Name | Type   | Description                                              |
| ---- | ------ | -------------------------------------------------------- |
| `id` | string | Identifier of the user for whom the password is changed. |

**Body**

```json
{
  "password": "newpass123",
  "secondPassword": "newpass123",
  "tradingPassword": "12345"
}
```

**CURL**

{% code overflow="wrap" %}

```json
curl -X PATCH "http://sandbox.traderevolution.com:8443/proftrading/rest/users/570790/changePassword" -H "accept: application/json" -H "Authorization: Bearer eyItNzIyNDgyODY5IjotNzIyNDgyODY5LCItNjcyNzUxOTQ5IjotNjcyNzUxOTQ5LCI4NjU2NjY4MTAiOjg2NTY2NjgxMCwiMTI1NDM4MDA0...5tiVOdEu9M7PnRl5Wg1I-zh60-Ir-LnF34x7PHEAQAA.cOEN1WQK2wfcD-I7HggcdbL9rzD963UtTXFWnuIakzY" -H "Content-Type: application/json" -d "{ \"password\": \"newpass123\", \"secondPassword\": \"newpass123\", \"tradingPassword\": \"12345\"}"
```

{% endcode %}

**Response**

You will get a 200 (OK) response in case all the passwords are changed successfully.&#x20;

{% hint style="success" %}
A full list of parameters that are available for managing passwords can be found here:

<https://sandbox.traderevolution.com:8443/proftrading/rest/swagger-ui.html#/Password_management>
{% endhint %}

## Get user groups

<mark style="color:blue;">`GET`</mark>`/userGroups`

This method is used to get a list of all user groups available on this server. All groups can be filtered using various parameters like *brandingId*, *name*, etc. The required parameter should be simply specified in the *query*.&#x20;

**Query**

<table><thead><tr><th width="389">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>brandingId</code></td><td>string</td><td>Branding identifier.</td></tr><tr><td><code>name</code></td><td>string</td><td>Filter user groups by name.</td></tr><tr><td><code>limit</code></td><td>string</td><td>Number of records to retrieve. Default is 1000, maximum is 1000. </td></tr><tr><td><code>offset</code></td><td>string</td><td>Defines the initial index number of outputting records.</td></tr><tr><td><code>planId</code></td><td>string</td><td>Identifier of the plan. Any type of plan can be set here (Risk plan, Swap plan, etc.).</td></tr><tr><td><code>serverId</code></td><td>string</td><td>Identifier of the server (cluster node).</td></tr></tbody></table>

**CURL example (all groups are returned, no filtering is applied)**

{% code overflow="wrap" %}

```json
curl -X GET "https://sandbox.traderevolution.com:8443/proftrading/rest/userGroups" -H "accept: application/json" -H "Authorization: Bearer eyItMjQ2NzI5NDUzIjotMjQ2NzI5NDUzLCItMTYzNjE4OTE0OSI6LTE2MzYxODkxNDksIjIwMDk0ODA1NDciOjIwMDk0ODA1NDcsIi0xODQzMD...dju7Z6ThRVSvXnrjoAY0pRkBiGq3SK0xLH4pSuAyBT1WxpbXzWLVtG_0SVlq2bANufLxtVFFatRS3s-P1XIC-cL3HlKZBsAQAA.5AHDn_Ohw52zPaHKr8l9H0kx6HWv1sh_1IvOJ5DDpHE"
```

{% endcode %}

**Response**

{% tabs %}
{% tab title="200" %}

```json
[
  {
    "userGroupId": -10,
    "userGroupName": "Root"
  },
  {
    "userGroupId": 0,
    "userGroupName": "Default Trader"
  },
  {
    "userGroupId": 2,
    "userGroupName": "Default Dealer"
  },
  {
    "userGroupId": 13340,
    "userGroupName": "PFS_Exchange"
  },
  {
    "userGroupId": 831168,
    "userGroupName": "TEST"
  }
]
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
A full list of parameters that are available for `/userGroups` can be found here:

<https://sandbox.traderevolution.com:8443/proftrading/rest/swagger-ui.html#/User_groups>
{% endhint %}

## Trading Webhooks

The Trading Webhooks keys methods allows generating and managing API keys used for trading via webhooks. These keys are used for authentication when sending webhook requests to the TE server.

An authorized user can generate, retrieve, and remove webhook keys only for their own account.

**Generate Webhooks keys**&#x20;

<mark style="color:green;">`POST`</mark> `/webhookskeys`

This method is used to generate a new webhook API and secret keys. The request may include an optional key name. If the name is not provided, the system will generate one automatically.

**Body parameter**

<table><thead><tr><th width="389">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td>string/body</td><td>Optional name of the webhook key. Maximum length is 32 characters.</td></tr></tbody></table>

**Request body**

```json
{
  "name": "webhook-key-1"
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "webhookskeyId": 145,
  "apiKey": "GaBvC…yxvpgIHfXCbpiU8",
  "key": "316…578",
  "createdDate": 1714780800000,
  "expiredDate": 1717382800000,
  "name": "webhook-key-1"
}
```

{% endtab %}
{% endtabs %}

#### **Get Webhooks keys**&#x20;

<mark style="color:blue;">`GET`</mark>`/webhooksKeys`

This method returns a list of webhook keys generated by the authorized user. The response contains all keys created by the user, except the secret key value.

**Response**

{% tabs %}
{% tab title="200" %}

```json
[
  {
    "webhookskeyId": 145,
    "apiKey": "GaBvCWdwsyTx…aZyxvpgIHfXCbpiU8",
    "createdDate": 1714780800000,
    "expiredDate": 1717382800000,
    "name": "webhook-key-1"
  },
  {
    "webhookskeyId": 146,
    "apiKey": "n7cYjP2sdFv5…3Xc9RtDqWbU",
    "createdDate": 1714800000000,
    "expiredDate": null,
    "name": "webhook-key-2"
  }
]
```

{% endtab %}
{% endtabs %}

In the response an array with keys and additional information is sent.

#### **Delete Webhooks keys**&#x20;

<mark style="color:$danger;">`DELETE`</mark>`/webhooksKeys/{webhookskeyId}`

This method allows removing webhook keys. Webhook key ID that need to be deleted must be specified in the path parameters.

**Path parameter**

<table><thead><tr><th width="389">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>webhookskeyId</code></td><td>integer/path</td><td>Unique identifier of the webhook key.</td></tr></tbody></table>

In the response the 200 OK status will be sent if the webhook key was deleted successfully.