Returning.AIDevelopers
v1

API reference / User Fields / User Field History

.md

Deprecated field-first history write

This retired address for writing a trader's field value always returns 404 ROUTE_NOT_FOUND and never saves anything.

Last updated 26 Sep 2026API v1

Method
POST
Path
https://api.returning.ai/v1/communities/{communityId}/user-fields/{fieldId}/users/{userId}/histories
Permission
None
Retries
Never succeeds; don't retry, move to the current write

When to use this

  • Older code still calls this address and gets 404 ROUTE_NOT_FOUND; move it to the current write.
  • You're checking whether an old integration can still write field values this way. It can't.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
NoneNo permission is checked; every request returns the same 404

This address checks no API key and no permission: every request gets the same 404. The current write, Update a user field value, needs a Community API key with the userFields permission, shown in the dashboard as User Fields.

Behaviour#

This is the old field-first shape of the field value write. It's retired: it never writes a value and never adds a history entry. To move to the current write, swap the two path segments and keep everything else:

TEXT
Old: /v1/communities/{communityId}/user-fields/{fieldId}/users/{userId}/histories
New: /v1/communities/{communityId}/users/{userId}/user-fields/{fieldIdOrName}/histories

The body stays the same, for example {"value": "verified", "action": "overwrite"}. The current write also accepts an Idempotency-Key header.

Request#

Path parameters#

communityId#stringREQUIRED
Not checked. Any value gets the same 404.

Eg"66f000000000000000000010"

fieldId#stringREQUIRED
Not checked. In the current write, the field key or _id goes after the trader.

Eg"kycstatus"

userId#stringREQUIRED
Not checked. In the current write, the trader comes before the field.

Eg"3247779"

Headers#

Authorization#stringOPTIONAL
Not checked. Any key, or none, gets the same 404.

RuleBearer <API_KEY>

curl --request POST \
  --url https://api.returning.ai/v1/communities/66f000000000000000000010/user-fields/kycstatus/users/3247779/histories \
  --header 'Authorization: Bearer <API_KEY>'

Response#

There's no success response. Every request returns 404 with meta.code ROUTE_NOT_FOUND and meta.replacementRoute naming the current write. The method and route fields tell this apart from a trader or field that doesn't exist.

{
  "meta": {
    "status": "error",
    "statusCode": 404,
    "method": "POST",
    "route": "/v1/communities/{communityId}/user-fields/{fieldIdOrName}/users/{userIdentifier}/histories",
    "attemptedMethod": "POST",
    "documentedRouteId": "user-fields/history/create",
    "documentedRoute": "POST /v1/communities/{communityId}/user-fields/{fieldId}/users/{userId}/histories",
    "replacementRoute": "POST /v1/communities/{communityId}/users/{userId}/user-fields/{fieldIdOrName}/histories",
    "code": "ROUTE_NOT_FOUND"
  },
  "message": "API request rejected error.",
  "detail": "This documented legacy route does not exist.",
  "solution": "Read error detail and try again."
}

Errors#

The code is in meta.code. The one exception is a request with no Authorization header and a JSON body, which returns 400 with a non-JSON body instead.

Fix the request01

400Fix the request
No Authorization header was sent with a JSON body. This returns 400 with a non-JSON body (Request body must encrypted) before the address is even checked. The address is still retired; move to Update a user field value.

Do not retry01

404ROUTE_NOT_FOUNDDo not retry
The address is retired. Call Update a user field value, POST /v1/communities/{communityId}/users/{userId}/user-fields/{fieldIdOrName}/histories, with the same body. meta.replacementRoute names it. This 404 doesn't mean the trader or field is missing.
{
  "meta": {
    "status": "error",
    "statusCode": 404,
    "method": "POST",
    "route": "/v1/communities/{communityId}/user-fields/{fieldIdOrName}/users/{userIdentifier}/histories",
    "attemptedMethod": "POST",
    "documentedRouteId": "user-fields/history/create",
    "documentedRoute": "POST /v1/communities/{communityId}/user-fields/{fieldId}/users/{userId}/histories",
    "replacementRoute": "POST /v1/communities/{communityId}/users/{userId}/user-fields/{fieldIdOrName}/histories",
    "code": "ROUTE_NOT_FOUND"
  },
  "message": "API request rejected error.",
  "detail": "This documented legacy route does not exist.",
  "solution": "Read error detail and try again."
}

Next step#

Update a user field valuePOST/v1/communities/{communityId}/users/{userId}/user-fields/{fieldIdOrName}/historiesThe current write. Same body, such as {"value": "verified", "action": "overwrite"}, with the trader before the field in the path.