## 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 |
|----------|-----|----------|
| `select` (query) | string | Comma-separated metadata properties, for example `name,type,multiple`. Without it, all metadata properties are returned |

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/crm-forms/fields" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
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

```javascript
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

```javascript
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 |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | array | Form property descriptions. The property set is in the table below |
| `data[].name` | string | Form property name |
| `data[].type` | string | Value type: `int`, `string`, `bool`, `date-time` or `object` |
| `data[].elementType` | string \| null | Element type of a multi-value property, for example `object`. `null` for single-value properties |
| `data[].multiple` | boolean | `true` — the property value is an array |
| `data[].title` | string | Property label. Matches `name` |
| `data[].description` | string \| null | Property description |
| `data[].validationRules` | array | Value validation rules |
| `data[].requiredGroups` | array \| null | Required groups |
| `data[].filterable` | boolean | Whether the property is marked as filterable |
| `data[].sortable` | boolean | Whether the property is marked as sortable |
| `data[].editable` | boolean | Editability 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 |
|------|-----|:--:|---------|
| `id` | int | yes | Form ID. List: [`GET /v1/crm-forms`](/docs/entities/crm-forms/list) |
| `code` | string | yes | Form symbolic code |
| `name` | string | | Form name |
| `active` | bool | | Whether the form is enabled. Accepted only on create. For an existing form, change it through [activation](/docs/entities/crm-forms/activate) and [deactivation](/docs/entities/crm-forms/deactivate) |
| `system` | bool | yes | System form |
| `languageId` | string | | Form language. List: `data.languages[].id` in the [builder configuration](/docs/entities/crm-forms/configuration) |
| `templateId` | string | | Form template |
| `createdTime` | date-time | yes | Creation time |
| `updatedTime` | date-time | yes | Last modification time. Pass it to [form update](/docs/entities/crm-forms/update) as a version that protects against overwriting other users' changes |
| `activeChangedById` | int | yes | ID of the user who last changed the active state. List: [`GET /v1/users`](/docs/entities/users) |
| `activeChangedTime` | date-time | yes | When the active state last changed |
| `appearance` | object | | Appearance: title, description, button caption and colors |
| `crm` | object | | CRM binding: entity scheme, duplicate mode, funnel. Values are in the [builder configuration](/docs/entities/crm-forms/configuration) |
| `dependencies` | object | | Array of field dependency rules, `multiple: true` |
| `presetFields` | object | | Array of preset field values, `multiple: true` |
| `responsible` | object | | Users responsible for form results and work time tracking. Responsible user IDs come from [`GET /v1/users`](/docs/entities/users) |
| `agreements` | object | | Agreements the visitor accepts on submission |
| `submission` | object | | Actions after submission: texts and redirect URLs on success and on error |
| `payment` | object | | Payment settings |
| `callback` | object | | Callback settings |
| `booking` | object | | Booking settings |
| `analytics` | object | | Analytics settings |
| `spamProtection` | object | | Spam protection settings |
| `integrations` | object | | Integration settings |
| `fields` | object | | Array of form fields, `multiple: true`. Field names come from [`GET /v1/crm-forms/entity-fields`](/docs/entities/crm-forms/entity-fields) |

## Response example

```json
{
  "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:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Unknown query parameter"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | An unknown query parameter was passed |
| 400 | `INVALID_PARAMS` | `select` is not a string or an array of strings |
| 400 | `INVALID_PARAMS` | Bitrix24 rejected the projection. The original code is in `error.b24Code` |
| 403 | `BITRIX_ACCESS_DENIED` | The Bitrix24 user lacks permission to access forms |
| 403 | `BITRIX_INSUFFICIENT_SCOPE` | The Bitrix24 token lacks the required scope |
| 404 | `ENTITY_NOT_FOUND` | Bitrix24 did not find a requested entity or field descriptor. The original code is in `error.b24Code` |
| 409 | `CRM_FORM_REST_NOT_ENABLED` | The CRM form REST methods are unavailable on this Bitrix24 account. This does not mean that an individual form is missing |
| 400–599 | `CRM_FORM_*` | Rejection under form rules. The code and HTTP status are preserved. The original code is in `error.b24Code` |
| 422 | `BITRIX_ERROR` | Another Bitrix24 rejection. The reason is in `error.message`. The original code is in `error.b24Code` |
| 429 | `RATE_LIMITED` | Request rate exceeded. Follow the `Retry-After` header |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 returned an unexpected response shape |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable: a server error or a dropped connection |
| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time. The read can be retried |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `TOKEN_MISSING` | The key has no configured Bitrix24 credentials |
| 403 | `SCOPE_DENIED` | The Vibecode API key lacks the `crm` scope |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

This endpoint describes properties of the form itself. CRM fields and their value options are listed separately by [List entity fields](/docs/entities/crm-forms/entity-fields). The two catalogs serve different purposes.

## See also

- [Get a form contract field](/docs/entities/crm-forms/field)
- [Create a form](/docs/entities/crm-forms/create)
- [Update a form](/docs/entities/crm-forms/update)
- [Get a form](/docs/entities/crm-forms/get)
- [Get the builder configuration](/docs/entities/crm-forms/configuration)
- [CRM forms](/docs/entities/crm-forms)