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

Create a form

POST /v1/crm-forms

Creates a CRM form with fields, a CRM binding, responsible users and result texts.

Request fields (body)

Pass either a flat body or an object in fields: {"fields":{"name":"VIBE-PROBE 777758 parity"}}. 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.

Before creating, you can check a draft without saving it: Validate a form.

Field Type Required Description
Fieldname Typestring Requiredyes DescriptionForm name in the forms list
Fieldcrm Typeobject Requiredyes DescriptionCRM binding. Take nested settings from the configuration of a specific form
Fieldcrm.entityScheme Typeinteger Requiredyes 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. Defaults to true. The state also has dedicated operations: activation and deactivation
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 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. To create a form based on an existing one, take the names of nested properties and the initial section values 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 POST "https://vibecode.bitrix24.com/v1/crm-forms" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIBE-PROBE 777758 parity",
    "active": false,
    "crm": { "entityScheme": 1 },
    "fields": [
      { "name": "LEAD_NAME", "type": "string", "required": false, "multiple": false }
    ]
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-forms" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIBE-PROBE 777758 parity",
    "active": false,
    "crm": { "entityScheme": 1 },
    "fields": [
      { "name": "LEAD_NAME", "type": "string", "required": false, "multiple": false }
    ]
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-forms', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'VIBE-PROBE 777758 parity',
    active: false,
    crm: { entityScheme: 1 },
    fields: [
      { name: 'LEAD_NAME', type: 'string', required: false, multiple: false },
    ],
  }),
})

const { data } = await res.json()
console.log('Form ID:', data.id, 'updatedTime:', data.updatedTime)

JavaScript — OAuth application

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

const { data } = await res.json()

Response fields

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

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typeobject DescriptionThe created form in the same format as Get a form. Top-level property metadata: Form contract fields
Fielddata.id Typeinteger DescriptionID of the created form
Fielddata.name Typestring DescriptionForm name
Fielddata.active Typeboolean | null DescriptionWhether the form is enabled
Fielddata.updatedTime Typestring | null DescriptionTime of the last change. Passed to PATCH /v1/crm-forms/:id
Fielddata.fields Typearray DescriptionForm fields as saved, including required and multiple
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: 201 with only data.id and meta.warnings[].code: "CRM_FORM_READBACK_FAILED". GET the form before another write 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 parity",
    "active": false,
    "system": false,
    "createdTime": "2026-11-05T08:16:55Z",
    "updatedTime": "2026-11-05T08:16:55Z",
    "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

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
HTTP400 CodeINVALID_PARAMS DescriptionThe body is not a JSON object, or a query string parameter was passed
HTTP400 CodeINVALID_PARAMS DescriptionBitrix24 rejected the configuration, for example crm.entityScheme was not passed. Violations are listed in error.validation
HTTP400 CodeCRM_FORM_PARTIALLY_CREATED DescriptionThe form exists: error.id is its ID, error.b24Code is the original error code, and error.validation describes failed sections. GET the form, then correct or delete it. Do not repeat creation
HTTP402 CodeCRM_FORM_WRITE_RESTRICTED DescriptionThe Bitrix24 plan (free or demo) does not allow writing CRM forms
HTTP402 CodeCRM_FORM_ACTIVATION_LIMIT_REACHED DescriptionThe form is created as enabled, and the active form limit is reached. The limit is data.limits.activeForms in GET /v1/crm-forms/configuration
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
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 did not find the requested entity or field descriptor. The original code is in error.b24Code
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
HTTP500 CodeCRM_FORM_SIDE_EFFECT_FAILED DescriptionThe form is already saved, but a subsequent step on the Bitrix24 side failed. error.id is the ID of the created form. Read the form before retrying
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a malformed response. The form may already be created — find it in the forms list 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.

See also