# 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. - Endpoint: `DELETE https://api.returning.ai/v1/communities/{communityId}/user-fields/{fieldIdOrName}` - Section: Users and data / User fields - Authentication: `Authorization: Bearer ` (Community API key) - Permission: `userFields` (Shown in the dashboard as "User Fields") - Retries: Read back before retrying; a repeat returns 404 - Guide: hand-written - Verified: live, 2026-09-27 - Last updated: 26 Sep 2026 - Web page: https://docs.returning.ai/api-reference/user-fields/delete-a-user-field-definition ## 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. **Instead:** Use [Update a user field definition](https://docs.returning.ai/api-reference/user-fields/update-a-user-field-definition.md) instead to rename a field or change its type. Deleting and creating it again loses the link to its history. ## Authentication - Header: `Authorization: Bearer ` - Permission: `userFields` 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](https://docs.returning.ai/api-reference/user-fields-user-field-history/get-all-user-field-histories-in-a-community.md) 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 | Name | Type | Required | Description | | --- | --- | --- | --- | | `communityId` | `string` | Yes | Your community's ID. It must be the community that owns your API key. (24 hex characters) | | `fieldIdOrName` | `string` | Yes | The key of the field to delete, or its `_id`. Capitals and spaces are cleaned up as on create, so `PromoCode` finds `promocode`. (Field key or 24-character ID) | ### Headers | Name | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | `string` | Yes | Community API key with `userFields`. (`Bearer `) | ### Example request ```bash curl --request DELETE \ --url https://api.returning.ai/v1/communities/66f000000000000000000010/user-fields/promocode \ --header 'Authorization: Bearer ' ``` ## 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`. **Note:** The definition may also include a `creator` object naming the account that created it. Build against the fields listed here. ### Response fields | Field | Type | Presence | Description | | --- | --- | --- | --- | | `meta` | `object` | always | - | | `meta.status` | `string` | always | `success` | | `meta.statusCode` | `integer` | always | `200` | | `meta.code` | `string` | always | Machine-readable result code. (`USER_FIELD_DELETED`) | | `message` | `string` | always | Human-readable summary. Do not branch on it. | | `data` | `object` | always | The definition as it was just before it was deleted. | | `data._id` | `string` | always | The deleted definition's ID. (`^[0-9a-fA-F]{24}$`) | | `data.name` | `string` | always | The field's display name. | | `data.field` | `string` | always | The field's key. (`a-z`, `0-9`, `_`, `-`) | | `data.type` | `string` | always | The field's type. (`single-line-text`, `multi-line-text`, `numerical`, `date`, `time`, `date-time`, `boolean`, `single-select-dropdown`, `multi-select-dropdown`) | | `data.defaultValue` | `any` | - | The field's default, in its type. `null` when it had none. | | `data.isCustom` | `boolean` | always | Always `true`. Only custom fields can be deleted. | | `data.createdAt` | `string` | always | When the definition was created. | | `data.updatedAt` | `string` | always | When the definition last changed before the delete. | ### Example response (200) ```json { "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 request | Status | Code | What to do | | --- | --- | --- | | 400 | - | `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. | | 401 | `AUTHENTICATION_REQUIRED` | The key is missing, invalid or expired. Send `Authorization: Bearer ` with a current Community API key. | | 403 | `API_KEY_PERMISSION_DENIED` | The key lacks `userFields`. Add the permission in Settings > Integration > API Keys. | | 403 | `API_KEY_COMMUNITY_MISMATCH` | `communityId` is not the community that owns your key. Use your own community's ID. | ### Fix the data | Status | Code | What to do | | --- | --- | --- | | 404 | `USER_FIELD_NOT_FOUND` | 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. | | 409 | `USER_FIELD_DELETE_FORBIDDEN` | The field is built in, such as `email` or `total_xp`. Only fields your community created can be deleted. | | 409 | `USER_FIELD_DELETE_IDENTIFIER_LOCKED` | The field is marked as a user identifier, such as your broker identifier field, and can't be deleted through the API. | | 404 | `COMMUNITY_NOT_FOUND` | The community this key belongs to no longer exists. Contact Returning.AI support. | ### Retry with backoff | Status | Code | What to do | | --- | --- | --- | | 500 | `USER_FIELD_OPERATION_FAILED` | 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. | **Retries:** This endpoint doesn't take an `Idempotency-Key`. Sending the same delete again after it worked returns `404 USER_FIELD_NOT_FOUND`, not `200`. After a timeout or a `500`, read the field with [Get a user field definition](https://docs.returning.ai/api-reference/user-fields/get-a-user-field-definition.md): a `404` means the delete took effect. Use the same key or ID throughout. Over the [rate limit](https://docs.returning.ai/how-it-works.md#rate-limits), requests return `429`; wait for the window to reset, then retry. ## Next step - [Get a user field definition](https://docs.returning.ai/api-reference/user-fields/get-a-user-field-definition.md): `GET /v1/communities/{communityId}/user-fields/{fieldIdOrName}`. Confirm the field is gone. A `404 USER_FIELD_NOT_FOUND` means the delete took effect. - [Find the field's old entries in Get all user field histories in a community](https://docs.returning.ai/api-reference/user-fields-user-field-history/get-all-user-field-histories-in-a-community.md): `GET /v1/communities/{communityId}/user-field-histories`.