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

Delete field

DELETE /v1/items/:entityTypeId/userfields/:id

Deletes a smart process user field along with all of its values in items. A deleted field cannot be restored via the API — create a new one if needed.

Parameters

Parameter Type Required Description
Parameter:entityTypeId (path) Typenumber Requiredyes DescriptionSmart process type identifier. Source: GET /v1/smart-processes — the entityTypeId field on each element of the data array
Parameter:id (path) Typenumber Requiredyes DescriptionNumeric field identifier (from the response of GET /v1/items/:entityTypeId/userfields or POST /v1/items/:entityTypeId/userfields)

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/items/174/userfields/8210" \
  -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/items/174/userfields/8210',
  {
    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/items/174/userfields/8210',
  {
    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, an HTTP 204 No Content status is returned with an empty body. The success indicator is the response code, not the body.

Response example

http 
HTTP/1.1 204 No Content

Error response example

403 — the key has no userfieldconfig scope:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ACCESS_DENIED",
    "message": "The request requires higher privileges than provided by the webhook token"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_ENTITY_TYPE_ID Description:entityTypeId is not a positive integer
HTTP400 CodeINVALID_PARAMS Description:id is not a positive integer or exceeds 9007199254740991. The value must contain digits only, with no leading zero, sign, fractional part, exponent or spaces. The field is not deleted
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key has no userfieldconfig scope — reissue the key with this scope
HTTP403 CodeSCOPE_DENIED DescriptionThe API key has no crm scope
HTTP404 CodeSMART_PROCESS_NOT_FOUND DescriptionA smart process with the given entityTypeId was not found on the portal
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe smart process in the path has no field with the given id: the field is already deleted or belongs to another entity. Nothing is deleted
HTTP422 CodeBITRIX_ERROR DescriptionThe field was deleted between the check and the deletion — Bitrix24 responds "You cannot delete the user field"
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 items are deleted permanently. When a field is deleted, all of its values in existing smart process items are lost. If the field is used in automations, automation rules, or integrations, check the dependencies before deleting.

Only a field of the smart process in the path is deleted. Field IDs are shared across all entities of the Bitrix24 account, so before deleting, the platform checks that the smart process :entityTypeId has a field with this id. A field of another entity is not deleted; the response is 404 ENTITY_NOT_FOUND.

Repeated deletion. A repeated DELETE on the same id returns 404 ENTITY_NOT_FOUND: the field is already deleted.

See also