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

Delete field

DELETE /v1/userfields/tasks/:id

Deletes a task user field together with its list options and its values in all tasks of the Bitrix24 account. The field and its values cannot be restored via the API.

Parameters

Parameter Type Required Description
Parameter:id (path) Typenumber Requiredyes DescriptionNumeric identifier of the field from the response of GET /v1/userfields/tasks or POST /v1/userfields/tasks

Examples

curl — personal key

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

curl — OAuth application

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

Response example

http 
HTTP/1.1 204 No Content

Error response example

404 — there is no field with this id, including after a successful deletion:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Task custom field not found"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_ID Description:id is not a positive integer — the request is rejected before it reaches Bitrix24
HTTP404 CodeENTITY_NOT_FOUND DescriptionThere is no field with this id — including a repeated DELETE after a successful deletion — or it belongs to another entity
HTTP403 CodeSYSTEM_FIELD_PROTECTED DescriptionSystem field UF_CRM_TASK, UF_TASK_WEBDAV_FILES, or UF_MAIL_MESSAGE
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key owner is not a Bitrix24 account administrator
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP403 CodeTASK_CUSTOM_FIELDS_UNAVAILABLE DescriptionThe portal plan does not include task user fields
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the task scope
HTTP502 CodeTASK_USERFIELD_OUTCOME_UNKNOWN DescriptionThe connection to Bitrix24 dropped, or Bitrix24 returned a server error during the deletion — whether the field was deleted is unknown. The request was not retried automatically: read the field by id before deleting it again
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 tokens. For an application key, the Authorization: Bearer USER_SESSION_TOKEN header was not passed
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing

Full list of common API errors — Errors.

Known specifics

Recreating the field does not bring its values back. After deletion, the field disappears from tasks: GET /v1/tasks/:id no longer returns it. A field created again with the same fieldName is empty in tasks — the previous values are not restored.

See also