Task Fields in REST 3.0
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
This page helps you understand the task fields in REST 3.0. They are returned by the methods tasks.task.get, tasks.task.list, and tasks.task.add, and accepted by the methods tasks.task.add and tasks.task.update. In the section Task Object, all task fields are described, while other sections cover the fields of related objects.
Some task fields exist in two forms: as an identifier and as an object, for example, creatorId and creator. Which form each method accepts and returns is shown in the table.
Which Fields the Methods Accept and Return
|
Method |
Accepts |
Returns |
|
Fields of the Task Object table with identifiers of related objects: |
The task object with the same structure as tasks.task.get without |
|
|
The same fields as |
Success flag |
|
|
Task |
Without |
|
|
|
Without |
In fields of the methods tasks.task.add and tasks.task.update, you cannot pass id, created, accomplices, auditors, tags, userFields, and object fields — creator, group, parent, and others. For such a field, the method returns a validation error stating that the field is read-only. Fields marked "changes automatically" do not need to be passed: their value is calculated by Bitrix24.
Instructions on how to work with the fields of related objects are described in the article Overview of REST API 3.0.
The rights to write and modify fields depend on the user's role in the task, group permission settings, employee hierarchy, task status, and task flags, such as allowsChangeDeadline. Before modifying a task, check the rights object: its fields show the actions available to the current user.
Boolean fields accept and return true or false. The string values Y and N from the classic task methods are not supported in REST 3.0: the method returns a validation error.
Task Object
|
Name |
Description |
|
id |
Task identifier |
|
title |
Task title, a required field for creating a task |
|
description |
Task description |
|
creatorId |
Creator identifier, a required field for creating a task. The field is returned by tasks.task.list; in the tasks.task.get response, request the |
|
creator |
Creator. An object of type user. Use for data requests in the |
|
created |
Creation date in ISO 8601 format. The field is returned by tasks.task.list; it is absent from the tasks.task.get response |
|
responsibleId |
Assignee identifier, a required field for creating a task. The field is returned by tasks.task.list; in the tasks.task.get response, request the |
|
responsible |
Assignee. An object of type user. Use for data requests in the |
|
deadline |
Deadline in ISO 8601 format, for example, |
|
needsControl |
Task control by the creator: |
|
startPlan |
Planned start date in ISO 8601 format, for example, |
|
endPlan |
Planned end date in ISO 8601 format, for example, |
|
checklist |
Identifiers of checklist items. To work with checklists, use the methods task.checklistitem.* |
|
fileIds |
Identifiers of Drive files to attach to the task. The field is accepted by tasks.task.add and tasks.task.update. In the tasks.task.get response, the field is not populated and is returned as |
|
groupId |
Group/project identifier. To work with groups, use the methods sonet_group.*. The field is returned by tasks.task.list; in the tasks.task.get response, request the |
|
group |
Group/project. An object of type group. Use for data requests in the |
|
stageId |
Stage identifier. Use if the task is in a group/project. The field is returned by tasks.task.list; in the tasks.task.get response, request the |
|
stage |
Stage. An object of type stage. Use for data requests in the |
|
epicId |
Epic identifier. To work with epics, use the methods tasks.api.scrum.epic.* |
|
storyPoints |
Story points. To update a Scrum task, use the method tasks.api.scrum.task.update |
|
flowId |
Flow identifier. To work with flows, use the methods tasks.flow.Flow.*. The field is returned by tasks.task.list; in the tasks.task.get response, request the |
|
flow |
Flow. An object of type flow. Use for data requests in the |
|
priority |
Task priority. Possible values:
|
|
status |
Task status. Possible values:
|
|
statusChanged |
Status change date in ISO 8601 format |
|
accomplices |
Participants. An array of objects of type user. Use for data requests in the The methods tasks.task.add and tasks.task.update do not accept the field. To assign participants, use the classic method tasks.task.update with the |
|
auditors |
Observers. An array of objects of type user. Use for data requests in the The methods tasks.task.add and tasks.task.update do not accept the field. To assign observers, use the classic method tasks.task.update with the |
|
parentId |
Parent task identifier. |
|
parent |
Parent task. An object of type task. Use for data requests in the |
|
containsChecklist |
Indicates the presence of a checklist. The field is automatically updated |
|
containsSubTasks |
Indicates the presence of subtasks. The field is automatically updated |
|
containsRelatedTasks |
Indicates the presence of related tasks. The field is automatically updated |
|
containsGanttLinks |
Indicates the presence of Gantt links. The field is automatically updated |
|
containsPlacements |
Indicates the presence of integrations. The field is automatically updated |
|
containsResults |
Indicates the presence of results. The field is automatically updated |
|
numberOfReminders |
Number of reminders for the task. The field is automatically updated |
|
chatId |
Task chat identifier. To work with the task chat, use the chat message methods. For more details, see New Task Card: Overview of Changes |
|
chat |
Task chat. An object of type task chat. Use for data requests in the |
|
plannedDuration |
Planned duration |
|
actualDuration |
Actual duration |
|
durationType |
Unit of planned duration. Possible values: |
|
started |
Start date of execution in ISO 8601 format |
|
estimatedTime |
Time estimate in seconds |
|
replicate |
Indicates a recurring task: |
|
changed |
Change date in ISO 8601 format |
|
changedById |
Identifier of the user who changed the task. The field is returned by tasks.task.list; in the tasks.task.get response, request the |
|
changedBy |
Who changed. An object of type user. Use for data requests in the |
|
statusChangedById |
Identifier of the user who changed the status. The field is returned by tasks.task.list; in the tasks.task.get response, request the |
|
statusChangedBy |
Who changed the status. An object of type user. Use for data requests in the |
|
closedById |
Identifier of the user who closed the task. The field is returned by tasks.task.list; in the tasks.task.get response, request the |
|
closedBy |
Who closed. An object of type user. Use for data requests in the |
|
closed |
Closing date in ISO 8601 format |
|
activity |
Date of last activity in ISO 8601 format |
|
guid |
Task |
|
xmlId |
External identifier |
|
exchangeId |
Exchange identifier |
|
exchangeModified |
Date of modification in Exchange |
|
outlookVersion |
Version of synchronization with Outlook |
|
mark |
Task rating. Possible values:
|
|
allowsChangeDeadline |
The assignee is allowed to change the deadline |
|
allowsTimeTracking |
Time tracking is enabled for the task |
|
matchesWorkTime |
Consider working hours: skip weekends when calculating planned dates |
|
addInReport |
Add the task to the report |
|
isMultitask |
Indicates "base task with subtasks" |
|
siteId |
Site identifier |
|
deadlineCount |
Service field of task counters. Do not use it in integrations |
|
declineReason |
Reason for declining the task. Populated when the assignee has declined the task |
|
forumTopicId |
Identifier of the forum topic with task comments. The value is |
|
forkedByTemplateId |
Identifier of the template if the task was created from a template. The field is returned by tasks.task.list; in the tasks.task.get response, request the |
|
forkedByTemplate |
Task template. An object of type template. Use for data requests in the |
|
maxDeadlineChangeDate |
Date after which the deadline cannot be changed, in ISO 8601 format |
|
maxDeadlineChanges |
Maximum number of deadline extensions |
|
requireDeadlineChangeReason |
Require a reason when the deadline is moved |
|
tags |
Task tags. An array of objects of type tag. Use for data requests in the |
|
link |
Relative link to the task in the Bitrix24 interface, for example, |
|
userFields |
Custom fields of the task. An array of objects of type custom field. Use for data requests in the |
|
rights |
Actions of the current user with the task. The key is the action code, and the value is |
|
archiveLink |
Link to the archive for downloading all task files |
|
crmItemIds |
Identifiers of related CRM objects in the format:
|
|
emailId |
Identifier of the email from which the task was created. The field is returned by tasks.task.list; in the tasks.task.get response, request the |
|
email |
Email from which the task was created. An object of type email. Use for data requests in the |
|
elapsedTime |
Time tracking. An object of type time tracking. Use for data requests in the |
|
requireResult |
Require a result: the task cannot be completed without a result record |
|
matchesSubTasksTime |
Consider subtask deadlines when calculating planned dates |
|
autocompleteSubTasks |
Complete subtasks automatically together with the base task |
|
allowsChangeDatePlan |
The assignee is allowed to change planned dates |
|
inFavorite |
Indicates "in favorites". The field returns an array containing the ID of the current user if their setting is active |
|
inPin |
Indicates "task pinned". The field returns an array containing the ID of the current user if their setting is active |
|
inGroupPin |
Indicates "task pinned in group". The field returns an array containing the ID of the current user if their setting is active |
|
inMute |
Indicates "mute". The field returns an array containing the ID of the current user if their setting is active |
|
source |
Source of the task. An object source. Use for data requests in the |
|
dependsOn |
Dependencies on tasks |
|
scenarios |
Task creation scenarios. Possible element values:
|
User Object
|
Name |
Description |
|
id |
User identifier |
|
name |
User name |
|
role |
User role |
|
image |
An object of type file. Use for data requests in the |
|
gender |
Gender. Possible values:
|
|
email |
|
|
externalAuthId |
External auth ID |
|
rights |
User rights |
Tag Object
|
Name |
Description |
|
id |
Tag identifier |
|
name |
Tag name |
Custom Field Object
Custom fields of a task are created by the methods task.item.userfield.*.
|
Name |
Description |
|
key |
Field code, for example, |
|
value |
Field value. The type depends on the field settings. If the field is empty — |
File Object
|
Name |
Description |
|
id |
File identifier |
|
src |
Link to the file |
|
name |
File name |
|
width |
Width |
|
height |
Height |
|
size |
Size |
|
subDir |
Subdirectory |
|
contentType |
MIME type |
|
file |
File data |
Group Object
|
Name |
Description |
|
id |
Group identifier |
|
name |
Group name |
|
image |
An object of type file. Use for data requests in the |
|
type |
Group type. Possible values:
|
|
isVisible |
Visibility indicator |
Stage Object
|
Name |
Description |
|
id |
Stage identifier |
|
title |
Stage title |
|
color |
Stage color |
Flow Object
|
Name |
Description |
|
id |
Flow identifier |
|
name |
Flow name |
Task Chat Object
|
Name |
Description |
|
id |
Chat element identifier |
|
entityId |
Chat object identifier |
|
entityType |
Chat object type. For a task chat — |
Task Template Object
|
Name |
Description |
|
id |
Template identifier |
|
task |
An object of type task. Use for data requests in the |
|
title |
Title |
|
description |
Description |
|
creator |
An object of type user. Use for data requests in the |
|
responsibleCollection |
Collection of responsible persons |
|
deadlineAfterTs |
Deadline shift |
|
startDatePlanTs |
Planned start date |
|
endDatePlanTs |
Planned end date |
|
replicate |
Task repetition from the template |
|
checklist |
Array of checklist item identifiers |
|
group |
An object of type group. Use for data requests in the |
|
priority |
Priority |
|
accomplices |
Participants |
|
auditors |
Auditors |
|
parent |
Parent template. An object of type task template |
|
replicateParams |
An object of replication parameters. Use for data requests in the |
Template Replication Parameters Object
|
Name |
Description |
|
period |
Frequency. Possible values:
|
|
everyDay |
Every day |
|
workdayOnly |
Only working days |
|
dailyMonthInterval |
Interval in days of the month |
|
everyWeek |
Every week |
|
monthlyType |
Type of monthly repetition |
|
monthlyDayNum |
Day of the month |
|
monthlyMonthNum1 |
First month of the period |
|
monthlyWeekDayNum |
Week number in the month |
|
monthlyWeekDay |
Day of the week |
|
monthlyMonthNum2 |
Second month of the period |
|
yearlyType |
Type of yearly repetition |
|
yearlyDayNum |
Day of the month for yearly repetition |
|
yearlyMonth1 |
First month of yearly repetition |
|
yearlyWeekDayNum |
Week number for yearly repetition |
|
yearlyWeekDay |
Day of the week for yearly repetition |
|
yearlyMonth2 |
Second month of yearly repetition |
|
time |
Time |
|
timezoneOffset |
Timezone offset |
|
startDate |
Start date of repetition |
|
repeatTill |
Until what date to repeat |
|
endDate |
End date of repetition |
|
times |
Number of repetitions |
Email Object
|
Name |
Description |
|
id |
Email ID |
|
taskId |
Task ID |
|
mailboxId |
Mailbox ID |
|
title |
Email title |
|
body |
Email body |
|
from |
Email sender |
|
dateTs |
Email sending timestamp |
|
link |
Link to the email |
Time Tracking Object
|
Name |
Description |
|
id |
Time tracking record identifier |
|
userId |
User |
|
taskId |
Task |
|
minutes |
Minutes |
|
seconds |
Seconds |
|
source |
Source of the time-tracking entry. Possible values:
|
|
text |
Comment |
|
createdAtTs |
Creation date |
|
startTs |
Start time |
|
stopTs |
End time |
Source Object
|
Name |
Description |
|
type |
Source type. Possible value — |
|
data |
Source data |