Returning.AIDevelopers
v1

API reference / Users

.md

Update User Data

Change one trader's profile, community roles or broker identifier, sending only the fields that change.

Last updated 26 Sep 2026API v1

Method
POST
Path
https://api.returning.ai/v1/users/update
Permission
manageUser
Retries
No Idempotency-Key; read back before repeating

When to use this

  • A trader changes their name, email or phone on your platform.
  • You add, remove or replace a trader's community roles, such as VIP.
  • You need to replace a trader's broker identifier. This is the only supported endpoint for that.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
manageUserRole changes also need bulkUpdateUser

Profile and identifier changes need manageUser. A request that includes updates.roles needs both manageUser and bulkUpdateUser. Keep the Community API key on your server.

Request#

Headers#

Authorization#stringREQUIRED
Community API key with manageUser, plus bulkUpdateUser for role changes.

RuleBearer <API_KEY>

Content-Type#stringREQUIRED
Request body format.

Ruleapplication/json

Body#

identifier finds the trader and updates holds the changes. Send only the properties that change. To replace the broker identifier, send custom_user_identifier as the only property in updates, in a request of its own.

identifier#objectREQUIRED
Selects the trader to change.

Eg{"type": "platform_user_id", "value": "3247779"}

type#stringREQUIRED
How value identifies the trader.

Ruleplatform_user_id, username, email, custom_user_identifier

Eg"platform_user_id"

value#string | numberREQUIRED
The identifier value to match.

Eg"3247779"

updates#objectREQUIRED
Only the changes you want to make.

RuleAt least one property

Eg{ ... }

firstname#stringOPTIONAL
The trader's first name.

Eg"Sample"

lastname#stringOPTIONAL
The trader's last name.
email#stringOPTIONAL
The trader's email. It must not belong to another trader.

RuleEmail format

phone#stringOPTIONAL
The trader's phone number.
roles#objectOPTIONAL
A role change.

Eg{"operator": "add", "names": ["VIP"]}

operator#stringREQUIRED
add and subtract are safe to repeat. overwrite replaces the trader's changeable roles in this community.

Ruleadd, subtract, overwrite

Eg"add"

names#string[]REQUIRED
Exact, case-sensitive role names in this community. all and @all cannot be changed.

RuleMin 1 item; unique

Eg["VIP"]

custom_user_identifier#string | numberOPTIONAL
The new broker identifier. Locate the trader by platform_user_id or username.

RuleMust be the only property in updates

Eg"<newBrokerCustomerId>"

curl --request POST \
  --url https://api.returning.ai/v1/users/update \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "identifier": {
      "type": "platform_user_id",
      "value": "3247779"
    },
    "updates": {
      "firstname": "Sample",
      "roles": {
        "operator": "add",
        "names": ["VIP"]
      }
    }
  }'

Response#

A 200 returns the trader after the update in data. roles is present only when the request changes roles. Read the trader back with Get User Data to confirm.

status#stringALWAYS
Result of the request.

Rulesuccess

code#stringALWAYS
Machine-readable result code.

RuleUSER_UPDATED

message#stringALWAYS
Human-readable summary. Do not branch on it.

Eg"User updated successfully"

data#objectALWAYS
The trader after the update.

Eg{ ... }

id#stringALWAYS
Platform user ID. Store it as a string and never do arithmetic on it.

RuleDecimal digits

Eg"3247779"

firstname#stringALWAYS
The stored first name.

Eg"Sample"

lastname#stringALWAYS
The stored last name.

Eg"Trader"

email#stringALWAYS
The stored email.

RuleEmail format

Eg"trader@example.com"

phone#stringALWAYS
The stored phone number.

Eg"15551234567"

custom_user_identifier#string | numberALWAYS
The trader's broker identifier.

RuleNullable

Eg"<brokerCustomerId>"

roles#string[]WHEN ROLES CHANGE
The trader's roles, returned when the request changes roles.

Eg["@all", "VIP"]

{
  "status": "success",
  "code": "USER_UPDATED",
  "message": "User updated successfully",
  "data": {
    "id": "3247779",
    "firstname": "Sample",
    "lastname": "Trader",
    "email": "trader@example.com",
    "phone": "15551234567",
    "custom_user_identifier": "<brokerCustomerId>",
    "roles": ["@all", "VIP"]
  }
}

Errors#

Errors from the API key check carry the code in meta.code, except the 401 for a role change without bulkUpdateUser, which has only a message. Other coded errors carry it in code. A 400 writes nothing, so correct the request and send it again. A malformed request, such as a bad identifier type or role operator, returns 400 with a message and a detail list explaining what's wrong, and no top-level code.

Fix the request08

400Fix the request

The body failed validation. There is no code; detail names the field. Common causes:

  • identifier.type is not one of the four types, or roles.operator is not add, subtract or overwrite.
  • updates is empty, or custom_user_identifier is empty.
  • roles.names is empty or includes all or @all (Default roles cannot be updated).
  • You looked the trader up by email and sent a new email, or by custom_user_identifier and sent a new custom_user_identifier. Look the trader up by platform user ID or username instead.
401Fix the request
The request changes roles and the key has manageUser but not bulkUpdateUser. The body is only {"message": "Your api key does not have permission to access this action"}, with no code. Add bulkUpdateUser to the key.
400INVALID_USER_UPDATEFix the request

The message names the rule:

  • Custom user identifier is not configured for this community: set up an active identifier field before sending custom_user_identifier.
  • Custom user identifier field is not configured correctly: ask Returning.AI to check the identifier field's setup.
  • <Field> - Identifier is required: send a non-empty identifier value.
400MIXED_IDENTIFIER_UPDATE_NOT_SUPPORTEDFix the request
The identifier change was combined with another update. Nothing was written; split it into two requests.
400ROLE_NOT_FOUNDFix the request
A role name did not match exactly. Role names are case-sensitive.
400ROLE_NAME_AMBIGUOUSFix the request
More than one role matched, so nothing was written. Use the exact role name.
401AUTHENTICATION_REQUIREDFix the request
The key is missing, malformed, invalid or expired. Send Authorization: Bearer <API_KEY> with a current key.
403API_KEY_PERMISSION_DENIEDFix the request
The key lacks manageUser. Add the permission in Settings > Integration > API Keys.

Fix the data03

404USER_NOT_FOUNDFix the data
No active trader in this community matches. Check the identifier.
409USER_EMAIL_CONFLICTFix the data
The new email belongs to another trader (message: Email already exists). Reconcile the two accounts first.
409USER_IDENTIFIER_CONFLICTFix the data
The new identifier belongs to another trader (message: <Field name> - Identifier is already used by another user, or <Field name> - Duplicate users found). Reconcile the two accounts first.

Retry with backoff02

500USER_UPDATE_FAILEDRetry with backoff
The update failed unexpectedly. Read the trader back with Get User Data before you try again.
503USER_IDENTIFIER_NOT_READYRetry with backoff
Identifier lookup is not ready. Retry later with backoff, or locate the trader by platform user ID.

Do not retry01

500USER_UPDATE_RECONCILIATION_REQUIREDDo not retry
The identifier change is unclear. Stop automatic retries and read the trader back before any other update.
{
  "status": "fail",
  "code": "MIXED_IDENTIFIER_UPDATE_NOT_SUPPORTED",
  "message": "Custom user identifier must be updated in a separate request"
}

Next step#

Get User DataPOST/v1/users/infoRead the trader back to confirm the new profile, roles or identifier.