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
Parameter:id (path) Typenumber Requiredyes DescriptionNumeric 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
HTTP400 CodeINVALID_ID Description:id is not a positive integer — the request is rejected before the portal is contacted
HTTP404 CodeENTITY_NOT_FOUND DescriptionThere is no field with this id — including a repeated DELETE after a successful deletion
HTTP422 CodeBITRIX_ERROR DescriptionThe key owner is not a Bitrix24 account administrator — Bitrix24 responds with the message Access denied.
HTTP422 CodeBITRIX_ERROR DescriptionOther Bitrix24 rejections — including a field removed between the existence check and the deletion itself. The text is returned verbatim in error.message
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the user.userfield scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP401 CodeMISSING_API_KEY DescriptionThe 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