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

Validate a form

POST /v1/crm-forms/validate

POST /v1/crm-forms/:id/validate

Checks a CRM form configuration without saving it and returns a list of violations. The first path checks a draft of a new form, the second checks changes to the saved form with the given ID.

Parameters

Parameter Type Required Description
Parameterid (path) Typeinteger Requiredno DescriptionID of a saved form — only for the POST /v1/crm-forms/:id/validate path. List: GET /v1/crm-forms

Request fields (body)

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

The body takes the same properties as form creation and update. For a draft, pass the whole configuration. For a saved form, pass only the properties being changed, without updatedTime. An empty object {} checks the form as saved.

Field Type Required Description
Fieldname Typestring | null Requiredno DescriptionForm name. A draft without name gets a violation on this field
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
Fieldactive Typeboolean Requiredno DescriptionWhether the form is enabled. Bitrix24 validates whether this property is allowed
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
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 set on save
Fieldfields[].multiple Typeboolean Requiredno DescriptionWhether the field accepts multiple values. Pass it explicitly: without the flag, true is set on save
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 schema
Fieldsubmission Typeobject Requiredno DescriptionPost-submission settings.
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. For a saved form, take nested property names and the current section values from the full Get a form response. Sections are passed in the Bitrix24 schema; Bitrix24 decides which settings can be written.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-forms/validate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Feedback form",
    "crm": { "entityScheme": 1 },
    "fields": [
      { "name": "LEAD_NAME", "type": "string", "label": "Name", "required": false, "multiple": false },
      { "name": "LEAD_PHONE", "type": "phone", "label": "Phone", "required": false, "multiple": false }
    ]
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-forms/validate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Feedback form",
    "crm": { "entityScheme": 1 },
    "fields": [
      { "name": "LEAD_NAME", "type": "string", "label": "Name", "required": false, "multiple": false },
      { "name": "LEAD_PHONE", "type": "phone", "label": "Phone", "required": false, "multiple": false }
    ]
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-forms/validate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Feedback form',
    crm: { entityScheme: 1 },
    fields: [
      { name: 'LEAD_NAME', type: 'string', label: 'Name', required: false, multiple: false },
      { name: 'LEAD_PHONE', type: 'phone', label: 'Phone', required: false, multiple: false },
    ],
  }),
})

const { data } = await res.json()
if (!data.valid) console.log('Violations:', data.violations)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-forms/validate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Feedback form',
    crm: { entityScheme: 1 },
    fields: [
      { name: 'LEAD_NAME', type: 'string', label: 'Name', required: false, multiple: false },
      { name: 'LEAD_PHONE', type: 'phone', label: 'Phone', required: false, multiple: false },
    ],
  }),
})

const { data } = await res.json()

Response fields

HTTP 200 on both paths, including when the check fails.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue — the check was performed. The check result is in data.valid
Fielddata.valid Typeboolean Descriptiontrue — no violations, false — the configuration needs fixing
Fielddata.violations Typearray DescriptionViolations. An empty array when valid: true
Fielddata.violations[].field Typestring DescriptionPath to the property with the violation, for example name
Fielddata.violations[].message Typestring DescriptionViolation text
Fieldmeta.redacted Typearray of string DescriptionJSON paths where the current connection's credentials were replaced

Response example

No violations:

JSON 
{
  "success": true,
  "data": {
    "valid": true,
    "violations": []
  }
}

The check failed — the draft has no name:

JSON 
{
  "success": true,
  "data": {
    "valid": false,
    "violations": [
      {
        "field": "name",
        "message": "Name of the CRM form is required"
      }
    ]
  }
}

Error response example

400 — an object in fields is combined with another top-level property:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Use either a flat body or {fields:{...}}"
  }
}

Errors

HTTP Code Description
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 did not find a requested entity or field descriptor. The original code is in error.b24Code
HTTP400 CodeINVALID_PARAMS Descriptionid is not a positive integer, the body is not a JSON object, or a query string parameter was passed
HTTP403 CodeCRM_FORM_SYSTEM_IMMUTABLE DescriptionPath with id only: the form is a system form; its settings cannot be changed
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 DescriptionAny other Bitrix24 refusal. The original message is kept in error.message
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a malformed response

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

Works with a read-only key. The check saves nothing and does not change the form's updatedTime, so a read-only key can call it too.

See also