## Get builder configuration

`GET /v1/crm-forms/configuration`

Returns the CRM form builder reference data for the Bitrix24 account. Call it before creating or updating a form to choose the entity scheme, language and funnel, and to check the active form limit.

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/crm-forms/configuration" \
  -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/configuration', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Active forms:', data.limits.activeForms.current, 'of', data.limits.activeForms.maximum)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-forms/configuration', {
  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` | object | Builder configuration, preserving the returned properties |
| `data.entitySchemes` | array | CRM entity schemes the form creates |
| `data.entitySchemes[].id` | number | Scheme ID. The value for `crm.entityScheme` when [creating a form](/docs/entities/crm-forms/create) |
| `data.entitySchemes[].name` | string | Scheme name |
| `data.entitySchemes[].description` | string | Which entities the scheme creates |
| `data.entitySchemes[].entityNames` | array | Entity names of the scheme, for example `LEAD`, `COMPANY`, `CONTACT` |
| `data.entitySchemes[].mainEntityName` | string \| null | Main entity of the scheme. `null` for a scheme without a main entity, for example "Client" |
| `data.entitySchemes[].hasInvoice` | boolean | Whether the scheme creates an invoice |
| `data.entitySchemes[].dynamic` | boolean | `true` for smart process schemes |
| `data.duplicateModes` | array | Duplicate handling modes |
| `data.duplicateModes[].id` | string | Mode code: `MERGE` or `REPLACE`. The value for `crm.duplicateMode` |
| `data.duplicateModes[].name` | string | Mode name |
| `data.lead.enabled` | boolean | Whether leads are enabled on the Bitrix24 account |
| `data.dealCategories` | array | Deal funnels |
| `data.dealCategories[].id` | number | Funnel ID. The value for `crm.dealCategoryId` |
| `data.dealCategories[].name` | string | Funnel name |
| `data.smartProcesses` | array | Smart processes of the Bitrix24 account |
| `data.smartProcesses[].entityTypeId` | number | Smart process type ID |
| `data.smartProcesses[].entityName` | string | Smart process entity name in the format `DYNAMIC_<entityTypeId>` |
| `data.smartProcesses[].name` | string | Smart process name |
| `data.smartProcesses[].categories` | array | Smart process funnels |
| `data.smartProcesses[].categories[].id` | number | Funnel ID. The value for `crm.smartProcessCategoryId` |
| `data.smartProcesses[].categories[].name` | string | Funnel name |
| `data.languages` | array | Form languages |
| `data.languages[].id` | string | Language code. The value for the form's `languageId` |
| `data.languages[].name` | string | Language name |
| `data.currencies` | array | Currencies of the Bitrix24 account |
| `data.currencies[].id` | string | Currency code, for example `USD` |
| `data.currencies[].fullName` | string | Short currency name |
| `data.currencies[].formatString` | string | Amount display template. `#` is replaced with the amount |
| `data.fieldTypes` | array | Form field types |
| `data.fieldTypes[].id` | string | Type code. The value for the form's `fields[].type` |
| `data.fieldTypes[].name` | string | Type name |
| `data.fieldTypes[].parameters` | array | Settings a field of this type accepts: `label`, `required`, `multiple`, `placeholder`, `valueType`, `value` |
| `data.paySystems` | array | Payment systems of the Bitrix24 account |
| `data.paySystems[].id` | number | Payment system ID |
| `data.paySystems[].name` | string | Payment system name |
| `data.permissions.canRead` | boolean | Whether the key's user can read forms |
| `data.permissions.canEdit` | boolean | Whether the key's user can edit forms |
| `data.limits.activeForms.current` | number | How many forms are active now |
| `data.limits.activeForms.maximum` | number | How many forms can be active on the Bitrix24 account |
| `data.product.isCloud` | boolean | `true` for a cloud Bitrix24 account |
| `data.product.isRegionRussian` | boolean | `true` for a Bitrix24 account in the Russian region |
| `data.region` | string | Region code of the Bitrix24 account, for example `en` |

## Response example

Only the first elements of each array are shown. The array contents depend on the Bitrix24 account.

```json
{
  "success": true,
  "data": {
    "entitySchemes": [
      {
        "id": 1,
        "name": "Lead",
        "description": "lead",
        "entityNames": ["LEAD", "COMPANY", "CONTACT"],
        "mainEntityName": "LEAD",
        "hasInvoice": false,
        "dynamic": false
      },
      {
        "id": 1770,
        "name": "Equipment purchase",
        "description": "Smart Process Automation, contact or company",
        "entityNames": ["DYNAMIC_177", "COMPANY", "CONTACT"],
        "mainEntityName": "DYNAMIC_177",
        "hasInvoice": false,
        "dynamic": true
      }
    ],
    "duplicateModes": [
      { "id": "MERGE", "name": "Merge" },
      { "id": "REPLACE", "name": "Replace" }
    ],
    "lead": { "enabled": true },
    "dealCategories": [
      { "id": 0, "name": "General" },
      { "id": 1, "name": "Newest" }
    ],
    "smartProcesses": [
      {
        "entityTypeId": 177,
        "entityName": "DYNAMIC_177",
        "name": "Equipment purchase",
        "categories": [
          { "id": 7, "name": "General" },
          { "id": 9, "name": "Second funnel" }
        ]
      }
    ],
    "languages": [
      { "id": "en", "name": "English" },
      { "id": "de", "name": "Deutsch" }
    ],
    "currencies": [
      { "id": "USD", "fullName": "$", "formatString": "$#" }
    ],
    "fieldTypes": [
      { "id": "section", "name": "Section", "parameters": ["label"] },
      { "id": "string", "name": "String", "parameters": ["label", "required", "multiple", "placeholder", "valueType", "value"] }
    ],
    "paySystems": [
      { "id": 1, "name": "Bank transfer (Companies)" },
      { "id": 11, "name": "Cash" }
    ],
    "permissions": { "canRead": true, "canEdit": true },
    "limits": { "activeForms": { "current": 4, "maximum": 99999 } },
    "product": { "isCloud": true, "isRegionRussian": false },
    "region": "en"
  }
}
```

## Error response example

400 — a query parameter was passed:

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

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | The endpoint accepts no query parameters |
| 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

- **The smart process scheme ID differs from `entityTypeId`.** For smart process `177`, `entitySchemes` returns a scheme with `id: 1770`. Pass the scheme `id` in `crm.entityScheme`, not `entityTypeId`.

## See also

- [Create a form](/docs/entities/crm-forms/create)
- [Activate a form](/docs/entities/crm-forms/activate)
- [Form contract fields](/docs/entities/crm-forms/fields)
- [List entity fields](/docs/entities/crm-forms/entity-fields)
- [CRM forms](/docs/entities/crm-forms)