For AI agents: markdown of this page — /docs-content-en/automation.md documentation index — /llms.txt
CRM Automation
Fire CRM triggers and start workflows via the API. Automate your sales funnel, move deals through stages, launch approval chains programmatically.
Scope: crm (triggers), bizproc (workflows) | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key
Documentation sections
- Triggers — firing CRM triggers for entities (2 endpoints).
- Workflows — starting, monitoring, and managing workflows (5 endpoints).
Quick start
Fire a CRM trigger
curl -X POST https://vibecode.bitrix24.com/v1/triggers/fire \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"entityType": "deal",
"entityId": 100,
"triggerId": "payment_received"
}'
Response:
{
"success": true,
"data": true
}
Full documentation of parameters and error codes: POST /v1/triggers/fire
Start a workflow
curl -X POST https://vibecode.bitrix24.com/v1/workflows/start \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"templateId": 15,
"entityType": "deal",
"entityId": 100,
"parameters": {
"approver": 1,
"comment": "15% discount approval"
}
}'
Response:
{
"success": true,
"data": {
"workflowId": "67a1b2c3d4e5f6"
}
}
Full documentation of parameters and error codes: POST /v1/workflows/start
Full example
Scenario: a deal moved to the "Paid" stage — we fire a CRM trigger, then start a document-preparation workflow, send an event to continue a suspended process, and terminate an unneeded instance.
const VIBE_KEY = process.env.VIBE_KEY
const BASE = 'https://vibecode.bitrix24.com/v1'
async function api(method, path, body = null) {
const opts = {
method,
headers: { 'X-Api-Key': VIBE_KEY }
}
if (body) {
opts.headers['Content-Type'] = 'application/json'
opts.body = JSON.stringify(body)
}
const res = await fetch(`${BASE}${path}`, opts)
return res.json()
}
const dealId = 100
// 1. Deal paid — fire a CRM trigger
await api('POST', '/triggers/fire', {
entityType: 'deal',
entityId: dealId,
triggerId: 'payment_received'
})
console.log('Trigger "Payment received" fired')
// 2. Start the document-preparation workflow
const { data: wf } = await api('POST', '/workflows/start', {
templateId: 22,
entityType: 'deal',
entityId: dealId,
parameters: {
docType: 'act',
sendToClient: true
}
})
console.log('Workflow started:', wf.workflowId)
// 3. List running instances by template
const { data: instances, meta } = await api('GET', '/workflows?templateId=22')
console.log(`Active processes for template 22: ${meta.total}`)
for (const instance of instances) {
console.log(` ${instance.ID}: started=${instance.STARTED}`)
}
// 4. Send an event to a suspended process
// eventToken arrives at the handler of a registered activity from the B24 callback
// (see /docs/entities/bizproc-activities), here it is an illustrative value
await api('POST', '/workflows/event', {
eventToken: '55c1dc1c3f0d75.67',
returnValues: { approved: true },
logMessage: 'Automatic confirmation — amount within the limit'
})
console.log('Event sent, process continued')
// 5. Terminate the unneeded instance
await fetch(`${BASE}/workflows/${wf.workflowId}`, {
method: 'DELETE',
headers: { 'X-Api-Key': VIBE_KEY }
})
console.log('Process terminated')
Endpoint reference
| Method | Path | Bitrix24 method | Scope | Description |
|---|---|---|---|---|
| POST | /v1/triggers/fire |
crm.automation.trigger | crm | Fire a CRM trigger |
| GET | /v1/triggers |
crm.automation.trigger.list | crm | List Bitrix24 account triggers |
| POST | /v1/workflows/start |
bizproc.workflow.start | bizproc | Start a workflow |
| GET | /v1/workflows |
bizproc.workflow.instances | bizproc | List running processes |
| DELETE | /v1/workflows/:id |
bizproc.workflow.terminate / kill | bizproc | Terminate a workflow |
| POST | /v1/workflows/event |
bizproc.event.send | bizproc | Send an event to a process |
| POST | /v1/workflows/activity-log |
bizproc.activity.log | bizproc | Write to the process log |
Error codes
Automation errors
| HTTP | Code | Description |
|---|---|---|
| 400 | INVALID_ENTITY_TYPE |
Unknown entity type in entityType. Supported: deal, lead, contact, company, quote, invoice |
| 400 | MISSING_PARAMS |
Required parameters not provided (listed in the response message field) |
| 400 | INVALID_PARAMS |
Invalid parameter value (returned by Bitrix24) |
| 401 | TOKEN_MISSING |
The API key has no configured Bitrix24 tokens |
| 403 | SCOPE_DENIED |
The API key lacks the required scope: crm for triggers, bizproc for workflows |
| 403 | BITRIX_ACCESS_DENIED |
The Bitrix24 portal rejected the operation — insufficient permissions on the portal side |
| 404 | ENTITY_NOT_FOUND |
The entity or template with the given ID was not found |
| 422 | BITRIX_ERROR |
Bitrix24 REST API error (details in the message field) |
| 429 | RATE_LIMITED |
Request limit exceeded. Wait 1–2 seconds and retry |
| 429 | QUEUE_TIMEOUT |
The request to Bitrix24 waited in the queue longer than 30 seconds. The request was NOT sent to Bitrix24 — safe to retry (Retry-After) |
| 500 | INTERNAL_ERROR |
Internal server error |
| 502 | BITRIX_UNAVAILABLE |
The Bitrix24 portal is unavailable |
| 503 | BITRIX_TIMEOUT |
Bitrix24 accepted the request but did not respond within 15 seconds. For write operations — re-read the entity first, the change may have applied |
Full reference of common errors: Errors.
See also
- Deals — the main entity for sales funnel automation
- Leads — firing triggers and workflows for leads
- Business process templates — list of templates for the
templateIdparameter - Business process activities — registering custom activities
- Automation rules — registering custom automation rules
- Errors — full reference of error codes