[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-entities\u002Fbizproc-robots\u002Fcreate":3,"docs-tabs-entities\u002Fbizproc-robots\u002Fcreate":6},{"content":4,"lastmod":5},"\n## Register an automation rule\n\n`POST \u002Fv1\u002Fbizproc-robots`\n\nRegisters a new automation rule in Bitrix24. Fields are passed flat at the JSON root — without a `fields` wrapper.\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|---------|\n| `code` | string | yes | Unique automation rule code. Allowed characters: `a-z`, `A-Z`, `0-9`, `.`, `-`, `_`. Becomes the automation rule identifier in update and delete paths |\n| `name` | string \\| object | yes | Automation rule name. A string or a localized object like `{\"en\": \"...\", \"de\": \"...\"}` |\n| `handler` | string | yes | Handler URL. The domain must match the application domain |\n| `documentType` | array | no | Document type `[module, object, type]`. Values:\u003Cbr>`[\"crm\", \"CCrmDocumentLead\", \"LEAD\"]` — leads\u003Cbr>`[\"crm\", \"CCrmDocumentDeal\", \"DEAL\"]` — deals\u003Cbr>`[\"crm\", \"Bitrix\\\\Crm\\\\Integration\\\\BizProc\\\\Document\\\\Quote\", \"QUOTE\"]` — quotes\u003Cbr>`[\"crm\", \"Bitrix\\\\Crm\\\\Integration\\\\BizProc\\\\Document\\\\SmartInvoice\", \"SMART_INVOICE\"]` — invoices\u003Cbr>`[\"crm\", \"Bitrix\\\\Crm\\\\Integration\\\\BizProc\\\\Document\\\\Dynamic\", \"DYNAMIC_\u003CentityTypeId>\"]` — smart processes, `\u003CentityTypeId>` from the `entityTypeId` field in [GET \u002Fv1\u002Fsmart-processes](\u002Fdocs\u002Fentities\u002Fsmart-processes\u002Flist) |\n| `description` | string \\| object | no | Automation rule description. A string or a localized object |\n| `authUserId` | number | no | The user whose token is passed to the application when the automation rule is invoked. List: `GET \u002Fv1\u002Fusers` |\n| `useSubscription` | string | no | Whether to wait for a response from the application before continuing the rule: `Y` or `N` |\n| `properties` | object | no | Automation rule input parameters — the fields filled in when configuring the rule |\n| `returnProperties` | object | no | Automation rule output parameters — the values the rule returns |\n| `filter` | object | no | Limits which documents the automation rule is available for. Without the field, the automation rule is available for all documents.\u003Cbr>`INCLUDE` lists the conditions under which the automation rule is available, `EXCLUDE` those under which it is not. A condition is a document type prefix, for example `[\"crm\", \"CCrmDocumentDeal\"]`, or a Bitrix24 edition: `\"b24\"` for cloud, `\"box\"` for on-premise.\u003Cbr>Example: `{\"INCLUDE\": [[\"crm\", \"CCrmDocumentDeal\"], [\"crm\", \"CCrmDocumentLead\"]]}`.\u003Cbr>Write the keys in uppercase: with lowercase keys the field is accepted but restricts nothing. A value that is not an object returns `422 BITRIX_ERROR` |\n| `usePlacement` | string | no | Whether to open the automation rule settings in a slider panel: `Y` or `N` |\n| `placementHandler` | string | no | URL of the settings slider panel. Required when `usePlacement: \"Y\"` |\n\n## Examples\n\nOnly an OAuth application key can register an automation rule — both examples send an OAuth application key and the `Authorization: Bearer` header. The session token is issued by OAuth authorization, is valid for 24 hours, and cannot be renewed — [Passing the key](\u002Fdocs\u002Fkeys-auth#passing-the-key).\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbizproc-robots\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"code\": \"deal_notify\",\n    \"name\": { \"en\": \"Deal notification\", \"de\": \"Deal-Benachrichtigung\" },\n    \"handler\": \"https:\u002F\u002Fapp.example.com\u002Frobots\u002Fdeal-notify\",\n    \"documentType\": [\"crm\", \"CCrmDocumentDeal\", \"DEAL\"],\n    \"useSubscription\": \"N\"\n  }'\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbizproc-robots', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    code: 'deal_notify',\n    name: { en: 'Deal notification', de: 'Deal-Benachrichtigung' },\n    handler: 'https:\u002F\u002Fapp.example.com\u002Frobots\u002Fdeal-notify',\n    documentType: ['crm', 'CCrmDocumentDeal', 'DEAL'],\n    useSubscription: 'N',\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data.id` | string | Addressable identifier. Uses the `code` returned by Bitrix24 when present; otherwise equals the submitted `code`. Used as `:code` for PATCH and DELETE |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": \"deal_notify\"\n  }\n}\n```\n\n## Error response example\n\n403 — the request was sent with an API key:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"OAUTH_REQUIRED\",\n    \"message\": \"bizproc-robots require an OAuth app key (vibe_app_*) with an Authorization: Bearer session — a personal vibe_api_* key lacks the per-user OAuth context Bitrix24 needs for these methods. Create an OAuth app (POST \u002Fv1\u002Fapps) and retry with its key. On this 403 switch keys — do NOT delete or recreate the app (that discards anything already registered under it, e.g. a bizproc robot you just registered).\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 403 | `OAUTH_REQUIRED` | The request was sent with an API key. Only an authorization key can register automation rules |\n| 401 | `TOKEN_MISSING` | The authorization key was sent without the `Authorization: Bearer` header |\n| 401 | `WRONG_AUTH_SCHEME` | The authorization key was sent in the `Authorization: Bearer` header. The key goes in `X-Api-Key`, while `Authorization: Bearer` carries the session token |\n| 401 | `INVALID_SESSION` | The session token has expired or is invalid — authorize again |\n| 403 | `SCOPE_DENIED` | The key lacks the `bizproc` scope |\n| 400 | `MISSING_REQUIRED_FIELDS` | A required field is missing — `code`, `name`, or `handler` |\n| 400 | `SERVER_APP_MISMATCH` | `handler` points to a Black Hole subdomain that has no server of this app behind it — the subdomain does not exist, or the server belongs to another app. Register the handler with the key of the app the server is linked to |\n| 409 | `BIZPROC_MODULE_NOT_ENABLED` | Business Processes are not available on the account: the module is not included in the plan, or it is switched off in account settings. Ask an account administrator to enable Business Processes — until then the method answers the same way for any number of retries |\n| 503 | `BIZPROC_CALLBACK_RESOLVE_FAILED` | The platform could not match the handler to a server. The automation rule is not registered — repeat the request |\n| 422 | `BITRIX_ERROR` | Bitrix24 validation error — text in `error.message` |\n\nThe full list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**A handler on a Black Hole subdomain gets reliable delivery.** The platform takes over delivery of the calls and stores the address of its own receiver in Bitrix24 instead of the one you passed. Such a handler can only be registered with a single request, and the delivery itself is switched on per Bitrix24 account — [Activity and automation rule callback delivery](\u002Fdocs\u002Finfra\u002Fbizproc-callbacks).\n\n## See also\n\n- [Update an automation rule](\u002Fdocs\u002Fentities\u002Fbizproc-robots\u002Fupdate)\n- [Delete an automation rule](\u002Fdocs\u002Fentities\u002Fbizproc-robots\u002Fdelete)\n- [Activity and automation rule callback delivery](\u002Fdocs\u002Finfra\u002Fbizproc-callbacks)\n- [Keys and authorization](\u002Fdocs\u002Fkeys-auth)\n","2026-10-22",{},1794739313153]