Tasks in REST 3.0: Overview of Methods

Tasks in Bitrix24 are a tool for organizing work, ranging from simple assignments to complex projects. They enable teams to track execution, manage deadlines, and distribute responsibilities.

Quick Navigation: All Methods

User Documentation: Bitrix24 Tasks

In REST 3.0, task methods have received an updated architecture, a unified response format, and support for relationships between objects. REST 3.0 now covers basic operations on tasks, working with task chat, attaching files, and methods for retrieving field schemas (*.field.list / *.field.get). Everything related to checklists, time tracking, results, and history is available in REST v2.

Task Detail FormTask Detail Form

The task detail form includes data about the task and a chat for discussions. The task itself can be divided into logical blocks:

• Task description,
• System fields: responsible, Creator, deadline, status,
• Relationships: subtasks, dependencies on other tasks, links to CRM entities, files,
• Additional data: checklists, results, time tracking.

Starting from module version tasks 25.700.0, comments have been moved to the task chat. More about the changes can be found in the article New Task Detail Form: Overview of Changes.

Relationships with Other ObjectsRelationships with Other Objects

Parent Task. A task can have subtasks. In this case, it is considered a parent task. You can add a link to the parent task using the parentId parameter. To get details about the parent task, use the parameter "select": ["parent.title", "parent.description"] in the method tasks.task.get.

Users. A task is linked to users by numerical identifiers in the fields:

• creatorId — the Creator of the task. Specify it when creating the task. To get information about the Creator, request the object fields via "select": ["creator.name", "creator.email"].

• responsibleId — the responsible person for the task. This is a required field when creating the task. You can retrieve data about the responsible person through: "select": ["responsible.name", "responsible.email"].

• accomplices — Participants. They are passed as an array of identifiers when creating or updating the task. To get information about them: "select": ["accomplices.name", "accomplices.email"].

• auditors — observers. They are passed as an array of identifiers when creating or updating the task. Request data through: "select": ["auditors.name", "auditors.email"].

• changedById — the identifier of the user who last modified the task. Retrieve data: "select": ["changedBy.name", "changedBy.email"].

• statusChangedById — the user who changed the task status. Retrieve data: "select": ["statusChangedBy.name", "statusChangedBy.email"].

• closedById — the user who closed the task. Retrieve data: "select": ["closedBy.name", "closedBy.email"].

Group or Project. A task can belong to a group or project. Link the task to a group using the groupId parameter. To get information about the group to which the task is linked, request: "select": ["group.name", "group.image"].

E-mail. A task can be created from an e-mail, in which case it will have a link to the e-mail. The e-mail identifier is stored in the emailId field. To get information about the e-mail, use: "select": ["email.title", "email.from", "email.body"].

Task Chat. Discussions about the task take place in the chat. The task chat identifier is returned in the chatId field. To get data about the chat, request: "select": ["chat.id", "chat.entityId", "chat.entityType"].

Flow. A task can be created within a Flow — a mechanism for automatic task distribution. Link the task to the flow via the flowId parameter. To get data about the flow, use: "select": ["flow.name"].

Time Tracking. If time tracking is enabled for the task, data on the minutes and seconds spent can be accessed via "select": ["elapsedTime.minutes", "elapsedTime.seconds", "elapsedTime.text"].

CRM Entities. You can link CRM entities to a task: leads, contacts, companies, deals, invoices, and SPAs. The identifiers of such entities are passed in the crmItemIds field in a prefixed format, for example, C_3 for a contact. Data about related CRM entities is not available directly — they should be requested separately through CRM methods.

Drive Files. You can upload files from Drive to the task.

• If the file has not yet been uploaded to Bitrix.Drive, use the method disk.storage.uploadfile or disk.folder.uploadfile to upload the file.

• If you want to attach an already existing file on the drive, use the methods disk.storage.getchildren or disk.folder.getchildren to find out the file identifier.

Pass the received file identifier to the method tasks.task.file.attach.

How to Work with Task ChatHow to Work with Task Chat

Starting from module version tasks 25.700.0, comments in tasks have been replaced with chat. The task method tasks.task.chat.message.send creates and sends a message in the task chat.

To perform other actions with chat messages, use the messenger methods:

• im.message.update — updates a message,

• im.message.delete — deletes a message. The message identifier can be obtained in the response to the message creation method tasks.task.chat.message.send or from the chat history.

• im.dialog.messages.get — returns the chat history by identifier. To get the task chat identifier, request: "select": ["chat.id"] in the method tasks.task.get.

Widgets in the Task Detail FormWidgets in the Task Detail Form

The task detail form can be extended with widgets — external applications embedded in the interface. This allows users to work with integrations without leaving the task detail form.

Where to Place WidgetsWhere to Place Widgets

Starting from module version tasks 25.700.0, all embedding locations in the task detail form have been consolidated into a single "Applications" block at the bottom of the task detail form:

• TASK_VIEW_TAB

• TASK_VIEW_SIDEBAR

• TASK_VIEW_TOP_PANEL

Embedding locations on the general task page remain unchanged:

• TASK_LIST_CONTEXT_MENU — item in the context menu of the task list,

• TASK_USER_LIST_TOOLBAR — item in the dropdown menu of the "My Plan" mode,

• TASK_GROUP_LIST_TOOLBAR — item in the dropdown menu of the group kanban mode,

• TASK_ROBOT_DESIGNER_TOOLBAR — item next to the Automation rule settings.

Additional Operations on TasksAdditional Operations on Tasks

The following capabilities work only through REST v2:

• Working with checklists task.checklistitem.*

• Retrieving task results tasks.task.result.list

• Tracking elapsed time task.elapseditem.*

• Managing custom fields task.item.userfield.*

• Retrieving change history tasks.task.history.list

• Working with kanban stages of groups and "My Plan" task.stages.*

• Managing Flows tasks.flow.Flow.*

• Managing Scrum objects tasks.api.scrum.*

Overview of MethodsOverview of Methods

Scope: task

Who can execute the method: depending on the method

Method	Description
tasks.task.add	Creates a new task
tasks.task.file.attach	Attaches Drive files to the task
tasks.task.get	Retrieves task data with support for relationships via select
tasks.task.chat.message.send	Sends a message in the task chat
tasks.task.update	Updates the task
tasks.task.delete	Deletes the task
tasks.task.access.get	Checks access permissions for the task
tasks.task.field.list	Returns a list of task fields
tasks.task.field.get	Returns the description of a task field by name
tasks.task.access.field.list	Returns a list of task access permission fields
tasks.task.access.field.get	Returns the description of a task access permission field by name
tasks.task.file.field.list	Returns a list of task file fields
tasks.task.file.field.get	Returns the description of a task file field by name
tasks.task.chat.message.field.list	Returns a list of task chat message fields
tasks.task.chat.message.field.get	Returns the description of a task chat message field by name

Continue LearningContinue Learning

• Task Fields in REST 3.0
• Overview of REST API 3.0