Delete A User Field Definition

What this endpoint does

Deletes one custom user-field definition by stable key or ObjectId. Use it only after confirming that no integration depends on the field. Built-in definitions are protected. Deleting a definition does not mean every historical row or external reference has disappeared.

INFO

Workflow

Field -> delete -> confirm absence

Quick start

There is no request body.

Authentication and permission

Use a community API key with userFields. The caller must be a community owner or administrator. The path accepts the stable key or 24-character field ObjectId.

Complete examples

Delete by stable key:

Expected response:

{
  "meta": { "status": "success", "statusCode": 200, "code": "USER_FIELD_DELETED" },
  "message": "Delete user field api success.",
  "data": {
    "_id": "<fieldObjectId>",
    "name": "Trading Volume",
    "field": "trading_volume",
    "type": "numerical",
    "defaultValue": 0,
    "isCustom": true
  }
}

Before deletion, search integration configuration, imports, reporting, webhooks, and stored client mappings for both the stable key and ObjectId.

Success and readback

After a 200, call GET for the same definition. A 404 USER_FIELD_NOT_FOUND confirms the definition is absent. If history retention matters, query the relevant history scope separately; the definition readback alone does not prove history deletion.

CHECK

Readback

Run the follow-up read named above. Compare the returned identifiers and final stored values.

Errors and recovery

400 INVALID_COMMUNITY_ID or INVALID_FIELD_IDENTIFIER: correct the path.

401 AUTHENTICATION_REQUIRED / 403 API_KEY_PERMISSION_DENIED: fix key or owner/admin access.

404 USER_FIELD_NOT_FOUND: the definition is already absent or the identifier is wrong. Re-list fields.

409 USER_FIELD_DELETE_FORBIDDEN: built-in/protected definition cannot be removed.

500 USER_FIELD_OPERATION_FAILED: read back before repeating the deletion.

Retry safety

WARNING

Retry rule

DELETE is not an unconditional idempotent success contract. After a timeout, GET the field first. If it is absent, treat the desired state as achieved. If it remains, retry the same path with bounded backoff. Do not switch between key and ObjectId mid-reconciliation.

Gotchas

Avoid this mistake

Next steps

Continue with user data

GET the same path to confirm absence, then list all definitions to refresh integration configuration. If replacing the field, create the new definition deliberately and migrate writers/readers before retiring the old key.

application/json

Delete user field api success. Branch on the HTTP status and meta.code; do not branch on the human-readable message.

Bodyapplication/json

{ "meta": { "status": "success", "statusCode": 200, "code": "USER_FIELD_DELETED" }, "message": "Delete user field api success.", "data": { "_id": "66f000000000000000000010", "name": "Trading Volume", "field": "trading_volume", "type": "numerical", "defaultValue": 0, "isCustom": true } }

Delete A User Field Definition

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps

Request

Responses

Delete A User Field Definition

What this endpoint does#

Quick start#

Authentication and permission#

Complete examples#

Success and readback#

Errors and recovery#

Retry safety#

Gotchas#

Next steps#

Request

Responses

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps