Workflows

A workflow is a multi-step scenario that runs on a Bitrix24 document. Unlike CRM triggers, which change an entity's state instantly, a workflow can include pauses to wait for external events, conditional branching, parallel branches, and delays. Typical scenarios: approval chains, automatic document preparation, scheduled notifications.

Lifecycle: launch (start) → execution → instance inspection (list) → pause handling via an event (event) or a log entry (activity-log) → termination (terminate).

Bitrix24 API: bizproc.workflow.*, bizproc.event.*, bizproc.activity.* Scope: bizproc

Start a workflow

POST /v1/workflows/start

Starts a workflow instance from a template for a CRM entity, a list element or another Bitrix24 document. The document is given in one of two shapes: a type and ID for a deal, lead, contact or company, or an explicit Bitrix24 document identifier for everything else.

Request fields (body)

Pass templateId and exactly one document shape. A body that carries entityType or entityId together with documentId is rejected with 400 CONFLICTING_PARAMS.

documentId values by module:

The class and the identifier are passed to Bitrix24 unchanged. In JSON, escape the backslash in the class name by doubling it, as in the lists example.

Examples

curl — personal key

curl -X POST https://vibecode.bitrix24.com/v1/workflows/start \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"templateId":713,"entityType":"deal","entityId":5141}'

curl — OAuth application

curl -X POST https://vibecode.bitrix24.com/v1/workflows/start \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"templateId":713,"entityType":"deal","entityId":5141}'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/workflows/start', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 713,
    entityType: 'deal',
    entityId: 5141,
  }),
})
const data = await res.json()
console.log(data.data.workflowId)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/workflows/start', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 713,
    entityType: 'deal',
    entityId: 5141,
  }),
})
const data = await res.json()

Response fields

Response example

HTTP 201 Created

{
  "success": true,
  "data": {
    "workflowId": "69f0c2d5ade389.22457798"
  }
}

Error response example

400 — both document shapes in one body:

{
  "success": false,
  "error": {
    "code": "CONFLICTING_PARAMS",
    "message": "Pass either { entityType, entityId } OR { documentId }, not both. Pick the shape that matches your target document namespace."
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

• One template — multiple instances. The same templateId can be started for different entities simultaneously. Each start receives its own unique workflowId.
• A repeated call starts another instance. A request with the same body is not rejected and does not return the already running workflow: every 201 means a new instance on the same document. If a request may have gone through but the response was lost, check the list of running workflows before retrying. It shows only active instances: a workflow that has already finished does not appear there.
• The document class must match the template. A template is bound to a document type, and the class in documentId must match it. For an element of an ordinary list it is Bitrix\Lists\BizprocDocumentLists. On a mismatch the response is 422 BITRIX_ERROR.

See also

• List of running workflows
• Terminate a workflow
• Workflows
• Business process templates