## Get form embedding codes

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

Returns HTML code for embedding a form in a page (`inline`), opening it on click (`click`), or displaying it after a delay (`auto`). Without `variant`, returns all three variants, their settings, and the public form URL. Query overrides affect the generated code without saving the 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`. Omit to get all variants |
| `buttonText` (query) | string | no | Button caption, only with `variant=click` |
| `buttonType` (query) | string | no | `button` or `link`, only with `variant=click` |
| `delay` (query) | integer | no | Delay in seconds, only with `variant=auto`. Passing it with another variant or without a variant returns `400 INVALID_PARAMS` |

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/crm-forms/59/embedding?variant=auto&delay=7" \
  -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=auto&delay=7', {
  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=auto&delay=7', {
  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 | Complete embedding settings without `variant`, or `{variant, code}` when it is set |
| `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 | HTML embed code, returned unchanged |
| `data.<variant>.previewUrl` | string | Preview URL, returned unchanged |
| `data.<variant>.settings` | object / null | Current settings listed in [Update embedding settings](/docs/entities/crm-forms/embedding-update). `inline` has `null` |
| `data.<variant>.options` | object / null | Allowed values for the variant settings. `inline` has `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 | Embed code for the selected variant, only when `variant` is set |

## Response example

Response for `variant=auto&delay=7`. Public domains and signatures in this example are placeholders.

```json
{
  "success": true,
  "data": {
    "variant": "auto",
    "code": "<script id=\"bx24_form_delay\" data-skip-moving=\"true\">\n\t(function(w,d,u,b){w['Bitrix24FormObject']=b;w[b] = w[b] || function(){arguments[0].ref=u;\n\t\t(w[b].forms=w[b].forms||[]).push(arguments[0])};\n\t\tif(w[b]['forms']) return;\n\t\tvar s=d.createElement('script');s.async=1;s.src=u+'?'+(1*new Date());\n\t\tvar h=d.getElementsByTagName('script')[0];h.parentNode.insertBefore(s,h);\n\t})(window,document,'https://example.bitrix24.com/bitrix/js/crm/form_loader.js','b24form');\n\n\tb24form({\"id\":59,\"lang\":\"ru\",\"sec\":\"p4yyaj\",\"type\":\"delay\",\"delay\":7});\n</script>"
  }
}
```

## Error response example

400 — unsupported `variant`:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "variant must be inline, click or auto"
  }
}
```

## Errors

| HTTP | Code | Description |
|---|---|---|
| 400 | `INVALID_PARAMS` | Invalid form ID or request structure |
| 400 | `UNKNOWN_FILTER_FIELD` | Unknown query parameter |
| 400 | `INVALID_PARAMS` | An override is used with the wrong variant, or its value is rejected. Field diagnostics are returned in `error.validation` |
| 404 | `ENTITY_NOT_FOUND` | Form not found |
| 403 | `SCOPE_DENIED` | API key lacks the `crm` scope |
| 403 | `BITRIX_ACCESS_DENIED` | User lacks access |
| 403 | `CRM_FORM_ACCESS_DENIED` | Form access is denied |
| 401 | `TOKEN_MISSING` | API key has no configured credentials |
| 502 | `BITRIX_UNAVAILABLE` | Invalid embedding response |

For common API errors, see [Errors](/docs/errors).

## Known specifics

Copy the returned HTML code and public URLs with their public signatures unchanged.

## See also

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