Dành cho AI agent: markdown của trang này — /docs-content-en/entities/crm-forms/builder.md chỉ mục tài liệu — /llms.txt
Hiện tại, các bài viết trong tài liệu chỉ có bằng tiếng Anh.
Builder dictionaries
Find out which form properties the API exposes, which CRM entity fields you can add to a form, and which settings and scenarios are available in the Bitrix24 account. The methods in this group only read data.
Bitrix24 API: crm.form.field.*, crm.form.configuration.get, crm.form.entityfield.list, crm.form.scenario.list, crm.form.scenariocategory.list
Scope: crm
Form contract fields
GET /v1/crm-forms/fields
Returns the schema of top-level CRM form properties. Use it to check which configuration blocks belong to the form contract before you create or update a form.
Parameters
| Parameter | Type | Description |
|---|---|---|
Parameterselect (query) |
Typestring | DescriptionComma-separated metadata properties, for example name,type,multiple. Without it, all metadata properties are returned |
Examples
curl — personal key
curl "https://vibecode.bitrix24.com/v1/crm-forms/fields" \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth application
curl "https://vibecode.bitrix24.com/v1/crm-forms/fields" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN"
JavaScript — personal key
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-forms/fields', {
headers: {
'X-Api-Key': 'YOUR_API_KEY',
},
})
const { success, data } = await res.json()
console.log('Form properties:', data.length)
JavaScript — OAuth application
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-forms/fields', {
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
},
})
const { success, data } = await res.json()
Response fields
| Field | Type | Description |
|---|---|---|
Fieldsuccess |
Typeboolean | DescriptionAlways true on success |
Fielddata |
Typearray | DescriptionForm property descriptions. The property set is in the table below |
Fielddata[].name |
Typestring | DescriptionForm property name |
Fielddata[].type |
Typestring | DescriptionValue type: int, string, bool, date-time or object |
Fielddata[].elementType |
Typestring | null | DescriptionElement type of a multi-value property, for example object. null for single-value properties |
Fielddata[].multiple |
Typeboolean | Descriptiontrue — the property value is an array |
Fielddata[].title |
Typestring | DescriptionProperty label. Matches name |
Fielddata[].description |
Typestring | null | DescriptionProperty description |
Fielddata[].validationRules |
Typearray | DescriptionValue validation rules |
Fielddata[].requiredGroups |
Typearray | null | DescriptionRequired groups |
Fielddata[].filterable |
Typeboolean | DescriptionWhether the property is marked as filterable |
Fielddata[].sortable |
Typeboolean | DescriptionWhether the property is marked as sortable |
Fielddata[].editable |
Typeboolean | DescriptionEditability flag from the schema. It is false for every property. Bitrix24 validates writable properties when a form is saved |
Form properties in data:
| Field | Type | RO | Description |
|---|---|---|---|
Fieldid |
Typeint | ROyes | DescriptionForm ID. List: GET /v1/crm-forms |
Fieldcode |
Typestring | ROyes | DescriptionForm symbolic code |
Fieldname |
Typestring | RO | DescriptionForm name |
Fieldactive |
Typebool | RO | DescriptionWhether the form is enabled. Accepted only on create. For an existing form, change it through activation and deactivation |
Fieldsystem |
Typebool | ROyes | DescriptionSystem form |
FieldlanguageId |
Typestring | RO | DescriptionForm language. List: data.languages[].id in the builder configuration |
FieldtemplateId |
Typestring | RO | DescriptionForm template |
FieldcreatedTime |
Typedate-time | ROyes | DescriptionCreation time |
FieldupdatedTime |
Typedate-time | ROyes | DescriptionLast modification time. Pass it to form update as a version that protects against overwriting other users' changes |
FieldactiveChangedById |
Typeint | ROyes | DescriptionID of the user who last changed the active state. List: GET /v1/users |
FieldactiveChangedTime |
Typedate-time | ROyes | DescriptionWhen the active state last changed |
Fieldappearance |
Typeobject | RO | DescriptionAppearance: title, description, button caption and colors |
Fieldcrm |
Typeobject | RO | DescriptionCRM binding: entity scheme, duplicate mode, funnel. Values are in the builder configuration |
Fielddependencies |
Typeobject | RO | DescriptionArray of field dependency rules, multiple: true |
FieldpresetFields |
Typeobject | RO | DescriptionArray of preset field values, multiple: true |
Fieldresponsible |
Typeobject | RO | DescriptionUsers responsible for form results and work time tracking. Responsible user IDs come from GET /v1/users |
Fieldagreements |
Typeobject | RO | DescriptionAgreements the visitor accepts on submission |
Fieldsubmission |
Typeobject | RO | DescriptionActions after submission: texts and redirect URLs on success and on error |
Fieldpayment |
Typeobject | RO | DescriptionPayment settings |
Fieldcallback |
Typeobject | RO | DescriptionCallback settings |
Fieldbooking |
Typeobject | RO | DescriptionBooking settings |
Fieldanalytics |
Typeobject | RO | DescriptionAnalytics settings |
FieldspamProtection |
Typeobject | RO | DescriptionSpam protection settings |
Fieldintegrations |
Typeobject | RO | DescriptionIntegration settings |
Fieldfields |
Typeobject | RO | DescriptionArray of form fields, multiple: true. Field names come from GET /v1/crm-forms/entity-fields |
Response example
{
"success": true,
"data": [
{"name": "id", "type": "int", "elementType": null, "multiple": false, "title": "id", "description": null, "validationRules": [], "requiredGroups": null, "filterable": true, "sortable": true, "editable": false},
{"name": "code", "type": "string", "elementType": null, "multiple": false, "title": "code", "description": null, "validationRules": [], "requiredGroups": null, "filterable": true, "sortable": false, "editable": false},
{"name": "name", "type": "string", "elementType": null, "multiple": false, "title": "name", "description": null, "validationRules": [], "requiredGroups": null, "filterable": true, "sortable": true, "editable": false},
{"name": "active", "type": "bool", "elementType": null, "multiple": false, "title": "active", "description": null, "validationRules": [], "requiredGroups": null, "filterable": true, "sortable": true, "editable": false},
{"name": "system", "type": "bool", "elementType": null, "multiple": false, "title": "system", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
{"name": "languageId", "type": "string", "elementType": null, "multiple": false, "title": "languageId", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
{"name": "templateId", "type": "string", "elementType": null, "multiple": false, "title": "templateId", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
{"name": "createdTime", "type": "date-time", "elementType": null, "multiple": false, "title": "createdTime", "description": null, "validationRules": [], "requiredGroups": null, "filterable": true, "sortable": true, "editable": false},
{"name": "updatedTime", "type": "date-time", "elementType": null, "multiple": false, "title": "updatedTime", "description": null, "validationRules": [], "requiredGroups": null, "filterable": true, "sortable": true, "editable": false},
{"name": "activeChangedById", "type": "int", "elementType": null, "multiple": false, "title": "activeChangedById", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
{"name": "activeChangedTime", "type": "date-time", "elementType": null, "multiple": false, "title": "activeChangedTime", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
{"name": "appearance", "type": "object", "elementType": null, "multiple": false, "title": "appearance", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
{"name": "crm", "type": "object", "elementType": null, "multiple": false, "title": "crm", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
{"name": "dependencies", "type": "object", "elementType": "object", "multiple": true, "title": "dependencies", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
{"name": "presetFields", "type": "object", "elementType": "object", "multiple": true, "title": "presetFields", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
{"name": "responsible", "type": "object", "elementType": null, "multiple": false, "title": "responsible", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
{"name": "agreements", "type": "object", "elementType": null, "multiple": false, "title": "agreements", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
{"name": "submission", "type": "object", "elementType": null, "multiple": false, "title": "submission", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
{"name": "payment", "type": "object", "elementType": null, "multiple": false, "title": "payment", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
{"name": "callback", "type": "object", "elementType": null, "multiple": false, "title": "callback", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
{"name": "booking", "type": "object", "elementType": null, "multiple": false, "title": "booking", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
{"name": "analytics", "type": "object", "elementType": null, "multiple": false, "title": "analytics", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
{"name": "spamProtection", "type": "object", "elementType": null, "multiple": false, "title": "spamProtection", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
{"name": "integrations", "type": "object", "elementType": null, "multiple": false, "title": "integrations", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
{"name": "fields", "type": "object", "elementType": "object", "multiple": true, "title": "fields", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false}
]
}
Error response example
400 — an unknown query parameter was passed:
{
"success": false,
"error": {
"code": "INVALID_PARAMS",
"message": "Unknown query parameter"
}
}
Errors
| HTTP | Code | Description |
|---|---|---|
| HTTP400 | CodeINVALID_PARAMS |
DescriptionAn unknown query parameter was passed |
| HTTP400 | CodeINVALID_PARAMS |
Descriptionselect is not a string or an array of strings |
| HTTP400 | CodeINVALID_PARAMS |
DescriptionBitrix24 rejected the projection. The original code is in error.b24Code |
| HTTP403 | CodeBITRIX_ACCESS_DENIED |
DescriptionThe Bitrix24 user lacks permission to access forms |
| HTTP403 | CodeBITRIX_INSUFFICIENT_SCOPE |
DescriptionThe Bitrix24 token lacks the required scope |
| HTTP404 | CodeENTITY_NOT_FOUND |
DescriptionBitrix24 did not find a requested entity or field descriptor. The original code is in error.b24Code |
| HTTP409 | CodeCRM_FORM_REST_NOT_ENABLED |
DescriptionThe CRM form REST methods are unavailable on this Bitrix24 account. This does not mean that an individual form is missing |
| HTTP400–599 | CodeCRM_FORM_* |
DescriptionRejection under form rules. The code and HTTP status are preserved. The original code is in error.b24Code |
| HTTP422 | CodeBITRIX_ERROR |
DescriptionAnother Bitrix24 rejection. The reason is in error.message. The original code is in error.b24Code |
| HTTP429 | CodeRATE_LIMITED |
DescriptionRequest rate exceeded. Follow the Retry-After header |
| HTTP502 | CodeBITRIX_UNAVAILABLE |
DescriptionBitrix24 returned an unexpected response shape |
| HTTP502 | CodeBITRIX_UNAVAILABLE |
DescriptionBitrix24 is unavailable: a server error or a dropped connection |
| HTTP503 | CodeBITRIX_TIMEOUT |
DescriptionBitrix24 did not respond in time. The read can be retried |
| HTTP401 | CodeMISSING_API_KEY |
DescriptionThe X-Api-Key header is missing |
| HTTP401 | CodeTOKEN_MISSING |
DescriptionThe key has no configured Bitrix24 credentials |
| HTTP403 | CodeSCOPE_DENIED |
DescriptionThe Vibecode API key lacks the crm scope |
Full list of common API errors — Errors.
Known specifics
This endpoint describes properties of the form itself. CRM fields and their value options are listed separately by List entity fields. The two catalogs serve different purposes.