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

Create a flow

POST /v1/tasks/flows

Creates a task flow — a shared queue from which tasks go to the responsible employees. Flow fields are passed in the flowData object and sent to Bitrix24 unchanged.

Request fields (body)

Field Type Required Description
FieldflowData Typeobject Requiredyes DescriptionFlow fields
FieldflowData.name Typestring Requiredyes DescriptionFlow name. You cannot create two flows with the same name in one Bitrix24 account
FieldflowData.plannedCompletionTime Typenumber Requiredyes DescriptionTime to complete a task, in seconds, for example 86400 — one day
FieldflowData.distributionType Typestring Requiredyes DescriptionHow tasks reach assignees: manually — a moderator assigns them, queue — in turn among the employees in responsibleList, himself — employees take tasks themselves
FieldflowData.responsibleList Typearray Requiredyes DescriptionWho receives the tasks: an array of pairs like ["user", "3"], where the second element is the employee ID as a string. With manually, the list holds the flow moderator. List: GET /v1/users
FieldflowData.groupId Typenumber Requiredno DescriptionID of the workgroup the flow is bound to. List: GET /v1/workgroups. If the field is not passed, a new group named after the flow is created
FieldflowData.ownerId Typenumber Requiredno DescriptionFlow administrator ID. List: GET /v1/users. If the field is not passed, the employee on whose behalf the request is made becomes the administrator
FieldflowData.description Typestring Requiredno DescriptionFlow description. Defaults to an empty string
FieldflowData.taskCreators Typearray Requiredno DescriptionWho can submit tasks to the flow: an array of pairs. [["meta-user", "all-users"]] — all employees
FieldflowData.matchWorkTime Typenumber Requiredno Description1 — weekends and holidays are skipped when the deadline is calculated, 0 — they are counted. Defaults to 1
FieldflowData.responsibleCanChangeDeadline Typenumber Requiredno Description1 — the assignee can change the task deadline, 0 — cannot. Defaults to 1
FieldflowData.taskControl Typenumber Requiredno Description1 — a completed task goes to its creator for review, 0 — no review. Defaults to 0
FieldflowData.notifyAtHalfTime Typenumber Requiredno Description1 — remind the assignee halfway to the deadline, 0 — no reminder. Defaults to 0
FieldflowData.notifyOnQueueOverflow Typenumber Requiredno DescriptionNotify the flow administrator when the number of tasks in the queue exceeds this value. Defaults to null — no notification
FieldflowData.notifyOnTasksInProgressOverflow Typenumber Requiredno DescriptionNotify the flow administrator when the number of tasks in progress exceeds this value. Defaults to null — no notification
FieldflowData.notifyWhenEfficiencyDecreases Typenumber Requiredno DescriptionNotify the flow administrator when efficiency drops below this value, in percent. Defaults to null — no notification
FieldanalyticsParams Typeobject Requiredno DescriptionInternal Bitrix24 analytics tags. They do not affect the flow

The body must not contain keys other than flowData and analyticsParams. The matchWorkTime, responsibleCanChangeDeadline, taskControl, and notifyAtHalfTime flags are passed as the numbers 1 and 0 and come back in the response as true and false.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/flows" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flowData": {
      "name": "Request processing",
      "description": "Customer requests from the website",
      "plannedCompletionTime": 86400,
      "distributionType": "queue",
      "responsibleList": [["user", "3"]]
    }
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/flows" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flowData": {
      "name": "Request processing",
      "description": "Customer requests from the website",
      "plannedCompletionTime": 86400,
      "distributionType": "queue",
      "responsibleList": [["user", "3"]]
    }
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/flows', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    flowData: {
      name: 'Request processing',
      description: 'Customer requests from the website',
      plannedCompletionTime: 86400,
      distributionType: 'queue',
      responsibleList: [['user', '3']],
    },
  }),
})

const { success, data } = await res.json()
if (success) {
  console.log('Flow ID:', data.id, 'Group ID:', data.groupId)
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/flows', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    flowData: {
      name: 'Request processing',
      description: 'Customer requests from the website',
      plannedCompletionTime: 86400,
      distributionType: 'queue',
      responsibleList: [['user', '3']],
    },
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typeobject DescriptionThe created flow. The set of fields is the same as in the GET /v1/tasks/flows/:flowId response
Fielddata.id Typenumber DescriptionID of the new flow
Fielddata.creatorId Typenumber DescriptionID of the employee on whose behalf the request was made
Fielddata.ownerId Typenumber DescriptionFlow administrator ID
Fielddata.groupId Typenumber DescriptionID of the flow's workgroup. If the request had no groupId, the ID of the created group
Fielddata.active Typeboolean Descriptiontrue — the flow is enabled. A new flow is created enabled
Fielddata.efficiency Typenumber DescriptionFlow efficiency in percent. For a new flow — 100
Fielddata.activity Typestring DescriptionDate and time of the flow's activity in ISO 8601 format. For a new flow — the moment of creation
Fielddata.taskCreators Typearray DescriptionAn empty array, even if taskCreators was passed in the request. The saved value is returned by GET /v1/tasks/flows/:flowId
Fielddata.team Typearray DescriptionAn empty array. The flow team is returned by GET /v1/tasks/flows/:flowId

Fields from the request come back with the passed values; fields that were not passed come back with the defaults from the request fields table.

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 20,
    "creatorId": 1,
    "ownerId": 1,
    "groupId": 178,
    "templateId": 0,
    "efficiency": 100,
    "active": true,
    "plannedCompletionTime": 86400,
    "activity": "2026-10-20T00:23:04+00:00",
    "name": "Request processing",
    "description": "Customer requests from the website",
    "distributionType": "queue",
    "responsibleList": [
      ["user", "3"]
    ],
    "demo": false,
    "responsibleCanChangeDeadline": true,
    "matchWorkTime": true,
    "matchSchedule": false,
    "taskControl": false,
    "notifyAtHalfTime": false,
    "notifyOnQueueOverflow": null,
    "notifyOnTasksInProgressOverflow": null,
    "notifyWhenEfficiencyDecreases": null,
    "taskCreators": [],
    "team": [],
    "trialFeatureEnabled": false
  }
}

Error response example

422 — the required distributionType field is not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Property distributionType cannot be null",
    "b24Code": "0"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionThe body is not an object or contains keys other than flowData and analyticsParams. Message: body must be an object with supported fields only
HTTP400 CodeINVALID_PARAMS DescriptionflowData is not passed or is not an object. Message: flowData must be an object
HTTP400 CodeINVALID_PARAMS DescriptionanalyticsParams is not an object. Message: analyticsParams must be an object
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not found
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe key has neither the task nor the tasks scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode. error.details.switchUrl holds the address of the section where the mode is changed
HTTP422 CodeBITRIX_ERROR DescriptionA required field is not passed. Messages: Property name cannot be null, Property plannedCompletionTime cannot be null, Property distributionType cannot be null, 'responsibleList': field's value must not be empty
HTTP422 CodeBITRIX_ERROR DescriptiondistributionType is not one of manually, queue, himself. Message: distributionType: unexpected value
HTTP422 CodeBITRIX_ERROR DescriptiongroupId is not passed, and a group with the same name as the flow already exists on the portal, including one left over from a deleted flow. Message: A group with this name already exists, error.b24Code is ERROR_GROUP_NAME_EXISTS
HTTP429 CodeRATE_LIMITED DescriptionThe request rate to Bitrix24 or to the platform is exceeded. Retry after the delay in the Retry-After header
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unreachable or returned a server error
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 did not respond in time

Full list of common API errors — Errors.

Known specifics

Creation is not retried automatically. The 502 BITRIX_UNAVAILABLE and 503 BITRIX_TIMEOUT responses do not tell whether the flow was created, and the platform does not retry such a request on its own. Before sending it again, look for the flow by name in GET /v1/tasks/flows.

See also