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"
        }
    }
}