## List forms

`GET /v1/crm-forms`

Finds CRM forms in the Bitrix24 account by activity, name, code, CRM scheme, responsible user or dates, so you can get the ID of the form you need.

## Parameters

| Parameter | Type | Default | Description |
|----------|-----|-----------|----------|
| `id` (query) | integer \| integer[] | — | Form IDs. Repeat the parameter: `?id=1&id=3`. IDs come from this list |
| `active` (query) | boolean | — | Form activity. Omit to return both active and inactive forms |
| `name` (query) | string | — | Exact form name, including commas. Repeat the parameter for several names |
| `code` (query) | string | — | Exact symbolic code. Repeat the parameter for several codes |
| `entityScheme` (query) | number | — | Alias for `crm.entityScheme`. Values: `entitySchemes` in [builder configuration](/docs/entities/crm-forms/configuration). Several values may be comma-separated |
| `responsibleUserId` (query) | number | — | Alias for `responsible.userIds`. IDs: [List employees](/docs/entities/users/list). Several IDs may be comma-separated |
| `filter` (query) | object | — | Filter by form properties. Top-level metadata: [Form contract fields](/docs/entities/crm-forms/fields). [Filtering syntax](/docs/filtering). Example: `?filter[id][$in]=1,3`, date range: `?filter[updatedTime][$gte]=2023-01-01T00:00:00Z`. Property names and operators are validated by Bitrix24 |
| `select` (query) | string | — | Comma-separated properties and nested paths, such as `id,name,active,templateId,crm.entityScheme,responsible.userIds,updatedTime` |
| `order` (query) | object | — | Sort: `?order[name]=desc`. Use either `order[...]` or `sort`. Using both returns `400 INVALID_PARAMS` |
| `sort` (query) | string | — | Sort shorthand: `?sort=-name`; a leading minus means descending order. Bitrix24 validates sort properties and directions |
| `limit` (query) | number | — | Page size. Bitrix24 validates the value |
| `offset` (query) | number | — | Number of forms to skip. Bitrix24 validates the value |

Pagination. One request reads one page. Without `limit` and `offset`, Bitrix24 uses its own pagination defaults. Pagination metadata is included only when returned by Bitrix24. To request the next page, pass `limit` and increase `offset` by that value.

## Examples

### curl — personal key

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

### curl — OAuth application

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

const { data, meta } = await res.json()
for (const form of data) console.log(form.id, form.name)
const mayHaveNextPage = data.length === 2
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-forms?limit=2', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data, meta } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` on success |
| `data` | array | Forms on the page, preserving their properties. Top-level property metadata: [Form contract fields](/docs/entities/crm-forms/fields) |
| `meta` | object | Optional pagination metadata returned by Bitrix24 |
| `meta.redacted` | string[] | Present only when the current connection's credentials are found in the content. `JSON Pointer` paths identify replaced values |

Without `select`, each form has 11 scalar properties: `id`, `code`, `name`, `active`, `system`, `languageId`, `templateId`, `createdTime`, `updatedTime`, `activeChangedById`, `activeChangedTime`. Target entities and responsible users require an explicit `select`. `activeChangedById` identifies the author of the activity change, not the responsible user.

## Response example

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

## Error response example

400 — invalid `limit`, here `?limit=abc`:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Cannot parse pagination parameter `{\"limit\":\"abc\"}`",
    "b24Code": "BITRIX_REST_V3_EXCEPTION_INVALIDPAGINATIONEXCEPTION"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | Malformed `filter`, `select`, `order` or `sort` structure |
| 400 | `INVALID_PARAMS` | Both `order[...]` and `sort` were passed |
| 400 | `INVALID_PARAMS` | Bitrix24 rejected a filter, sort or pagination value. The original code is in `error.b24Code`. Field errors are in `error.validation` |
| 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).

## See also

- [Get a form](/docs/entities/crm-forms/get)
- [Create a form](/docs/entities/crm-forms/create)
- [Get the builder configuration](/docs/entities/crm-forms/configuration)
- [CRM forms](/docs/entities/crm-forms)
- [Limits and optimization](/docs/optimization)