Returning.AIDocs
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 28 Oct 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.

Retries

Don't retry. This address never succeeds, however often you call it or with whatever key. Move the call to Update a user field value instead.

{
  "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.