Returning.AIDevelopers
v1

API reference / Users

.md

Manage User Account

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

Last updated 26 Sep 2026API v1

Method
POST
Path
https://api.returning.ai/v1/users/manage
Permission
manageUser
Retries
Safe to repeat; a repeat returns 400

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.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
manageUserShown in the dashboard as “Delete/Restore User”

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#

Authorization#stringREQUIRED
Community API key with manageUser.

RuleBearer <API_KEY>

Content-Type#stringREQUIRED
Request body format.

Ruleapplication/json

Body#

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

user#stringREQUIRED
The trader's exact username or email. Platform user IDs are not accepted.

RuleUsername or email, exact match

Eg"trader@example.com"

action#stringREQUIRED
delete removes the trader. restore brings back a removed trader.

Ruledelete or restore

Eg"delete"

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.

status#stringALWAYS
Result of the request.

Rulesuccess

code#stringALWAYS
Machine-readable result code: USER_SOFT_DELETED after delete, USER_RESTORED after restore.

RuleUSER_SOFT_DELETED or USER_RESTORED

message#stringALWAYS
Human-readable summary. Do not branch on it.
{
  "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 request03

400Fix the request
user is empty, or action is not delete or restore. remove is not accepted; send delete. detail names the field.
401AUTHENTICATION_REQUIREDFix the request
The key is missing, invalid or expired. Send Authorization: Bearer <API_KEY> with a current key.
403API_KEY_PERMISSION_DENIEDFix the request
The key is valid but lacks manageUser. Add the permission in Settings > Integration > API Keys.

Fix the data05

404USER_NOT_FOUNDFix the data
No account has that exact username or email. Check the value; platform user IDs are not accepted.
403USER_NOT_IN_COMMUNITYFix the data
The account that matches is not in your API key's community. Check the key and the username or email.
400USER_ALREADY_DELETEDFix the data
The trader is already removed. Nothing changed; treat it as done.
400USER_NOT_DELETEDFix the data
The trader is not removed, so there is nothing to restore. Nothing changed; treat it as done.
404COMMUNITY_NOT_FOUNDFix the data
The key's community no longer exists. Use a key from an active community.

Retry with backoff02

500USER_MANAGEMENT_FAILEDRetry with backoff
The change failed unexpectedly. Check the trader with Get User Data, then retry with backoff if nothing changed.
500AUTHENTICATION_FAILEDRetry with backoff
The key could not be checked. Retry the same request with backoff.
{
  "status": "fail",
  "code": "USER_ALREADY_DELETED",
  "message": "User is already removed."
}

Next step#

Get User DataPOST/v1/users/infoConfirm the change. After delete it returns 404 USER_NOT_FOUND; after restore it returns the trader.