# 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](/docs/automation/triggers) — firing CRM triggers for entities (2 endpoints).
- [Workflows](/docs/automation/workflows) — starting, monitoring, and managing workflows (5 endpoints).

## Quick start

### Fire a CRM trigger

```bash
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`](/docs/automation/triggers/fire)

### Start a workflow

```bash
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`](/docs/automation/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`](/docs/automation/triggers/fire) | crm.automation.trigger | crm | Fire a CRM trigger |
| GET | [`/v1/triggers`](/docs/automation/triggers/list) | crm.automation.trigger.list | crm | List Bitrix24 account triggers |
| POST | [`/v1/workflows/start`](/docs/automation/workflows/start) | bizproc.workflow.start | bizproc | Start a workflow |
| GET | [`/v1/workflows`](/docs/automation/workflows/list) | bizproc.workflow.instances | bizproc | List running processes |
| DELETE | [`/v1/workflows/:id`](/docs/automation/workflows/terminate) | bizproc.workflow.terminate / kill | bizproc | Terminate a workflow |
| POST | [`/v1/workflows/event`](/docs/automation/workflows/event) | bizproc.event.send | bizproc | Send an event to a process |
| POST | [`/v1/workflows/activity-log`](/docs/automation/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](/docs/errors).

## See also

- [Deals](/docs/entities/deals) — the main entity for sales funnel automation
- [Leads](/docs/entities/leads) — firing triggers and workflows for leads
- [Business process templates](/docs/entities/bizproc-templates) — list of templates for the `templateId` parameter
- [Business process activities](/docs/entities/bizproc-activities) — registering custom activities
- [Automation rules](/docs/entities/bizproc-robots) — registering custom automation rules
- [Errors](/docs/errors) — full reference of error codes