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

Update a form

PATCH /v1/crm-forms/:id

Changes the settings of a saved CRM form: name, fields, CRM binding, responsible users and texts.

Parameters

Parameter Type Required Description
Parameterid (path) Typeinteger Requiredyes DescriptionForm ID. List: GET /v1/crm-forms

Request fields (body)

Pass either a flat body or an object in fields: {"fields":{"name":"Contact form"}}. In a flat body, an array in fields is the list of form fields. Do not combine an object in fields with other top-level properties except updatedTime — this returns 400 INVALID_PARAMS. Bitrix24 validates the form properties and values.

Field Type Required Description
FieldupdatedTime Typestring Requiredyes DescriptionCurrent form version — data.updatedTime from GET /v1/crm-forms/:id or from the response of the previous write
Fieldname Typestring | null Requiredno DescriptionForm name in the forms list
FieldlanguageId Typestring | null Requiredno DescriptionForm language. List: data.languages in GET /v1/crm-forms/configuration
FieldtemplateId Typestring | null Requiredno DescriptionScenario the form was created from. List: List scenarios
Fieldcrm Typeobject Requiredno DescriptionCRM binding
Fieldcrm.entityScheme Typeinteger Requiredno DescriptionScheme of the CRM records the form creates. List: data.entitySchemes in GET /v1/crm-forms/configuration
Fieldappearance Typeobject Requiredno DescriptionAppearance: title, description, button caption buttonCaption and other properties
Fieldfields Typearray | object Requiredno DescriptionForm fields as an array, or a request envelope as an object
Fieldfields[].name Typestring Requiredno DescriptionField name, for example LEAD_NAME. List: GET /v1/crm-forms/entity-fields
Fieldfields[].type Typestring Requiredno DescriptionField type. List: data.fieldTypes in GET /v1/crm-forms/configuration
Fieldfields[].label Typestring Requiredno DescriptionField label in the form
Fieldfields[].required Typeboolean Requiredno DescriptionWhether the field is required for submission. Pass it explicitly: without the flag, true is saved
Fieldfields[].multiple Typeboolean Requiredno DescriptionWhether the field accepts multiple values. Pass it explicitly: without the flag, true is saved
Fieldresponsible Typeobject Requiredno DescriptionUsers responsible for the form results
Fieldresponsible.userIds Typearray of integer Requiredno DescriptionIDs of responsible users. List: GET /v1/users
Fieldagreements Typeobject Requiredno DescriptionAgreement settings in the Bitrix24 format
Fieldsubmission Typeobject Requiredno DescriptionPost-submission settings: texts and redirect URLs on success and on error
Fieldcallback Typeobject Requiredno DescriptionCallback settings
Fieldpayment Typeobject Requiredno DescriptionPayment settings
Fieldbooking Typeobject Requiredno DescriptionBooking settings
FieldpresetFields Typearray Requiredno DescriptionPreset field values
Fielddependencies Typearray Requiredno DescriptionDependencies between fields
Fieldanalytics Typeobject Requiredno DescriptionAnalytics settings
Fieldintegrations Typeobject Requiredno DescriptionIntegration settings
FieldspamProtection Typeobject Requiredno DescriptionSpam protection settings

The Form contract fields reference describes top-level metadata only. Take the names of nested properties and the current section values of a saved form from the full Get a form response. Sections are passed in the Bitrix24 format; Bitrix24 decides which settings can be written.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/crm-forms/91" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "updatedTime": "2026-11-05T08:16:55Z",
    "name": "VIBE-PROBE 777758 flat, companies"
  }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/crm-forms/91" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "updatedTime": "2026-11-05T08:16:55Z",
    "name": "VIBE-PROBE 777758 flat, companies"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-forms/91', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    updatedTime: '2026-11-05T08:16:55Z',
    name: 'VIBE-PROBE 777758 flat, companies',
  }),
})

const { data } = await res.json()
console.log('New version:', data.updatedTime)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-forms/91', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    updatedTime: '2026-11-05T08:16:55Z',
    name: 'VIBE-PROBE 777758 flat, companies',
  }),
})

const { data } = await res.json()

Response fields

HTTP 200. The response is the saved form, re-read after the change. Form properties other than id are present only when this read succeeds.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typeobject DescriptionThe updated form in the same format as Get a form. Top-level property metadata: Form contract fields
Fielddata.id Typeinteger DescriptionForm ID
Fielddata.name Typestring DescriptionForm name
Fielddata.updatedTime Typestring | null DescriptionNew form version. Pass it in the next write request
Fielddata.fields Typearray DescriptionForm fields as saved
Fieldmeta.warnings Typearray DescriptionPresent when the saved state could not be read
Fieldmeta.redacted Typearray of string DescriptionJSON paths where current connection credentials were replaced. Do not save this representation back as a complete configuration

If the write succeeds but the follow-up read fails, the response stays successful: 200 with only data.id and meta.warnings[].code: "CRM_FORM_READBACK_FAILED". Before the next write, re-read the form with GET to obtain its current updatedTime. Do not repeat the successful write.

Response example

The example is abbreviated. Take nested property names and values from the full GET response for your configured form. Form contract fields describes top-level metadata only.

JSON 
{
  "success": true,
  "data": {
    "id": 91,
    "code": "91",
    "name": "VIBE-PROBE 777758 flat, companies",
    "active": false,
    "system": false,
    "createdTime": "2026-11-05T08:16:55Z",
    "updatedTime": "2026-11-05T08:25:29Z",
    "crm": {
      "entityScheme": 1,
      "duplicateMode": "",
      "dealCategoryId": null,
      "dealDuplicateControlEnabled": false,
      "smartProcessCategoryId": null,
      "smartProcessDuplicateControlEnabled": false
    },
    "fields": [
      {
        "name": "LEAD_NAME",
        "type": "string",
        "label": null,
        "sort": 10,
        "required": false,
        "multiple": false,
        "placeholder": null,
        "valueType": null,
        "value": null
      }
    ],
    "agreements": {
      "enabled": false,
      "items": []
    }
  }
}

Error response example

409 — the form changed after it was read; the passed updatedTime is outdated:

JSON 
{
  "success": false,
  "error": {
    "code": "CRM_FORM_VERSION_MISMATCH",
    "message": "The CRM form version is outdated. Changes were not saved. Get the form again and retry the request",
    "b24Code": "CRM_FORM_VERSION_MISMATCH",
    "currentUpdatedTime": "2026-11-05T08:25:30Z"
  }
}

Errors

HTTP Code Description
HTTP409 CodeCRM_FORM_VERSION_MISMATCH DescriptionupdatedTime does not match the current form version. Changes were not saved; the current version is in error.currentUpdatedTime
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo form with this id
HTTP400 CodeINVALID_PARAMS DescriptionThe body has no updatedTime
HTTP400 CodeINVALID_PARAMS Descriptionid is not a positive integer, the body is not a JSON object, the body formats are mixed, or a query string parameter was passed
HTTP402 CodeCRM_FORM_WRITE_RESTRICTED DescriptionThe Bitrix24 plan (free or demo) does not allow writing CRM forms
HTTP403 CodeCRM_FORM_SYSTEM_IMMUTABLE DescriptionThe form is a system form; its settings cannot be changed
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only. A key with write access is required
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: the user has no permission to change CRM forms
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the crm scope
HTTP401 CodeMISSING_API_KEY DescriptionX-Api-Key was not passed
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 access tokens
HTTP422 CodeBITRIX_ERROR DescriptionAnother Bitrix24 refusal. The original message is kept in error.message
HTTP500 CodeCRM_FORM_SIDE_EFFECT_FAILED DescriptionThe changes are already written, but a subsequent step on the Bitrix24 side failed. Read the form before retrying
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a malformed response. The changes may have been saved — read the form before retrying

Bitrix24 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. Common 429, 502 and 503 responses: Limits and optimization. Full list of common API errors: Errors.

Known specifics

Partial update. Properties absent from the body stay unchanged. A passed array or object replaces the previous one entirely: to add one form field, pass all fields in fields together with the new one. An empty array clears the collection; null on a scalar property clears its value.

See also