CRM forms

Read and configure CRM forms, publish them on a website and submit visitor data to them.

Scope: crm | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

Documentation sections

• Form management — create, read, update, validate, activate and delete forms
• Builder dictionaries — form properties, CRM entity fields, Bitrix24 account settings and scenarios
• Publishing and results — embedding code, website widgets, Open Channels and visitor data submission

Key fields

To read a full form or select specific properties, see Get a form. Form contract fields lists top-level metadata only. Take nested property names and values from the full GET response for your configured form.

What to know before you start

1. A read-only key can use GET requests and both form validations — POST /v1/crm-forms/validate and POST /v1/crm-forms/:id/validate. Creating, updating, activating or deactivating, deleting and submitting visitor data require a key with write access. Submitting visitor data can create CRM records and trigger automation and notifications.
2. Without filters, the list includes active and inactive forms and returns one page. By default, it returns 11 scalar fields. Use select, for example id,name,crm.entityScheme,responsible.userIds,updatedTime, to request sections or subfields. Bitrix24 validates filters, sorting and pagination.
3. A full form contains the 11 scalar fields and 14 configuration sections, including analytics, integrations and spamProtection. The object is passed through without rebuilding agreements, adding top-level aliases or filling missing fields. An explicit select can return a partial object without id, name or fields.
4. User content, public URLs and embedding signatures are preserved. Only credentials for the current Bitrix24 connection are replaced, with affected paths in meta.redacted. Such a response is not a complete configuration for saving back. Credentials are always hidden in errors and logs.
5. For an update, first read the form and keep updatedTime. Activate and deactivate return the actual active and updatedTime, including the unchanged version when no write was needed. If the additional read after a confirmed create or update fails, the response remains successful with data.id and meta.warnings. Read the form before the next write, without repeating the successful operation.
6. Create, update, validate and embedding-update requests accept a flat body or an object-valued fields wrapper. For versioned updates, keep updatedTime at the root. The form's own fields array remains a form property. Bitrix24 validates settings and business rules.
7. CRM_FORM_PARTIALLY_CREATED is an error: the form already exists; its ID is in error.id. GET the form, then correct or delete it. Do not repeat creation. There is no automatic deletion or retry.

Limits

Quick start

Get the first two forms in your Bitrix24 account:

curl 'https://vibecode.bitrix24.com/v1/crm-forms?limit=2' \
  -H 'X-Api-Key: YOUR_API_KEY'

{
  "success": true,
  "data": [
    {
      "id": 1,
      "code": "1_kontaktnye_dannye",
      "name": "Contact details",
      "active": true,
      "system": true,
      "languageId": "ru",
      "templateId": "light",
      "createdTime": "2020-04-22T06:13:05Z",
      "updatedTime": "2020-04-22T06:13:05Z",
      "activeChangedById": 1,
      "activeChangedTime": "2020-04-22T06:13:05Z"
    },
    {
      "id": 3,
      "code": "3_obratnaya_svyaz",
      "name": "Feedback form",
      "active": true,
      "system": true,
      "languageId": "ru",
      "templateId": "light",
      "createdTime": "2020-04-22T06:13:05Z",
      "updatedTime": "2020-04-22T06:13:05Z",
      "activeChangedById": 1,
      "activeChangedTime": "2020-04-22T06:13:05Z"
    }
  ]
}

Live response from a Russian-language portal: code and languageId are portal values returned as stored. code is the exact value for the ?code= filter, and another portal has its own codes. Only the display name appears here in English.

Full example

Validate a draft, create an inactive form, activate it, submit visitor data, deactivate it and delete it.

1. Validate the draft without saving it:

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":"Contact form","crm":{"entityScheme":1},"fields":[{"name":"LEAD_NAME","type":"string","label":"Name","required":true,"multiple":false},{"name":"LEAD_PHONE","type":"phone","label":"Phone","required":false,"multiple":false}]}'

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

2. Create the form inactive — with the same body plus "active":false:

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

The 201 response contains the saved form, or data.id with meta.warnings if the additional read failed. Keep data.id, which is 87 in this example. A warning does not mean creation failed: GET the form instead of repeating POST. If creation returns CRM_FORM_PARTIALLY_CREATED, use error.id to read and correct or delete the existing form, without repeating creation.

3. Activate the form:

curl -X POST 'https://vibecode.bitrix24.com/v1/crm-forms/87/activate' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

{ "success": true, "data": { "active": true, "updatedTime": "2026-10-27T13:48:44Z" } }

4. Submit visitor data:

curl -X POST 'https://vibecode.bitrix24.com/v1/crm-forms/87/results' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"fields":{"LEAD_NAME":"Anna","LEAD_PHONE":"+12025550123"},"fromUrl":"https://example.com/contact"}'

{ "success": true, "data": { "resultId": 235 } }

5. Deactivate the form:

curl -X POST 'https://vibecode.bitrix24.com/v1/crm-forms/87/deactivate' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

{ "success": true, "data": { "active": false, "updatedTime": "2026-10-27T13:48:46Z" } }

6. Delete the form. An inactive form is deleted without confirm:

curl -X DELETE 'https://vibecode.bitrix24.com/v1/crm-forms/87' \
  -H 'X-Api-Key: YOUR_API_KEY'

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

Endpoint reference

The PRD name crm.form.embed.get maps to crm.form.embedding.get. The PRD name crm.form.fields.get for fields of selected CRM entities maps to crm.form.entityfield.list. crm.form.field.list and crm.form.field.get describe the form model itself. Visitor submissions use REST v2 and are separate from these REST v3 methods.

Error codes

CRM form errors

System errors

Full list of common API errors — Errors.

See also

• Open Channels
• Leads
• Users
• API reference