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 is the second element of the template's documentType in the GET /v1/bizproc-templates response, and the iblockId for the element source is the number in the third element, iblock_<id>. Pass the class as is: an ordinary list and a process in the Feed share the module lists, but their classes differ. Templates can be read only with an OAuth app key. If your template request passes select, include moduleId and entity in it, otherwise the first two elements of documentType come back as null.

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 Bitrix\Lists\BizprocDocumentLists 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. No Vibecode API method returns finished instances, so an empty list does not prove that the workflow was never started.

See also

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