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

Terminal
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:

JSON
{
  "success": true,
  "data": true
}

Full documentation of parameters and error codes: POST /v1/triggers/fire

Start a workflow

Terminal
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:

JSON
{
  "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.

javascript
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