# Manage User Account

Remove one trader's account, or restore a removed account, by username or email.

- Endpoint: `POST https://api.returning.ai/v1/users/manage`
- Section: Users and data / Users
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Permission: `manageUser` (Shown in the dashboard as "Delete/Restore User")
- Retries: Safe to repeat; a repeat returns 400
- Guide: hand-written
- Verified: live, 2026-09-27
- Last updated: 26 Sep 2026
- Web page: https://docs.returning.ai/api-reference/users/manage-user-account

## When to use this

- A trader closes their trading account and you want their loyalty account removed as well.
- You removed a trader by mistake and need to restore the account, with its balances and history.

**Instead:** Use [Update User Data](https://docs.returning.ai/api-reference/users/update-user-data.md) instead to change a trader's profile or roles.

**Action values:** Send `delete` to remove a trader and `restore` to bring them back. `remove` is rejected with `400`.

## Authentication

- Header: `Authorization: Bearer <API_KEY>`
- Permission: `manageUser`

Removing and restoring need `manageUser`. The trader must be a member of the API key's community. Keep the key on your server.

## Behaviour

`delete` is a soft delete. It marks the trader's account as removed; their profile, balances and history are kept, so `restore` brings everything back. The mark is on the trader's account itself, not on their membership in your community, so it applies wherever that account is used.

While removed, Get User Data returns `404 USER_NOT_FOUND` for the trader. They still appear in Get Users with Filters and in your community's member list, so do not use those lists to check whether a trader is removed.

## Request

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | Community API key with `manageUser`. (`Bearer <API_KEY>`) |
| `Content-Type` | `string` | Yes | Request body format. (`application/json`) |

### Body

`user` is matched exactly against the trader's username or email. `action` is `delete` or `restore`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `user` | `string` | Yes | The trader's exact username or email. Platform user IDs are not accepted. (Username or email, exact match) |
| `action` | `string` | Yes | `delete` removes the trader. `restore` brings back a removed trader. (`delete` or `restore`) |

### Example request

```bash
curl --request POST \
  --url https://api.returning.ai/v1/users/manage \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "user": "trader@example.com",
    "action": "delete"
  }'
```

## Response

A `200` means the change is saved. `code` is `USER_SOFT_DELETED` after `delete` and `USER_RESTORED` after `restore`. Branch on the HTTP status and `code`, never on `message`.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `status` | `string` | always | Result of the request. (`success`) |
| `code` | `string` | always | Machine-readable result code: `USER_SOFT_DELETED` after `delete`, `USER_RESTORED` after `restore`. (`USER_SOFT_DELETED` or `USER_RESTORED`) |
| `message` | `string` | always | Human-readable summary. Do not branch on it. |

### Example response (200)

```json
{
  "status": "success",
  "code": "USER_SOFT_DELETED",
  "message": "User has been deleted successfully"
}
```

## Errors

Errors from the API key check, such as 401 and 403 `API_KEY_PERMISSION_DENIED`, carry the code in `meta.code`; other errors carry it in `code`. A malformed body returns `400` with a `message` and a `detail` naming the field, and no `code`. A `400` or `404` changes nothing.

### Fix the request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | - | `user` is empty, or `action` is not `delete` or `restore`. `remove` is not accepted; send `delete`. `detail` names the field. |
| 401 | `AUTHENTICATION_REQUIRED` | The key is missing, invalid or expired. Send `Authorization: Bearer <API_KEY>` with a current key. |
| 403 | `API_KEY_PERMISSION_DENIED` | The key is valid but lacks `manageUser`. Add the permission in Settings > Integration > API Keys. |

### Fix the data

| Status | Code | What to do |
| --- | --- | --- |
| 404 | `USER_NOT_FOUND` | No account has that exact username or email. Check the value; platform user IDs are not accepted. |
| 403 | `USER_NOT_IN_COMMUNITY` | The account that matches is not in your API key's community. Check the key and the username or email. |
| 400 | `USER_ALREADY_DELETED` | The trader is already removed. Nothing changed; treat it as done. |
| 400 | `USER_NOT_DELETED` | The trader is not removed, so there is nothing to restore. Nothing changed; treat it as done. |
| 404 | `COMMUNITY_NOT_FOUND` | The key's community no longer exists. Use a key from an active community. |

### Retry with backoff

| Status | Code | What to do |
| --- | --- | --- |
| 500 | `USER_MANAGEMENT_FAILED` | The change failed unexpectedly. Check the trader with Get User Data, then retry with backoff if nothing changed. |
| 500 | `AUTHENTICATION_FAILED` | The key could not be checked. Retry the same request with backoff. |

**Retries:** Manage User Account does not accept an `Idempotency-Key`, but repeating a request cannot change a trader twice: a second `delete` returns `400 USER_ALREADY_DELETED` and a second `restore` returns `400 USER_NOT_DELETED`. After a timeout, check with Get User Data before you repeat. Over the [rate limit](https://docs.returning.ai/how-it-works.md#rate-limits), requests return `429`; wait for the window to reset, then retry.

## Next step

- [Get User Data](https://docs.returning.ai/api-reference/users/get-user-data.md): `POST /v1/users/info`. Confirm the change. After `delete` it returns `404 USER_NOT_FOUND`; after `restore` it returns the trader.