## Get form embedding codes

`GET /v1/crm-forms/:id/embedding`

Get the form embed code or a public link to place on a website. Query parameters change the requested variant without saving settings.

## Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` (path) | number | yes | Positive form ID from [List forms](/docs/entities/crm-forms/list) |
| `variant` (query) | string | no | `inline`, `click`, `auto`, `link`. Omit to get all embedding settings |
| `buttonText` (query) | string | no | Button caption override, validated by Bitrix24 |
| `buttonType` (query) | string | no | Button type override, such as `button` or `link`. Bitrix24 validates the value |
| `delay` (query) | integer | no | Delay override in seconds. Bitrix24 validates the value and its combination with `variant` |

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/crm-forms/59/embedding?variant=link" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

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

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

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-forms/59/embedding?variant=link', {
  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 | `true` on success |
| `data` | object | Embedding object as returned by Bitrix24. Without `variant`, includes available variants and settings. With `variant=link`, contains `{variant, url}` |
| `data.formActive` | boolean | Whether the form is active |
| `data.resourcesReady` | boolean | Whether form resources are ready |
| `data.publicUrl` | string | Public form URL, including its public signature |
| `data.inline` | object | Form embedded in the page |
| `data.click` | object | Form opened on click |
| `data.auto` | object | Form opened after a delay |
| `data.<variant>.code` | string / null | HTML embed code, or `null` when resources are not ready |
| `data.<variant>.previewUrl` | string | Preview URL when supplied. Missing fields and `null` values are preserved |
| `data.<variant>.settings` | object / null | Current settings. See [Update embedding settings](/docs/entities/crm-forms/embedding-update). Values are passed through, including `null` |
| `data.<variant>.options` | object / null | Allowed setting values returned by Bitrix24, including `null` |
| `data.<variant>.options.type` | string[] | `popup`, `panel` |
| `data.<variant>.options.position` | string[] | `left`, `center`, `right` |
| `data.<variant>.options.vertical` | string[] | `bottom`, `top` |
| `data.click.options.button.font` | string[] | `modern`, `classic`, `elegant` |
| `data.click.options.button.align` | string[] | `inline`, `left`, `center`, `right` |
| `data.auto.options.delay` | number[] | `3`, `5`, `7`, `10`, `15`, `20`, `25`, `30`, `40`, `60`, `120` |
| `data.variant` | string | Selected variant, only when `variant` is set |
| `data.code` | string / null | Embed code for the selected HTML variant, including `null` when supplied |
| `data.url` | string | Public URL when `variant=link` |
| `meta.redacted` | string[] | Paths with connection credentials replaced. Such a response is not a complete configuration for saving back |

## Response example

Response for `variant=link`. The public domain and signature are placeholders.

```json
{
  "success": true,
  "data": {
    "variant": "link",
    "url": "https://example.bitrix24.com/crm_form_tz6sk/?telemetry_sign=DUMMY_PUBLIC_SIGNATURE"
  }
}
```

## Error response example

400 — the form ID is not a positive integer:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "id must be a positive safe integer"
  }
}
```

## Errors

| HTTP | Code | Description |
|---|---|---|
| 400 | `INVALID_PARAMS` | Invalid form ID or request structure |
| 400 | `INVALID_PARAMS` | Unknown query parameter or invalid request structure |
| 400 | `INVALID_PARAMS` | Bitrix24 rejected a parameter or parameter combination. The original code is in `error.b24Code`, with field diagnostics in `error.validation` when supplied |
| 409 | `CRM_FORM_REST_NOT_ENABLED` | CRM form REST methods are disabled on the Bitrix24 account. The original code for the missing method is in `error.b24Code` |
| 403 | `BITRIX_INSUFFICIENT_SCOPE` | The Bitrix24 token lacks the required scope. The original code is in `error.b24Code` |
| 404 | `ENTITY_NOT_FOUND` | Form not found |
| 403 | `SCOPE_DENIED` | API key lacks the `crm` scope |
| 403 | `BITRIX_ACCESS_DENIED` | The user lacks access permissions |
| 401 | `TOKEN_MISSING` | API key has no configured credentials |
| 502 | `BITRIX_UNAVAILABLE` | Invalid embedding response |

Errors from Bitrix24 include the original `error.b24Code` and field diagnostics in `error.validation`, when supplied. For common API errors, see [Errors](/docs/errors).

## Known specifics

When resources are not ready, the response remains successful with `resourcesReady: false` and any `code: null` supplied by Bitrix24. Missing fields are not filled in. Public signatures are preserved. Only credentials used for the current connection are replaced, with paths listed in `meta.redacted`.

## See also

- [Update form embedding settings](/docs/entities/crm-forms/embedding-update)
- [List forms](/docs/entities/crm-forms/list)