For AI agents: markdown of this page — /docs-content-en/userfields/users/delete.md documentation index — /llms.txt

Delete employee field

DELETE /v1/userfields/users/:id

Deletes an employee user field together with all its values in employee cards. A deleted field cannot be restored via the API — create a new one if needed.

Parameters

Parameter Type Required Description
:id (path) number yes Numeric identifier of the field (from the response of GET /v1/userfields/users or POST /v1/userfields/users)

Examples

curl — personal key

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/userfields/users/6007923" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/userfields/users/6007923" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/userfields/users/6007923', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

if (res.status === 204) {
  console.log('Field deleted')
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/userfields/users/6007923', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

if (res.status === 204) {
  console.log('Field deleted')
}

Response

On successful deletion, the API returns HTTP status 204 No Content with an empty body. Success is indicated by the response code, not the body.

Response example

http 
HTTP/1.1 204 No Content

Error response example

404 — there is no field with this id:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "User field 999999999 not found"
  }
}

Errors

HTTP Code Description
400 INVALID_ID :id is not a positive integer — the request is rejected before the portal is contacted
404 ENTITY_NOT_FOUND There is no field with this id — including a repeated DELETE after a successful deletion
422 BITRIX_ERROR The key owner is not a Bitrix24 account administrator — Bitrix24 responds with the message Access denied.
422 BITRIX_ERROR Other Bitrix24 rejections — including a field removed between the existence check and the deletion itself. The text is returned verbatim in error.message
403 SCOPE_DENIED The API key does not have the user.userfield scope
401 TOKEN_MISSING The API key has no configured tokens
401 MISSING_API_KEY The X-Api-Key header is missing

Full list of common API errors — Errors.

Known specifics

Values in employee cards are deleted irreversibly. When a field is deleted, all of its values for employees are lost. If the field is used in workflows or integrations, check the dependencies before deleting.

The field disappears from the employee schema immediately. After deletion, the UF_USR_* name disappears from GET /v1/users/fields without delay, and GET /v1/userfields/users/:id for the former id returns 404 NOT_FOUND. A repeated DELETE on the same id returns 404 ENTITY_NOT_FOUND.

See also