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

Delete a form

DELETE /v1/crm-forms/:id

Deletes a CRM form by ID together with its settings. A deleted form cannot be restored through the API — create a new one if needed.

Parameters

Parameter Type Required Default Description
Parameterid (path) Typeinteger Requiredyes Default— DescriptionForm ID. List: GET /v1/crm-forms
Parameterconfirm (query) Typeboolean Requiredno Defaultfalse Descriptiontrue confirms deletion of an active form. Without confirmation, an active form is not deleted — the response is 409 CRM_FORM_DELETE_CONFIRMATION_REQUIRED. A deactivated form can be deleted without confirm. Accepts only true or false
Parameterconfirmed (query) Typeboolean Requiredno Default— DescriptionAlias of confirm. If both are supplied, their values must match, otherwise 400 INVALID_PARAMS
ParameterupdatedTime (query) Typestring Requiredno Default— DescriptionLast modification time of the form from GET /v1/crm-forms/:id. If the form was modified after this time, deletion is rejected with 409 CRM_FORM_VERSION_MISMATCH. Without the parameter, no version check is performed

Any other query string parameter and any body field return 400 INVALID_PARAMS. No request body is sent.

Bitrix24 validates the type and value of updatedTime. Use the version from the form read response; a local refusal for an invalid type is not guaranteed.

Examples

curl — personal key

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/crm-forms/75?confirm=true" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/crm-forms/75?confirm=true" \
  -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/crm-forms/75?confirm=true', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})
const body = await res.json()
if (body.success && body.data.deleted) {
  console.log('Form deleted')
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-forms/75?confirm=true', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const body = await res.json()
if (body.success && body.data.deleted) {
  console.log('Form deleted')
}

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on successful deletion
Fielddata.deleted Typeboolean DescriptionAlways true: the form is deleted

Response example

HTTP status 200 OK:

JSON 
{
  "success": true,
  "data": {
    "deleted": true
  }
}

Error response example

409 — the form is active and deletion was not confirmed:

JSON 
{
  "success": false,
  "error": {
    "code": "CRM_FORM_DELETE_CONFIRMATION_REQUIRED",
    "message": "The CRM form is active: confirm deletion and retry the request",
    "b24Code": "CRM_FORM_DELETE_CONFIRMATION_REQUIRED"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS Descriptionid is not a positive integer, a query string parameter other than confirm, confirmed and updatedTime was passed, confirm, confirmed or updatedTime was repeated, the confirmation values conflict, confirm is neither true nor false, or a body field was passed
HTTP400 CodeFST_ERR_CTP_EMPTY_JSON_BODY DescriptionThe Content-Type: application/json header was passed with an empty body. Remove the header
HTTP402 CodeCRM_FORM_WRITE_RESTRICTED DescriptionThe Bitrix24 plan does not allow writing CRM forms. Writes are not performed on free and demo plans
HTTP403 CodeCRM_FORM_SYSTEM_IMMUTABLE DescriptionThe form is a system form — system: true in the form list. A system form cannot be deleted
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo form with this id, including when the same form is deleted again
HTTP409 CodeCRM_FORM_DELETE_CONFIRMATION_REQUIRED DescriptionThe form is active and deletion was not confirmed
HTTP409 CodeCRM_FORM_VERSION_MISMATCH DescriptionThe form was modified after the passed updatedTime. The current modification time is in error.currentUpdatedTime
HTTP403 CodeBITRIX_INSUFFICIENT_SCOPE DescriptionThe Bitrix24 token lacks the required scope
HTTP409 CodeCRM_FORM_REST_NOT_ENABLED DescriptionThe CRM form methods are disabled on the Bitrix24 account
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access to the form for the key's user
HTTP422 CodeBITRIX_ERROR DescriptionAnother Bitrix24 rejection. The rejection text is in error.message
HTTP500 CodeCRM_FORM_SIDE_EFFECT_FAILED DescriptionThe deletion was performed but completed with an error. Check the form with GET /v1/crm-forms/:id before retrying
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a response of an unexpected shape. Check the form before retrying
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the crm scope
HTTP401 CodeMISSING_API_KEY DescriptionX-Api-Key is missing
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no valid Bitrix24 authorization

Upstream errors include the original code in error.b24Code and field violations in error.validation when provided. CRM_FORM_* codes retain their HTTP status, code and message. 429 and 503 responses are described in Limits and optimization. For the full list of common API errors, see Errors.

Known specifics

  • Deactivate instead of deleting. To stop a form from working while keeping its settings, deactivate it — a deactivated form can be activated again.

See also