Tasks
In this section we will describe how to work with tasks via API
Table of Contents
Common information
- Task is a separate entity that can be linked to a lead, contact, company, or customer entity
- It is required for a task to have a responsible user and deadline (date and time)
- Tasks have 2 standard types with predefined IDs: : 1 – Follow-up, 2 – Meeting
Tasks List
Method
GET /api/v4/tasks
Description
This method allows to get a list of tasks on the account.
Limitations
Method is available in correspondence to the user rights.
GET parameters
Parameter | Data type | Description |
---|---|---|
page | int | Sample page |
limit | int | The number of the entities returned in the response of one request (limit – 250) |
filter | object | Filter |
filter[responsible_user_id] | int|array | Filter by the task responsible user ID. Either a single ID or an array of IDs can be passed |
filter[is_completed] | bool | Filter by the task status. 1 – completed, 0 – open |
filter[task_type] | int|array | Filter by the task type ID. Either a single ID or an array of IDs can be passed |
filter[entity_type] | string | Filter by the entity type the task is linked to. Possible values: leads, contacts, companies, customers |
filter[entity_id] | int|array | Filter by the entity ID the task is linked to. To use the filter, the value should be passed into filter[entity_type]. Either a single ID or an array of IDs can be passed |
filter[id] | int|array | Filter by the task ID. Either a single ID or an array of IDs can be passed |
filter[updated_at] | int|object |
Filter by the last task edit. A timestamp can be passed, in that case, tasks edited after the timestamp value will be returned. Otherwise, the array of the following structure can be passed to filter between FROM and TO values: filter[updated_at][from]=… and filter[updated_at][to]=…. |
order | object |
Lists elements sorting. Fields available to sort by: created_at, complete_till, id. Values available to sort by: asc, desc. Example: /api/v4/tasks?order[complete_till]=asc |
An example of the request
In the following example we will get a list of all completed tasks with the type 2 (Meeting) limiting the sample to 2 rows.
https://example.kommo.com/api/v4/tasks?filter[task_type][]=2&filter[is_completed][]=1&limit=2
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Request successful |
401 | User is not authorized |
Response parameters
Method returns a collection of task models. The properties of the model are listed below.
Parameter | Data type | Description |
---|---|---|
id | int | Task ID |
created_by | int | ID of the user who created the task |
updated_by | int | ID of the user who edited the task last |
created_at | int | Task creation date in the format of Unix Timestamp |
updated_at | int | Task edit date in the format of Unix Timestamp |
responsible_user_id | int | Task responsible user ID |
group_id | int | Group ID of the task responsible user |
entity_id | int | ID of the entity the task is linked to |
entity_type | string | Type of the entity the task is linked to |
is_completed | bool | Defines whether the task is completed |
task_type_id | int | Task type |
text | string | Task description |
duration | int | Time to the task deadline (task duration) |
complete_till | int | Task deadline date in the format of Unix Timestamp |
result | object | Task result |
result[text] | string | Task result text |
account_id | int | Account ID where the task is located in |
Response example
{
"_page": 1,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/tasks?filter[task_type][]=2&filter[is_completed][]=1&limit=2&page=1"
},
"next": {
"href": "https://example.kommo.com/api/v4/tasks?filter[task_type][]=2&filter[is_completed][]=1&limit=2&page=2"
}
},
"_embedded": {
"tasks": [
{
"id": 7087,
"created_by": 3987910,
"updated_by": 3987910,
"created_at": 1575364000,
"updated_at": 1575364851,
"responsible_user_id": 123123,
"group_id": 0,
"entity_id": 167353,
"entity_type": "leads",
"duration": 0,
"is_completed": true,
"task_type_id": 2,
"text": "Send an invitation",
"result": [],
"complete_till": 1575665940,
"account_id": 321321,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/tasks/7087"
}
}
},
{
"id": 215089,
"created_by": 0,
"updated_by": 3987910,
"created_at": 1576767879,
"updated_at": 1576767914,
"responsible_user_id": 123123,
"group_id": 0,
"entity_id": 1035487,
"entity_type": "leads",
"duration": 0,
"is_completed": true,
"task_type_id": 2,
"text": "Schedule a meeting",
"result": [],
"complete_till": 1576768179,
"account_id": 321312,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/tasks/215089"
}
}
}
]
}
}
Getting a task by its ID
Method
GET /api/v4/tasks/{id}
Description
This method allows to get a particular task data by its ID.
Limitations
Method is available in correspondence to the user rights.
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Request successful |
401 | User is not authorized |
Response parameters
Method returns a task model. The properties of the model are listed below.
Parameter | Data type | Description |
---|---|---|
id | int | Task ID |
created_by | int | ID of the user who created the task |
updated_by | int | ID of the user who edited the task last |
created_at | int | Task creation date in the format of Unix Timestamp |
updated_at | int | Task edit date in the format of Unix Timestamp |
responsible_user_id | int | Task responsible user ID |
group_id | int | Group ID of the task responsible user |
entity_id | int | ID of the entity the task is linked to |
entity_type | string | Type of the entity the task is linked to |
is_completed | bool | Defines whether the task is completed |
task_type_id | int | Task type |
text | string | Task description |
duration | int | Time to the task deadline (task duration) |
complete_till | int | Task deadline date in the format of Unix Timestamp |
result | object | Task result |
result[text] | string | Task result text |
account_id | int | Account ID where the task is located in |
Response example
{
"id": 56981,
"created_by": 54224,
"updated_by": 3987910,
"created_at": 1575910123,
"updated_at": 1576767989,
"responsible_user_id": 123123,
"group_id": 0,
"entity_id": 180765,
"entity_type": "leads",
"duration": 0,
"is_completed": true,
"task_type_id": 2,
"text": "Schedule a meeting",
"result": {
"text": "Scheduled"
},
"complete_till": 1575910423,
"account_id": 321312,
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/tasks/56981"
}
}
}
Adding tasks
Method
POST /api/v4/tasks
Description
This method allows to add multiple tasks into the account.
Limitations
Method is available in correspondence to the user rights.
Request header
Content-Type: application/json
Request parameters
To add a task, 2 mandatory parameters should be passed: text and complete_till. All available parameters are listed below.
Parameter | Data type | Description |
---|---|---|
responsible_user_id | int | Task responsible user ID. Is not a mandatory parameter, current user ID by default |
entity_id | int | ID of the entity the task is linked to. Is not a mandatory parameter |
entity_type | string | Type of the entity the task is linked to. Is not a mandatory parameter |
is_completed | bool | Defines whether the task is completed. Is not a mandatory parameter |
task_type_id | int | Task type. Is not a mandatory parameter |
text | string | Task description. Is a mandatory parameter |
duration | int | Time to the task deadline (task duration). Is not a mandatory parameter |
complete_till | int | Task deadline date in the format of Unix Timestamp. Is a mandatory parameter. |
result | object | Task result |
result[text] | string | Task result text |
created_by | int | ID of the user who created the task. Is not a mandatory parameter |
updated_by | int | ID of the user who edited the task last. Is not a mandatory parameter |
created_at | int | Task creation date in the format of Unix Timestamp. Is not a mandatory parameter |
updated_at | int | Task edit date in the format of Unix Timestamp. Is not a mandatory parameter |
request_id | string | Field that will be returned unchanged in the response and will not be saved. Is not a mandatory parameter |
An example of the request
[
{
"task_type_id": 1,
"text": "Meeting with the client",
"complete_till": 1588885140,
"entity_id": 9785993,
"entity_type": "leads",
"request_id": "example"
}
]
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Tasks added successfully |
401 | User is not authorized |
400 | Invalid data given. Details are available in the request response |
Response parameters
Method returns a collection of added tasks.
Response example
{
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/tasks"
}
},
"_embedded": {
"tasks": [
{
"id": 4745251,
"request_id": "example",
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/tasks/4745251"
}
}
}
]
}
}
Editing tasks
Method
PATCH /api/v4/tasks
Description
This method allows to edit multiple tasks.
To edit a singular task, you can add the task ID into the method URL (/api/v4/tasks/{id}).
When updating multiple tasks, an array of task objects is passed. In case with a singular task, the task model is passed.
Limitations
Method is available in correspondence to the user rights.
Request header
Content-Type: application/json
Request parameters
Parameter | Data type | Description |
---|---|---|
responsible_user_id | int | Task responsible user ID. Is not a mandatory parameter, current user ID by default |
entity_id | int | ID of the entity the task is linked to. Is not a mandatory parameter |
entity_type | string | Type of the entity the task is linked to. Is not a mandatory parameter |
is_completed | bool | Defines whether the task is completed. Is not a mandatory parameter |
task_type_id | int | Task type. Is not a mandatory parameter |
text | string | Task description. Is a mandatory parameter |
duration | int | Time to the task deadline (task duration). Is not a mandatory parameter |
complete_till | int | Task deadline date in the format of Unix Timestamp. Is a mandatory parameter. |
result | object | Task result |
result[text] | string | Tast result text |
created_by | int | ID of the user who created the task. Is not a mandatory parameter |
updated_by | int | ID of the user who edited the task last. Is not a mandatory parameter |
created_at | int | Task creation date in the format of Unix Timestamp. Is not a mandatory parameter |
updated_at | int | Task edit date in the format of Unix Timestamp. Is not a mandatory parameter |
request_id | string | Field that will be returned unchanged in the response and will not be saved. Is not a mandatory parameter |
An example of the request
[
{
"id": 4745251,
"task_type_id": 2,
"text": "New task description",
"complete_till": 1588885140
},
{
"id": 4747929,
"task_type_id": 1,
"text": "New task description 2",
"complete_till": 1588885140
}
]
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Tasks edited successfully |
401 | User is not authorized |
400 | Invalid data given. Details are available in the request response |
Response parameters
Method returns a collection of edited tasks or a completed task model. Only properties “id” and “updated_at” are returned.
Response example
{
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/tasks"
}
},
"_embedded": {
"tasks": [
{
"id": 4745251,
"updated_at": 1588760725,
"request_id": "0",
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/tasks/4745251"
}
}
},
{
"id": 4747929,
"updated_at": 1588760725,
"request_id": "1",
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/tasks/4747929"
}
}
}
]
}
}
Completing a task
Method
PATCH /api/v4/tasks
Description
We’ll review task completion separately as a special case of task editing.
This method allows to edit multiple tasks.
To edit a singular task, you can add the task ID into the method URL (/api/v4/tasks/{id}).
When updating multiple tasks, an array of task objects is passed. In case with a singular task, the task model is passed.
Limitations
Method is available in correspondence to the user rights.
Request header
Content-Type: application/json
Request parameters
To complete a task, properties “result” and “is_completed” should be passed
Parameter | Data type | Description |
---|---|---|
is_completed | bool | Defines whether the task is completed |
result | object | Task result |
result[text] | string | Task result text |
An example of the request
In the following example we will complete a task using the /api/v4/tasks/4747929 method.
{
"is_completed": true,
"result": {
"text": "Reached the client"
}
}
Data type header when the request is successful
Content-Type: application/hal+json
Data type header in case of an error
Content-Type: application/problem+json
HTTP response codes.
Response code | Case |
---|---|
200 | Tasks edited successfully |
401 | User is not authorized |
400 | Invalid data given. Details are available in the request response |
Response parameters
Method returns a collection of edited tasks or a completed task model. Only properties “id” and “updated_at” are returned.
Response example
{
"id": 4747929,
"updated_at": 1588770600,
"request_id": "0",
"_links": {
"self": {
"href": "https://example.kommo.com/api/v4/tasks/4747929"
}
}
}