# Update a form

`PATCH /v1/crm-forms/:id`

Bitrix24 method: `crm.form.update` (REST v3).

Scope: `crm`. Requires a READWRITE key.

## Behavior and parameters

Supply `updatedTime` from [get a form](/docs/entities/crm-forms/get) and only the configuration properties to change. Omitted properties stay unchanged. Collections supplied in the request replace the collection; an empty array clears it. The wrapper re-reads the saved form and returns HTTP 200 in the GET DTO. Activate or deactivate the form using the dedicated actions.

Allowed top-level properties: `name`, `active` on creation only, `languageId`, `templateId`, `crm`, `appearance`, `fields`, `responsible`, `agreements`, `submission`, `callback`, `payment`, `booking`, `presetFields`, `dependencies`; update additionally requires `updatedTime`. Nested values are passed unchanged; Bitrix24 validates them. `analytics`, `integrations`, `spamProtection` and unknown top-level properties are refused before calling Bitrix24. Read field metadata with [form fields](/docs/entities/crm-forms/fields).

Set `required` and `multiple` explicitly for each field; omitted flags are saved as `true`. List, checkbox, radio, product and booking fields cannot be configured through this contract; validation reports violations. The appearance theme is not part of the writable projection; Bitrix24 decides how to handle an unrecognized nested property.

Bitrix24 does not perform writes on free or demo plans. Permissions, quota and business rules are checked by Bitrix24.

## Example

```bash
curl -X PATCH 'https://vibecode.bitrix24.com/v1/crm-forms/8' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"updatedTime":"2026-10-22T12:00:00Z","name":"Updated contact form"}'
```

For an OAuth application, use its key and the `Authorization: Bearer USER_SESSION_TOKEN` header.

```json
{"success":true,"data":{"id":8,"name":"Contact form","fields":[],"updatedTime":"2026-10-22T12:00:00Z"}}
```

## Errors

| HTTP | Code | Reason |
|---|---|---|
| 400 | `INVALID_PARAMS` | Invalid id, body or query shape |
| 400 | `MISSING_REQUIRED_FIELDS` | Missing updatedTime on PATCH |
| 400 | `READONLY_FIELD` | Unpublished field |
| 400 | `UNKNOWN_FIELD` | Unknown top-level field |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | READONLY key |
| 402 | `CRM_FORM_WRITE_RESTRICTED` | Bitrix24 plan does not allow writing CRM forms |
| 403 | `SCOPE_DENIED` | Missing crm scope |
| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 permission refusal |
| 403 | `CRM_FORM_SYSTEM_IMMUTABLE` | System form cannot be changed |
| 404 | `ENTITY_NOT_FOUND` | Form does not exist |
| 409 | `CRM_FORM_VERSION_MISMATCH` | Version is stale; error.currentUpdatedTime contains the current version |
| 422 | `BITRIX_ERROR` | Other Bitrix24 refusal, original message retained |
| 500 | `CRM_FORM_SIDE_EFFECT_FAILED` | Write already happened; read the form before retrying. On creation error.id identifies the saved form |
| 502 | `BITRIX_UNAVAILABLE` | Invalid or unavailable upstream response; re-read the form before retrying a write |

Bitrix24 codes, statuses and messages are retained. See [common limits](/docs/optimization) for shared 429, 502 and 503 responses.

Scalar `null` values are passed to Bitrix24 for clearing; supplied collections replace the previous collection, and an empty array clears it.