Create a new Flow tasks.flow.Flow.create

Scope: task

Who can execute the method: any user who is not an extranet user

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

The flow must be linked to a group. If a group ID is not provided when creating the flow, a new group will be automatically created, consisting of the creator, 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 is provided below)

Parameter flowData

Required parameters are marked with *

Name `type`	Description
name* `string`	The name of the flow. Must be unique for each flow. 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, a new group will be automatically created
ownerId `integer`	The ID of the flow administrator. If not specified, the creator will be the administrator of the flow
templateId `integer`	The ID of the template that users will use to add tasks to the flow
plannedCompletionTime* `integer`	The planned time to complete the task in seconds
distributionType* `string`	Distribution type: `manually` — manual distribution `queue` — queue distribution `himself` — self-distribution More about distribution types can be found in the article Flows: Overview of Methods
responsibleList* `object`	IDs of employees who will receive tasks. For manual distribution, specify the ID of the flow moderator. For self-distribution or queue distribution, specify the IDs of employees or departments. For example: `[ [ 'department','3' ], [ 'department','17:F' ] ]` If you do not add the suffix `:F`, the system will select all sub-departments of the specified department according to the company structure
taskCreators `object`	A list of users who can add tasks to the flow in the format `{"<entity-type>": "<entity-id>"}`. For example: `[ [ 'user','3' ], [ 'department','17:F' ] ]` If you do not add the suffix `:F`, the system will select all sub-departments of the specified department according to the company structure. To allow all users to add tasks, specify the value `{"meta-user": "all-users"}`
matchWorkTime `integer`	Skip weekends and holidays when calculating the task deadline. Accepts values `0` and `1`. Default is `1`
responsibleCanChangeDeadline `integer`	Can the responsible person change the task deadline. Accepts values `0` and `1`. Default is `0`
notifyAtHalfTime `integer`	Notify the assignee 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`	Notify the flow administrator when the number of tasks in the queue exceeds this parameter. Default is `null`, meaning no notifications
notifyOnTasksInProgressOverflow `integer`	Notify the flow administrator when the number of tasks in progress exceeds this parameter. Default is `null`, meaning no notifications
notifyWhenEfficiencyDecreases `integer`	Notify the flow administrator when efficiency drops below this parameter. Default is `null`, meaning no notifications

Code Examples

How to Use Examples in Documentation

cURL (Webhook)

cURL (oAuth)

PHP

BX24.js

PHP CRest

curl -X POST \
        -H "Content-Type: 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://your-domain.bitrix24.com/rest/_USER_ID_/_CODE_/tasks.flow.Flow.create

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
        -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://your-domain.bitrix24.com/rest/tasks.flow.Flow.create

try
        {
        	const response = await $b24.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
        			}
        		}
        	);
        	
        	const result = response.getData().result;
        	console.info(result);
        }
        catch( error )
        {
        	console.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'); // connect 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
        ];
        
        // execute the request to the REST API
        $result = CRest::call(
            'tasks.flow.Flow.create',
            [
                'flowData' => $flowData
            ]
        );
        
        // Process the response from Bitrix24
        if ($result['error']) {
            echo 'Error: '.$result['error_description'];
        } else {
            print_r($result['result']);
        }

Response Handling

HTTP status: 200

{
            "result": {
                "id": 517,
                "creatorId": 1,
                "ownerId": 1,
                "groupId": 178,
                "templateId": 0,
                "efficiency": 0,
                "active": true,
                "plannedCompletionTime": 7200,
                "activity": "2024-09-02T15:27:29+00:00",
                "name": "Updated Flow Name",
                "description": "Updated description",
                "distributionType": "manually",
                "responsibleList": [
                    [
                        "user",
                        "3"
                    ]
                ],
                "demo": false,
                "responsibleCanChangeDeadline": true,
                "matchWorkTime": true,
                "taskControl": false,
                "notifyAtHalfTime": false,
                "notifyOnQueueOverflow": 10,
                "notifyOnTasksInProgressOverflow": 50,
                "notifyWhenEfficiencyDecreases": null,
                "taskCreators": [
                    [
                        "meta-user",
                        "all-users"
                    ]
                ],
                "team": [
                    [
                        "user",
                        "3"
                    ]
                ],
                "trialFeatureEnabled": false
            }
        }

Returned Data

Name `type`	Description
result `object`	Object with flow data
id `integer`	ID of the created flow
creatorId `integer`	ID of the flow creator. Read-only
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. Read-only
active `boolean`	Status of the flow's activity
plannedCompletionTime `integer`	Planned time to complete the task in seconds
activity `string`	Date and time of the last activity in the flow. Read-only
name `string`	Name of the flow
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. For manual distribution, this is the flow moderator
demo `boolean`	Indicates whether the flow is a demo. System parameter. Read-only
responsibleCanChangeDeadline `boolean`	Can the responsible person change the task deadline
matchWorkTime `boolean`	Whether to skip weekends and holidays when calculating the task deadline
taskControl `boolean`	Whether to send the completed task to the creator for review
notifyAtHalfTime `boolean`	Whether to notify the assignee at half the task deadline
notifyOnQueueOverflow `integer`	Number of tasks in the queue, exceeding which will send a notification to the flow administrator (if `null`, notifications are disabled)
notifyOnTasksInProgressOverflow `integer`	Number of tasks in progress, exceeding which will send a notification to the flow administrator (if `null`, notifications are disabled)
notifyWhenEfficiencyDecreases `integer`	Efficiency in percentage, below which a notification will be sent to the flow administrator (if `null`, notifications are disabled)
taskCreators `object`	List of users who can add tasks to the flow in the format `{"<object-type>": "<object-id>"}`. For example, `[{"user": 3}, {"department": "17:F"}]`. The element `{"meta-user": "all-users"}` means that all users can add tasks
team `object`	Flow team. For manual distribution, this includes all project participants to which the flow is linked, except for the moderator. For queue and self-distribution, the team is the same as in `responsibleList`
trialFeatureEnabled `boolean`	Indicates whether the trial period is enabled for the flow. System parameter. Read-only

Error Handling

HTTP status: 400

{
            "error": "0",
            "error_description": "Access denied or flow not found"
        }

Name `type`	Description
error `string`	String error code. It may consist of digits, Latin letters, and underscores
error_description `error_description`	Textual description of the error. The description is not intended to be shown to the end user in its raw form

Possible Error Codes

Code	Description	Additional Information
`0`	Access denied or flow not found	The account plan does not allow working with flows or the user does not have permission to create a flow
`0`	`Unknown error`	Unknown error
`0`	`'distributionType': field's value has an invalid value`	Invalid value for `distributionType` (similarly for other parameters)
`0`	A flow with this name already exists

Statuses and System Error Codes

HTTP Status: 20x, 40x, 50x

The errors described below may occur when calling any method.

Status	Code Error Message	Description
`500`	`INTERNAL_SERVER_ERROR` Internal server error	An internal server error has occurred, please contact the server administrator or Bitrix24 technical support
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	An internal server error has occurred, please contact the server administrator or Bitrix24 technical support
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	The request intensity limit has been exceeded
`405`	`ERROR_BATCH_METHOD_NOT_ALLOWED` Method is not allowed for batch usage	The current method is not allowed to be called using batch
`400`	`ERROR_BATCH_LENGTH_EXCEEDED` Max batch length exceeded	The maximum length of parameters passed to the batch method has been exceeded
`401`	`NO_AUTH_FOUND` Wrong authorization data	Invalid access token or webhook code
`400`	`INVALID_REQUEST` Https required	The methods must be called using the HTTPS protocol
`503`	`OVERLOAD_LIMIT` REST API is blocked due to overload	The REST API is blocked due to overload. This is a manual individual block, to remove it you need to contact Bitrix24 technical support
`403`	`ACCESS_DENIED` REST API is available only on commercial plans	The REST API is available only on commercial plans
`403`	`INVALID_CREDENTIALS` Invalid request credentials	The user whose access token or webhook was used to call the method lacks permissions
`404`	`ERROR_MANIFEST_IS_NOT_AVAILABLE` Manifest is not available	The manifest is not available
`403`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	The request requires higher privileges than those provided by the webhook token
`401`	`expired_token` The access token provided has expired	The provided access token has expired
`403`	`user_access_error` The user does not have access to the application	The user does not have access to the application. This means that the application is installed, but the account administrator has allowed access to this application only for specific users
`500`	`PORTAL_DELETED` Portal was deleted	The public part of the site is closed. To open the public part of the site on an on-premise installation, disable the option "Temporary closure of the public part of the site". Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Continue Learning

Overview of methods

Update Flow

Create a new Flow tasks.flow.Flow.create

Method ParametersMethod Parameters

Parameter flowDataParameter flowData

Code ExamplesCode Examples

Response HandlingResponse Handling

Returned DataReturned Data

Error HandlingError Handling

Possible Error CodesPossible Error Codes

Statuses and System Error CodesStatuses and System Error Codes

Continue LearningContinue Learning