For AI agents: markdown of this page — /docs-content-en/entities/bizproc-templates.md documentation index — /llms.txt

Business process templates

A business process template is a process blueprint bound to a document type: a deal, a lead, a list item, a Drive document. Bitrix24 starts a process from the template when the document is created or changed. An application uploads a ready-made template as a .bpt file, changes its settings, and deletes it.

Templates can be read, uploaded, updated, and deleted only with an authorization key vibe_app_… — an API key vibe_api_… cannot be used for these methods. Only a Bitrix24 account administrator can manage templates.

Bitrix24 API: bizproc.workflow.template.* Scope: bizproc

Upload a template

POST /v1/bizproc-templates

Uploads a business process template from a BPT file and binds it to a document type. Fields are passed flat at the JSON root — without a fields wrapper.

Request fields (body)

Field Type Req. Description
templateData array yes Template file as two elements — the file name and its contents in base64. Example: ["process.bpt", "eNrlWNtO41YUfe..."]
documentType array yes Document type [module, object, type]. Values:
["crm", "CCrmDocumentLead", "LEAD"] — leads
["crm", "CCrmDocumentContact", "CONTACT"] — contacts
["crm", "CCrmDocumentCompany", "COMPANY"] — companies
["crm", "CCrmDocumentDeal", "DEAL"] — deals
["crm", "Bitrix\\Crm\\Integration\\BizProc\\Document\\Quote", "QUOTE"] — quotes
["crm", "Bitrix\\Crm\\Integration\\BizProc\\Document\\SmartInvoice", "SMART_INVOICE"] — invoices
["crm", "Bitrix\\Crm\\Integration\\BizProc\\Document\\Dynamic", "DYNAMIC_<entityTypeId>"] — smart processes, <entityTypeId> from the entityTypeId field in GET /v1/smart-processes
["lists", "BizprocDocument", "iblock_<id>"] — processes in the Feed
["lists", "Bitrix\\Lists\\BizprocDocumentLists", "iblock_<id>"] — lists in workgroups
["disk", "Bitrix\\Disk\\BizProcDocument", "STORAGE_<id>"] — Drive documents
name string yes Template name. Bitrix24 rejects an empty value
description string no Template description
autoExecute number no Autostart condition: 0 — no autostart, 1 — on document creation, 2 — on change, 3 — on creation and change. Defaults to 0

Examples

Only an authorization key can upload templates — both examples send the authorization key and the Authorization: Bearer header. The session token is issued by OAuth authorization, is valid for 24 hours, and cannot be renewed — Passing the key.

curl — authorization key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/bizproc-templates" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "documentType": ["crm", "CCrmDocumentDeal", "DEAL"],
    "name": "Deal approval",
    "description": "Uploaded from the application",
    "autoExecute": 0,
    "templateData": ["approval.bpt", "eNrlWNtO41YUfe..."]
  }'

JavaScript — authorization key

javascript 
import { readFile } from 'node:fs/promises'

const file = await readFile('approval.bpt')

const res = await fetch('https://vibecode.bitrix24.com/v1/bizproc-templates', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    documentType: ['crm', 'CCrmDocumentDeal', 'DEAL'],
    name: 'Deal approval',
    description: 'Uploaded from the application',
    autoExecute: 0,
    templateData: ['approval.bpt', file.toString('base64')],
  }),
})

const { success, data } = await res.json()
console.log(`Template identifier: ${data.id}`)

Response fields

Field Type Description
success boolean Always true on success
data.id number Identifier of the created template. Used in the update and delete paths

Response example

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

Error response example

400 — the template file was not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "Body field \"templateData\" is required to create bizprocTemplate."
  }
}

Errors

HTTP Code Description
400 MISSING_REQUIRED_FIELDS The templateData field was not passed
422 BITRIX_ERROR name was not passed — message Empty template name!, the b24Code field contains ERROR_TEMPLATE_VALIDATION_FAILURE
422 BITRIX_ERROR documentType was not passed or an unknown type was given — message Incorrect field DOCUMENT_TYPE!, the b24Code field contains ERROR_TEMPLATE_VALIDATION_FAILURE
422 BITRIX_ERROR The file contents were not recognized as a template. Bitrix24 returns the message text in the account language
403 OAUTH_REQUIRED The request was sent with an API key. Only an authorization key can upload templates
401 TOKEN_MISSING Authorization key without the Authorization: Bearer header
401 WRONG_AUTH_SCHEME The authorization key was sent in the Authorization: Bearer header. The key goes in X-Api-Key, while Authorization: Bearer carries the session token
401 INVALID_SESSION The session token has expired or is invalid — authorize again
403 SCOPE_DENIED The key lacks the bizproc scope

On a Bitrix24-side error the error object gains a b24Code field — the machine-readable reason code.

The full list of common API errors — Errors.

Known specifics

The .bpt file is prepared in Bitrix24. Configure the process in the business process designer and export it to a file — that file is what you pass in templateData. The contents of a .bpt file cannot be assembled through the API, so preparing the file stays a manual step.

The response does not show what was written. Only id is returned, so check the applied values by reading the record through GET /v1/bizproc-templates with a filter by id.

See also