bizproc.workflow.start

What bizproc.workflow.start does

Bridges external events into Bitrix24's workflow engine: approval chains, document generation, multi-step processes — designed visually in the workflow designer, triggered programmatically by your systems.

Business use cases

• Payment received externally → start the fulfillment approval workflow on the deal
• KYC verified in an external system → start the onboarding process
• Escalation monitors starting review workflows on stalled records
• Batch-starting a re-approval process across records after a policy change

Typical fields and parameters

• TEMPLATE_ID — The workflow template — list with bizproc.workflow.template.list; IDs are portal-specific
• DOCUMENT_ID — Triplet array: ['crm', 'CCrmDocumentDeal', 'DEAL_3120'] for a deal; format varies by module and entity
• PARAMETERS — Values for the template's declared input parameters

Example workflow

1. External billing marks invoice 8842 paid
2. Worker resolves deal 3120 by order ID
3. bizproc.workflow.start launches the 'Post-payment fulfillment' template on the deal with the amount as a parameter
4. The workflow handles approvals, task creation, and client notification per its design

Example request

POST .../bizproc.workflow.start.json

{
  "TEMPLATE_ID": 41,
  "DOCUMENT_ID": ["crm", "CCrmDocumentDeal", "DEAL_3120"],
  "PARAMETERS": { "PaidAmount": 4500, "TxnRef": "pay_9f3k2" }
}

Example response

{ "result": "6a2c1e…", "time": { ... } }
// "result" is the workflow instance ID — keep it to monitor
// or terminate via bizproc.workflow.instances / terminate.

Field mapping notes

• DOCUMENT_ID formats are the most error-prone detail: CCrmDocumentDeal/DEAL_n, CCrmDocumentLead/LEAD_n, Lists use lists + BizprocDocument + element ID — test each target type explicitly
• Template IDs differ across portals/environments — resolve by listing and matching template name, or configure per environment
• PARAMETERS must match the template's declared parameters exactly; missing required parameters fail the start

Security notes

• Workflows can approve, notify, and modify data — starting them is a privileged action. Restrict which templates your integration may start; validate external triggers (e.g. payment signatures) before starting anything

Common errors

• 'Template not found' — Portal-specific ID hardcoded from another environment — resolve dynamically
• Workflow starts but stalls immediately — Required PARAMETERS missing or the workflow's first action lacks permissions — check the workflow log in the designer
• Duplicate workflow instances — Event retries re-started the workflow — check bizproc.workflow.instances for a running instance on the document first

Production implementation tips

• Check for already-running instances before starting when the workflow shouldn't run concurrently on one record
• Log instance IDs against your trigger events — 'did the approval start?' should be answerable from your logs
• Prefer starting workflows over reimplementing approval logic in code: the business can edit the workflow in the designer without redeploying your integration

Webhook or OAuth app?

Privileged action — OAuth app with bizproc scope and a documented list of startable templates is the disciplined setup.

Full decision guide: webhook vs OAuth app in Bitrix24.

When to use a queue worker

Same as all event-driven flows: verify, enqueue, start from the worker with idempotency (instance check).

How Tech Titan can help

Tech Titan builds production Bitrix24 integrations around bizproc.workflow.start and its siblings — with authentication, field mapping, queue workers, retry logic, duplicate handling, and structured logs as standard. If this method is on your critical path, bring the requirement to a free audit call and leave with an architecture sketch.