Returning.AIDevelopers
v1

API reference / User Fields

.md

Delete a user field definition

Remove one of your custom user fields by its key or ID, so it no longer appears in your field list and can't be written.

Last updated 26 Sep 2026API v1

Method
DELETE
Path
https://api.returning.ai/v1/communities/{communityId}/user-fields/{fieldIdOrName}
Permission
userFields
Retries
Read back before retrying; a repeat returns 404

When to use this

  • A field your integration created is no longer used, such as a promo code field from a finished campaign.
  • You created a field with the wrong key and want to start again with the right one.
  • You clean up test fields before going live.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
userFieldsShown in the dashboard as “User Fields”

Use a Community API key with the userFields permission, and keep it on your server. communityId must be the ID of the community that owns the key.

Behaviour#

Only custom fields can be deleted. Built-in fields, such as email, total_xp and total_coins, return 409 USER_FIELD_DELETE_FORBIDDEN, and a field marked as a user identifier, such as your broker identifier field, returns 409 USER_FIELD_DELETE_IDENTIFIER_LOCKED.

After a delete, the field no longer appears in your field list, and value writes and field history reads that use its key or ID return 404 USER_FIELD_NOT_FOUND.

Traders' history entries for the field are not deleted. They still appear in Get all user field histories in a community and in each trader's list, with fieldType set to null. If you create a field with the same key again, it gets a new _id and starts with an empty history; the old entries stay with the old ID.

Before you delete a field, remove it from anything that still writes to it, such as your own sync jobs or a data workflow.

Request#

Path parameters#

communityId#stringREQUIRED
Your community's ID. It must be the community that owns your API key.

Rule24 hex characters

Eg"66f000000000000000000010"

fieldIdOrName#stringREQUIRED
The key of the field to delete, or its _id. Capitals and spaces are cleaned up as on create, so PromoCode finds promocode.

RuleField key or 24-character ID

Eg"promocode"

Headers#

Authorization#stringREQUIRED
Community API key with userFields.

RuleBearer <API_KEY>

curl --request DELETE \
  --url https://api.returning.ai/v1/communities/66f000000000000000000010/user-fields/promocode \
  --header 'Authorization: Bearer <API_KEY>'

Response#

A 200 returns the definition as it was just before the delete, so you can keep a record of it. Branch on the HTTP status and meta.code, never on message.

meta#objectALWAYS

Eg{ ... }

status#stringALWAYS

Rulesuccess

statusCode#integerALWAYS

Rule200

code#stringALWAYS
Machine-readable result code.

RuleUSER_FIELD_DELETED

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

Eg"Delete user field api success."

data#objectALWAYS
The definition as it was just before it was deleted.

Eg{ ... }

_id#stringALWAYS
The deleted definition's ID.

Rule^[0-9a-fA-F]{24}$

Eg"66f000000000000000000604"

name#stringALWAYS
The field's display name.

Eg"Promo code"

field#stringALWAYS
The field's key.

Rulea-z, 0-9, _, -

Eg"promocode"

type#stringALWAYS
The field's type.

Rulesingle-line-text, multi-line-text, numerical, date, time, date-time, boolean, single-select-dropdown, multi-select-dropdown

Eg"single-line-text"

defaultValue#any
The field's default, in its type. null when it had none.

Egnull

isCustom#booleanALWAYS
Always true. Only custom fields can be deleted.
createdAt#stringALWAYS
When the definition was created.
updatedAt#stringALWAYS
When the definition last changed before the delete.
{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "USER_FIELD_DELETED"
  },
  "message": "Delete user field api success.",
  "data": {
    "_id": "66f000000000000000000604",
    "name": "Promo code",
    "field": "promocode",
    "type": "single-line-text",
    "defaultValue": null,
    "isCustom": true,
    "createdAt": "2026-09-01T08:30:00.000Z",
    "updatedAt": "2026-09-01T08:30:00.000Z"
  }
}

Errors#

Every error carries its code in meta.code, except a fieldIdOrName that isn't a valid key or ID: that returns 400 with a detail object and no code. A 400, 404 or 409 deletes nothing.

Fix the request04

400Fix the request
fieldIdOrName isn't a valid key or ID: after cleanup it must be 1-120 characters of a-z, 0-9, _ and -. detail names the problem. This error has no code. Nothing was deleted.
401AUTHENTICATION_REQUIREDFix the request
The key is missing, invalid or expired. Send Authorization: Bearer <API_KEY> with a current Community API key.
403API_KEY_PERMISSION_DENIEDFix the request
The key lacks userFields. Add the permission in Settings > Integration > API Keys.
403API_KEY_COMMUNITY_MISMATCHFix the request
communityId is not the community that owns your key. Use your own community's ID.

Fix the data04

404USER_FIELD_NOT_FOUNDFix the data
No field in your community has this key or ID. If you were retrying a delete, the field is already gone; treat it as done.
409USER_FIELD_DELETE_FORBIDDENFix the data
The field is built in, such as email or total_xp. Only fields your community created can be deleted.
409USER_FIELD_DELETE_IDENTIFIER_LOCKEDFix the data
The field is marked as a user identifier, such as your broker identifier field, and can't be deleted through the API.
404COMMUNITY_NOT_FOUNDFix the data
The community this key belongs to no longer exists. Contact Returning.AI support.

Retry with backoff01

500USER_FIELD_OPERATION_FAILEDRetry with backoff
At 409, the field changed while your delete ran and nothing was deleted. At 500, the outcome is unclear. Read the field with Get a user field definition: a 404 means it's gone; otherwise send the delete again.
{
  "meta": {
    "status": "error",
    "statusCode": 400
  },
  "message": "Delete user field api validation error.",
  "detail": {
    "fieldIdOrName": "field must use ASCII letters, numbers, \"_\", or \"-\" after normalization."
  },
  "solution": "Check your params in request and try again"
}

Next step#

Get a user field definitionGET/v1/communities/{communityId}/user-fields/{fieldIdOrName}Confirm the field is gone. A 404 USER_FIELD_NOT_FOUND means the delete took effect.