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, task results, and methods for retrieving field schemas (*.field.list / *.field.get). Everything related to checklists, time tracking, and history is available in REST v2.

Task CardTask Card

The task card includes data about the task and a chat for discussion. 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. For more details on the changes, refer to the article New Task Card: 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 numeric identifiers in the fields:

• creatorId — the Creator of the task. Specify this when creating the task. To get information about the Creator, request the object's 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 obtain data about the responsible person through: "select": ["responsible.name", "responsible.email"].

• accomplices — Participants. These 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. These are passed as an array of identifiers when creating or updating the task. Request data via: "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. Task discussions 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 using 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"].

Task Results. The result captures the outcome of the work on the task. To work with results, use the methods in the section Task Results in REST 3.0. They allow you to manually add a result, create it from a message in the task chat, modify the result text, retrieve a list of results, and delete unnecessary results.

CRM Objects. You can link CRM objects to a task: leads, contacts, companies, deals, invoices, and SPAs. The identifiers of such objects are passed in the crmItemIds field in a prefixed format, for example, C_3 for a contact. Data about related CRM objects 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 obtained 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 CardWidgets in the Task Card

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

Where to Place WidgetsWhere to Place Widgets

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

• 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 kanban group mode,

• TASK_ROBOT_DESIGNER_TOOLBAR — item next to the Automation rule settings.

Additional Operations on the TaskAdditional Operations on the Task

The following capabilities work only through REST v2:

• Working with checklists task.checklistitem.*

• 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: tasks

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.result.add	Adds a result to the task
tasks.task.result.addfromchatmessage	Creates a result from a task chat message
tasks.task.result.update	Updates the result text
tasks.task.result.list	Returns a list of task results
tasks.task.result.delete	Deletes a task result
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 task file fields 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