Create a Flow tasks.flow.Flow.create

Choose a tool for developing with an AI agent:

  • use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
  • use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation

Scope: task

Who can execute the method: Bitrix24 administrator or a user with the permission to create flows. Extranet users cannot create flows

The method tasks.flow.Flow.create creates a flow.

A flow is always linked to a group. If groupId is not passed, a new group is created. It includes the flow creator, the flow administrator, and the flow team.

Method Parameters

Required parameters are marked with *

Name
type

Description

flowData*
object

Field values for creating the flow (detailed description)

Parameter flowData

Required parameters are marked with *

Name
type

Description

name*
string

The name of the flow, from 1 to 255 characters. Must be unique within Bitrix24.

You can check the name using the method tasks.flow.Flow.isExists

description
string

Description of the flow

groupId
integer

The ID of the group to which the flow will be linked.

If not specified, the method creates a new group named after the flow. If a group with this name already exists, the method returns the ERROR_GROUP_NAME_EXISTS error

ownerId
integer

The ID of the flow administrator.

If not specified, the creator will be the flow administrator

templateId
integer

The ID of the template that users will use to add tasks to the flow

plannedCompletionTime*
integer

Number of seconds allowed to complete a task, at least 3600 (one hour). The flow calculates the task deadline from this time

distributionType*
string

Type of distribution:

  • manually — manual distribution
  • queue — distribution by queue
  • himself — self-distribution

More about distribution types can be found in the article Flows: Overview of Methods

responsibleList*
array

Employees or departments that will receive tasks. Each element is a "type — ID" pair.

For manual distribution, specify a single pair with the flow moderator, for example ["user", "1"].

For self-distribution or queue distribution, specify employees or departments. For example:

[
            [
                'department','3'
            ],
            [
                'department','17:F'
            ]
        ]
        

A department without the :F suffix is included together with all its sub-departments according to the company structure. With the :F suffix, only the department itself is included

taskCreators
array

Who can add tasks to the flow: users or departments. Each element is a ["<object-type>", "<object-id>"] pair, for example:

[
            [
                'user','3'
            ],
            [
                'department','17:F'
            ]
        ]
        

A department without the :F suffix is included together with all its sub-departments according to the company structure. With the :F suffix, only the department itself is included

To allow all users to add tasks, pass the pair ["meta-user", "all-users"]

matchWorkTime
integer

Skip weekends and holidays when calculating the task deadline.

Accepts values 0 and 1. Default is 1

matchSchedule
integer

Count the task completion time only during working hours according to the work schedule.

Accepts values 0 and 1. Default is 0

responsibleCanChangeDeadline
integer

Can the responsible person change the task deadline.

Accepts values 0 and 1. Default is 1

notifyAtHalfTime
integer

Notify the performer at half the task deadline.

Accepts values 0 and 1. Default is 0

taskControl
integer

Send the completed task to the creator for review.

Accepts values 0 and 1. Default is 0

notifyOnQueueOverflow
integer

Number of tasks in the queue above which the flow administrator receives a notification.

Default is null, no notification

notifyOnTasksInProgressOverflow
integer

Number of tasks in progress above which the flow administrator receives a notification.

Default is null, no notification

notifyWhenEfficiencyDecreases
integer

Efficiency percentage below which the flow administrator receives a notification.

Default is null, no notification

Code Examples

How to Use Examples in Documentation

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{
            "flowData": {
                "name": "Unique Flow Name",
                "description": "Flow description",
                "plannedCompletionTime": 7200,
                "distributionType": "manually",
                "responsibleList": [["user","3"]],
                "taskCreators": [["meta-user","all-users"]],
                "matchWorkTime": 1,
                "notifyAtHalfTime": 0
            }
        }' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/tasks.flow.Flow.create
        
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{
            "flowData": {
                "name": "Unique Flow Name",
                "description": "Flow description",
                "plannedCompletionTime": 7200,
                "distributionType": "manually",
                "responsibleList": [["user","3"]],
                "taskCreators": [["meta-user","all-users"]],
                "matchWorkTime": 1,
                "notifyAtHalfTime": 0
            },
            "auth": "**put_access_token_here**"
        }' \
        https://**put_your_bitrix24_address**/rest/tasks.flow.Flow.create
        
// This snippet is an ES module: top-level await requires type="module" or a bundler.
        // $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
        import { Text } from '@bitrix24/b24jssdk'
        import type { B24Frame, ISODate } from '@bitrix24/b24jssdk'
        
        declare const $b24: B24Frame
        
        // Shape of the payload returned in result (match the "response handling" section of the page)
        type FlowCreateResult = {
          id: number
          creatorId: number
          ownerId: number
          groupId: number
          templateId: number
          efficiency: number
          active: boolean
          plannedCompletionTime: number
          activity: ISODate
          name: string
          description: string
          distributionType: string
          responsibleList: string[][]
          demo: boolean
          responsibleCanChangeDeadline: boolean
          matchWorkTime: boolean
          matchSchedule: boolean
          taskControl: boolean
          notifyAtHalfTime: boolean
          notifyOnQueueOverflow: number | null
          notifyOnTasksInProgressOverflow: number | null
          notifyWhenEfficiencyDecreases: number | null
          taskCreators: string[][]
          team: string[][]
          trialFeatureEnabled: boolean
        }
        
        try {
          const response = await $b24.actions.v2.call.make<FlowCreateResult>({
            method: 'tasks.flow.Flow.create',
            params: {
              flowData: {
                name: 'Unique Flow Name',
                description: 'Flow description',
                plannedCompletionTime: 7200,
                distributionType: 'manually',
                responsibleList: [['user', '3']],
                taskCreators: [['meta-user', 'all-users']],
                matchWorkTime: 1,
                notifyAtHalfTime: 0,
              },
            },
            requestId: Text.getUuidRfc4122()
          })
        
          // The payload is available only on a successful response
          if (!response.isSuccess) {
            console.error(response.getErrorMessages().join('; '))
          } else {
            const result = response.getData()!.result
            console.info('Created flow:', result.id, result.name, result.active)
          }
        } catch (error) {
          // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
          console.error(error)
        }
        
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
        <script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
        <script>
          async function createFlow() {
            try {
              // Initialize the SDK inside a Bitrix24 frame
              const $b24 = await B24Js.initializeB24Frame()
        
              const response = await $b24.actions.v2.call.make({
                method: 'tasks.flow.Flow.create',
                params: {
                  flowData: {
                    name: 'Unique Flow Name',
                    description: 'Flow description',
                    plannedCompletionTime: 7200,
                    distributionType: 'manually',
                    responsibleList: [['user', '3']],
                    taskCreators: [['meta-user', 'all-users']],
                    matchWorkTime: 1,
                    notifyAtHalfTime: 0,
                  },
                },
                requestId: B24Js.Text.getUuidRfc4122()
              })
        
              // The payload is available only on a successful response
              if (!response.isSuccess) {
                console.error(response.getErrorMessages().join('; '))
                return
              }
        
              const result = response.getData().result
              console.info('Created flow:', result.id, result.name, result.active)
            } catch (error) {
              // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
              console.error(error)
            }
          }
        
          document.addEventListener('DOMContentLoaded', createFlow)
        </script>
        
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
        
        flow_data = {
            "name": "Unique Flow Name",
            "description": "Flow description",
            "plannedCompletionTime": 7200,
            "distributionType": "manually",
            "responsibleList": [
                [
                    "user",
                    "3",
                ],
            ],
            "taskCreators": [
                [
                    "meta-user",
                    "all-users",
                ],
            ],
            "matchWorkTime": 1,
            "notifyAtHalfTime": 0,
        }
        
        try:
            bitrix_response = client.tasks.flow.flow.create(
                flow_data=flow_data,
            ).response
            result = bitrix_response.result
            print(result)
        except BitrixAPIError as error:
            print(
                "Bitrix API error",
                f"error: {error.error}",
                f"error_description: {error.error_description}",
                sep="\n",
            )
        except BitrixSDKException as error:
            print(f"Bitrix SDK error: {error.message}")
        except Exception as error:
            print(f"Unexpected error: {error}")
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'tasks.flow.Flow.create',
                    [
                        'flowData' => [
                            'name'                  => 'Unique Flow Name',
                            'description'           => 'Flow description',
                            'plannedCompletionTime' => 7200,
                            'distributionType'      => 'manually',
                            'responsibleList'       => [
                                ['user', '3']
                            ],
                            'taskCreators'          => [
                                ['meta-user', 'all-users']
                            ],
                            'matchWorkTime'         => 1,
                            'notifyAtHalfTime'      => 0
                        ]
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Success: ' . print_r($result, true);
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error creating flow: ' . $e->getMessage();
        }
        
BX24.callMethod(
            'tasks.flow.Flow.create',
            {
                flowData: {
                    name: 'Unique Flow Name',
                    description: 'Flow description',
                    plannedCompletionTime: 7200,
                    distributionType: 'manually',
                    responsibleList: [
                        [
                            'user','3'
                        ]
                    ],
                    taskCreators: [
                        [
                            'meta-user','all-users'
                        ]
                    ],
                    matchWorkTime: 1,
                    notifyAtHalfTime: 0
                }
            },
            function(result) {
                if (result.error()) {
                    console.error(result.error());
                } else {
                    console.info(result.data());
                }
            }
        );
        
require_once('crest.php'); // connecting CRest PHP SDK
        
        $flowData = [
            "name" => "Unique Flow Name",
            "description" => "Flow description",
            "plannedCompletionTime" => 7200,
            "distributionType" => "manually",
            "responsibleList" => [["user", "3"]],
            "taskCreators" => [["meta-user", "all-users"]],
            "matchWorkTime" => 1,
            "notifyAtHalfTime" => 0
        ];
        
        // executing a request to the REST API
        $result = CRest::call(
            'tasks.flow.Flow.create',
            [
                'flowData' => $flowData
            ]
        );
        
        // Processing the response from Bitrix24
        if ($result['error']) {
            echo 'Error: '.$result['error_description'];
        } else {
            print_r($result['result']);
        }
        
// client and ctx are already created — see the Go SDK section
        res, err := client.Core().Call(ctx, "tasks.flow.Flow.create", b24.Params{
        	"flowData": b24.Params{
        		"name":                  "Unique Flow Name",
        		"description":           "Flow description",
        		"plannedCompletionTime": 7200,
        		"distributionType":      "manually",
        		"responsibleList": []any{
        			[]string{"user", "3"},
        		},
        		"taskCreators": []any{
        			[]string{"meta-user", "all-users"},
        		},
        		"matchWorkTime":    1,
        		"notifyAtHalfTime": 0,
        	},
        })
        if err != nil {
        	return fmt.Errorf("tasks.flow.Flow.create: %w", err)
        }
        
        var item struct {
        	ID         b24.ID `json:"id"`
        	CreatorID  b24.ID `json:"creatorId"`
        	OwnerID    b24.ID `json:"ownerId"`
        	GroupID    b24.ID `json:"groupId"`
        	TemplateID b24.ID `json:"templateId"`
        	Efficiency int    `json:"efficiency"`
        }
        if err := json.Unmarshal(res.Result, &item); err != nil {
        	return fmt.Errorf("parse response: %w", err)
        }
        fmt.Println(item.ID, item.CreatorID)
        

Response Handling

HTTP status: 200

{
            "result": {
                "id": 7,
                "creatorId": 1,
                "ownerId": 1,
                "groupId": 6,
                "templateId": 0,
                "efficiency": 100,
                "active": true,
                "plannedCompletionTime": 7200,
                "activity": "2026-11-06T11:59:13+03:00",
                "name": "Unique Flow Name",
                "description": "Flow description",
                "distributionType": "manually",
                "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
            },
            "time": {
                "start": 1793955553,
                "finish": 1793955554.612625,
                "duration": 1.6126248836517334,
                "processing": 1,
                "date_start": "2026-11-06T11:59:13+03:00",
                "date_finish": "2026-11-06T11:59:14+03:00"
            }
        }
        

Returned Data

Name
type

Description

result
object

Object containing flow data (detailed description)

time
time

Information about the request execution time

Object result

Name
type

Description

id
integer

ID of the created flow

creatorId
integer

ID of the flow creator

ownerId
integer

ID of the flow administrator

groupId
integer

ID of the group to which the flow is linked

templateId
integer

ID of the template used to create tasks in the flow

efficiency
integer

Efficiency of the flow in percentage

active
boolean

Whether the flow is enabled

plannedCompletionTime
integer

Number of seconds allowed to complete a task, at least 3600 (one hour). The flow calculates the task deadline from this time

activity
datetime

Date and time of the last activity in the flow

name
string

Flow name

description
string

Description of the flow

distributionType
string

Type of task distribution in the flow

responsibleList
array

List of responsible persons for tasks in the flow, with "type — ID" pairs as elements. For manual distribution, this is the flow moderator

demo
boolean

Indicates whether the flow is a demo. System parameter

responsibleCanChangeDeadline
boolean

Can the responsible person change the task deadline

matchWorkTime
boolean

Whether to skip weekends and holidays when calculating the task deadline

matchSchedule
boolean

Whether to count the task completion time only during working hours according to the work schedule

taskControl
boolean

Whether to send the completed task to the creator for review

notifyAtHalfTime
boolean

Whether to notify the performer at half the task deadline

notifyOnQueueOverflow
integer

Number of tasks in the queue above which the flow administrator receives a notification. null — the notification is disabled

notifyOnTasksInProgressOverflow
integer

Number of tasks in progress above which the flow administrator receives a notification. null — the notification is disabled

notifyWhenEfficiencyDecreases
integer

Efficiency percentage below which the flow administrator receives a notification. null — the notification is disabled

taskCreators
array

Who can add tasks to the flow. Each element is a "type — ID" pair, for example ["user", "3"] or ["department", "17:F"]. The pair ["meta-user", "all-users"] means that all users can add tasks.

In the response of this method, the field is empty even if task creators are set. The current list is returned by the tasks.flow.Flow.get method

team
array

Flow team.

For manual distribution, this includes all members of the group linked to the flow, except for the moderator.

For queue and self-distribution, the team is the same as in responsibleList.

Elements are "type — ID" pairs, as in taskCreators. In the response of this method, the field is empty; the current team is returned by the tasks.flow.Flow.get method

trialFeatureEnabled
boolean

Indicates whether the trial period is enabled for the flow. System parameter

Error Handling

HTTP status: 400

{
            "error": "0",
            "error_description": "'responsibleList': field's value must not be empty"
        }
        

Name
type

Description

error
string

String error code. It consists of digits, Latin letters, and underscores. It may arrive empty — in that case only error_description shows the reason

error_description
string

Error message for the developer. Do not show it to the end user without processing

Possible Error Codes

Status

Code

Description

Value

400

0

Cannot find flow

The user does not have the permission to create flows, a group with this groupId does not exist, or the user does not have access to it

400

0

Property name cannot be null

A required field is not passed. Instead of name, the text contains the name of the missing field: plannedCompletionTime or distributionType

400

0

'name': field's length must be greater than 1 and less than 255

The name is empty or longer than 255 characters

400

0

'plannedCompletionTime': field's value must be greater than 3600

The completion time is less than an hour: plannedCompletionTime is less than 3600 seconds

400

0

distributionType: unexpected value

distributionType contains a value that is not in the list

400

0

'responsibleList': field's value must not be empty

responsibleList is not passed or is an empty array

400

0

Template 99999 doesn't exists

A template with this templateId does not exist. Instead of 99999, the text contains the passed ID

400

0

A flow with this name already exists

The flow name is already taken in Bitrix24. You can check the name in advance using the method tasks.flow.Flow.isExists

400

ERROR_GROUP_NAME_EXISTS

Workgroup with this name already exists

groupId is not passed, and a group named after the flow already exists, so a new group cannot be created. Pass groupId or choose a different flow name

400

0

Unknown error. [Flow: 198]

Internal error. The number in brackets indicates where in the code the error occurred; it helps support find the cause

Statuses and System Error Codes

HTTP Status: 4xx, 5xx

The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.

Status

Code
Error Message

Description

500

INTERNAL_SERVER_ERROR
Internal server error

An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support

503

QUERY_LIMIT_EXCEEDED
Too many requests

The request intensity limit has been exceeded

429

OPERATION_TIME_LIMIT
Method is blocked due to operation time limit

The method is blocked because the request resource intensity limit has been exceeded. The block is lifted automatically once the accumulated execution time of the method no longer exceeds the limit

401

NO_AUTH_FOUND
Wrong authorization data

The request contains no authorization data: neither an access token nor a webhook code was passed

401

INVALID_REQUEST
Https required

Methods are called over the HTTPS protocol only

401

OVERLOAD_LIMIT
REST API is blocked due to overload

The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support

401

ACCESS_DENIED
REST is available only on commercial plans

REST API access is not active for this account. In Bitrix24 Cloud, check the current plan or trial status: Vibe+ plans include REST API access, while Essentials plans do not. A webhook receives a different error message — REST is available only by subscription

401

INVALID_CREDENTIALS
Invalid request credentials

No active webhook with the specified user identifier and secret code was found

404

ERROR_METHOD_NOT_FOUND
Method not found!

No method with this name was found. The name is misspelled, the method does not exist in the REST API, or it is unavailable without the required scope

401

insufficient_scope
The request requires higher privileges than provided by the webhook token

The request requires broader permissions than the token has: for a webhook these are the permissions granted to it, for an application it is the scope. For an application, the error message ends with provided by the access token

401

expired_token
The access token provided has expired

The access token has expired

401

user_access_error
The user does not have access to the application

The application is installed, but the Bitrix24 administrator has granted access to it only to specific users

403

PORTAL_DELETED
Portal was deleted

The public part of the site is closed. To open it on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Continue Learning