Help CenterSidebar
api:tasks
Tasks
There are two types of tasks in Pyrus: simple tasks and form tasks.
A Simple task contains a fixed set of fields: Subject and Text, as well as an array of participants.
A Form task differs from the simple task in that it can have a pre-configured workflow and a custom set of fields.
Any change to the task, like altering the field values or downloading attachments, is done by adding a comment.
You can find more information on tasks and forms in Help.
Getting a simple task with all comments
A simple task has three fields that a form task doesn't have. These are text, responsible, and participants — an array of task participants from which you can assign a responsible person.
GET https://api.pyrus.com/v4/tasks/11611
{
"task": {
"id": 11611,
"text": "Help with printer",
"create_date": "2017-08-17T15:32:11Z",
"last_modified_date": "2017-08-17T15:32:11Z",
"author": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
},
"responsible": {
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com",
"type": "user"
},
"participants": [
{
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com",
"type": "user"
},
{
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
}
],
"comments": [
{
"id": 13767,
"create_date": "2017-08-17T15:32:11Z",
"text": "Help with printer",
"author": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
},
"reassigned_to": {
"id": 1730,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com",
"type": "user"
},
"participants_added": [
{
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com",
"type": "user"
},
{
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
}
]
}
]
}
}
curl
curl -X GET \
'https://api.pyrus.com/v4/tasks/11611' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
-H 'Content-Type: application/json'
Getting a form task with all comments
A form task has three fields that a simple task doesn't have: form_id, a form template identifier; fields, an array of form fields; and approvals, an array of approval steps.
GET https://api.pyrus.com/v4/tasks/11613
{
"task": {
"id": 11613,
"text": "Payments",
"create_date": "2017-08-17T14:31:18Z",
"last_modified_date": "2017-08-18T10:00:11Z",
"author": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
},
"form_id": 1345,
"approvals": [
[
{
"person": {
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com",
"type": "user"
},
"approval_choice": "waiting"
}
],
[
{
"person": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
},
"approval_choice": "waiting"
}
]
],
"fields": [
{
"id": 1,
"type": "text",
"name": "Purpose",
"value": "IT conference in Amsterdam"
},
{
"id": 2,
"type": "money",
"name": "Amount",
"value": 10306.25
},
{
"id": 3,
"type": "catalog",
"name": "Payment type",
"value": {
"item_id": 845,
"headers": [
"Payment types"
],
"values": [
"IT Conference"
]
}
},
{
"id": 4,
"type": "table",
"name": "Payment Schedule",
"value" : [
{
"row_id": 0,
"cells": [
{
"id": 9,
"type": "date",
"name": "Date",
"value": "2017-08-26",
"parent_id": 4,
"row_id": 0
},
{
"id": 6,
"type": "money",
"name": "Amount",
"value": 10000,
"parent_id": 4,
"row_id": 0
}
]
},
{
"row_id": 1,
"cells": [
{
"id": 9,
"type": "date",
"name": "Date",
"value": "2017-08-27",
"parent_id": 4,
"row_id": 1
},
{
"id": 6,
"type": "money",
"name": "Amount",
"value": 306.25,
"parent_id": 4,
"row_id": 1
}
]
}
]
}
],
"comments": [
{
"id": 13767,
"create_date": "2017-08-17T14:31:18Z",
"author": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
},
"reassigned_to": {
"id": 1730,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com",
"type": "user"
},
"approvals_added": [
[
{
"person": {
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com",
"type": "user"
},
"step": 1
},
{
"person": {
"id": 1725,
"first_name": "Jane",
"last_name": "Doe",
"email": "Jane.Doe@gmail.com",
"type": "user"
},
"step": 1
}
],
[
{
"person": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
},
"step": 2
}
]
],
"field_updates": [
{
"id": 1,
"type": "text",
"name": "Purpose",
"value": "IT conference in Amsterdam"
},
{
"id": 2,
"type": "money",
"name": "Amount",
"value": 10306.25
},
{
"id": 3,
"type": "catalog",
"name": "Payment type",
"value": {
"item_id": 845,
"headers": [
"Payment types"
],
"values": [
"IT Conference"
]
}
},
{
"id": 4,
"type": "table",
"name": "Payment Schedule",
"value" : [
{
"row_id": 0,
"cells": [
{
"id": 9,
"type": "date",
"name": "Date",
"value": "2017-08-26",
"parent_id": 4,
"row_id": 0
},
{
"id": 6,
"type": "money",
"name": "Amount",
"value": 10000,
"parent_id": 4,
"row_id": 0
}
]
},
{
"row_id": 1,
"cells": [
{
"id": 9,
"type": "date",
"name": "Date",
"value": "2017-08-27",
"parent_id": 4,
"row_id": 1
},
{
"id": 6,
"type": "money",
"name": "Amount",
"value": 306.25,
"parent_id": 4,
"row_id": 1
}
]
}
]
},
{
"id": 13768,
"create_date": "2017-08-18T10:00:11Z",
"author": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
},
"text": ""
"approvals_removed": [
[{
"person": {
"id": 1725,
"first_name": "Jane",
"last_name": "Doe",
"email": "Jane.Doe@gmail.com",
"type": "user"
},
"step": 1
}]
]
}
]
}
]
}
}
curl
curl -X GET \
'https://api.pyrus.com/v4/tasks/11613' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
-H 'Content-Type: application/json'
Creating a simple task
This Method returns a created task with a comment.
POST https://api.pyrus.com/v4/tasks
{
"text": "Help with printer",
"responsible": {
"id": 1733
},
"participants": [
{
"id": 1733
},
{
"email": "Bob.Smith@gmail.com"
}
]
}
{
"task": {
"id": 11611,
"text": "Help with printer",
"create_date": "2017-08-17T15:32:11Z",
"last_modified_date": "2017-08-17T15:32:11Z",
"author": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
},
"responsible": {
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com",
"type": "user"
},
"participants": [
{
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com",
"type": "user"
},
{
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
}
],
"comments": [
{
"id": 13767,
"text": "Help with printer",
"create_date": "2017-08-17T15:32:11Z",
"author": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
},
"reassigned_to": {
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com",
"type": "user"
},
"participants_added": [
{
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com",
"type": "user"
},
{
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
}
]
}
]
}
}
curl
curl -X POST \
https://api.pyrus.com/v4/tasks/ \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"text": "Help with printer",
"responsible": {
"id": 1733
},
"participants": [
{
"id": 1733
},
{
"email": "Bob.Smith@gmail.com"
}
]
}'
Creating a form task
This Method returns a created task with a comment.
POST https://api.pyrus.com/v4/tasks
{
"form_id": 1345,
"fields": [
{
"id": 1,
"value": "IT conference in Amsterdam"
},
{
"id": 2,
"value": 10306.25
},
{
"id": 3,
"value": {
"item_id": 845
}
},
{
"id": 4,
"value": [
{
"row_id": 0,
"cells": [
{
"id": 6,
"value": "2017-08-26"
},
{
"id": 9,
"value": 10000
}
]
}
]
}
]
}
{
"task": {
"id": 11615,
"text": "Payments",
"create_date": "2017-08-17T14:31:18Z",
"last_modified_date": "2017-08-17T14:31:18Z",
"author": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
},
"form_id": 1345,
"approvals": [
[
{
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com",
"type": "user"
},
{
"id": 1725,
"first_name": "Jane",
"last_name": "Doe",
"email": "Jane.Doe@gmail.com",
"type": "user"
}
],
[
{
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
}
]
],
"fields": [
{
"id": 1,
"type": "text",
"name": "Purpose",
"value": "IT conference in Amsterdam"
},
{
"id": 2,
"type": "money",
"name": "Amount",
"value": 10306.25
},
{
"id": 3,
"type": "catalog",
"name": "Payment type",
"value": {
"item_id": 845,
"headers": [
"Payment types"
],
"values": [
"IT Conference"
]
}
},
{
"id": 4,
"type": "table",
"name": "Payment Schedule",
"value" : [
{
"row_id": 0,
"cells": [
{
"id": 9,
"type": "date",
"name": "Date",
"value": "2017-08-26",
"parent_id": 4,
"row_id": 0
},
{
"id": 6,
"type": "money",
"name": "Amount",
"value": 10000,
"parent_id": 4,
"row_id": 0
}
]
}
]
}
],
"comments": [
{
"id": 13767,
"create_date": "2017-08-17T14:31:18Z",
"author": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
},
"reassigned_to": {
"id": 1730,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com",
"type": "user"
},
"approvals_added": [
[
{
"person": {
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com",
"type": "user"
},
"step": 1
},
{
"person": {
"id": 1725,
"first_name": "Jane",
"last_name": "Doe",
"email": "Jane.Doe@gmail.com",
"type": "user"
},
"step": 1
}
],
[
{
"person": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
},
"step": 2
}
]
],
"field_updates": [
{
"id": 1,
"type": "text",
"name": "Purpose",
"value": "IT conference in Amsterdam"
},
{
"id": 2,
"type": "money",
"name": "Amount",
"value": 10306.25
},
{
"id": 3,
"type": "catalog",
"name": "Payment type",
"value": {
"item_id": 845,
"headers": [
"Payment types"
],
"values": [
"IT Conference"
]
}
},
{
"id": 4,
"type": "table",
"name": "Payment Schedule",
"value" : [
{
"row_id": 0,
"cells": [
{
"id": 9,
"type": "date",
"name": "Date",
"value": "2017-08-26",
"parent_id": 4,
"row_id": 0
},
{
"id": 6,
"type": "money",
"name": "Amount",
"value": 10000,
"parent_id": 4,
"row_id": 0
}
]
}
]
}
]
}
]
}
}
curl
curl -X POST \
https://api.pyrus.com/v4/tasks/ \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"form_id": 1345,
"fields": [
{
"id": 1,
"value": "IT conference in Amsterdam"
},
{
"id": 2,
"value": 10306.25
},
{
"id": 3,
"value": {
"item_id": 845
}
},
{
"id": 4,
"value": [
{
"row_id": 0,
"cells": [
{
"id": 6,
"value": "2017-08-26"
},
{
"id": 9,
"value": 10000
}
]
}
]
}
]
}'
Parameters
| Name | Description | Simple task | Form task |
| text * | Text of the task. |  |
|
| responsible | id or email of the person responsible for the task. | |
|
| due_date | The task due date (either due_date or due can be used). | |
|
| due | Task due date with time (either due_date or due can be used). | |
|
| duration | The duration of the event in minutes (it can only be used with due). | |
|
| subject | Task subject. If not filled out, the first line of the task text will be used as the subject. | |
|
| participants | An array of people's id or email. | |
|
| parent_task_id | |
|
|
| attachments | An array of unique identifiers of uploaded files. You can upload the file and get its identifier using the files/upload method. | |
|
| scheduled_date | Schedule a task on a specified date. Task will be returned to the inbox at 7 am in the client's timezone. Date format: YYYY-MM-DD. |
|
|
| scheduled_datetime_utc | Schedule a task for a specified time in the utc time zone. Date format: YYYY-MM-DDThh:mm:ssZ |
|
|
| list_ids | An array of list identifiers. | |
|
| approvals | An array of approval steps that contains an array of people's id or email. | |
|
| form_id * | form template identifier. | |
|
| fields | An array of field values. Every field contains an id and value. You can find additional information about field types in the Form fields format section. | |
|
| fill_defaults | The flag indicating whether the form fields should be filled with default values from the form template. Be default: false |
|
Adding a task comment.
This method returns a task with all comments, including the added one.
POST https://api.pyrus.com/v4/tasks/11613/comments
{
"text": "It's done.",
"action": "finished"
}
{
"task": {
"id": 11613,
"text": "Payments",
"create_date": "2017-08-17T14:31:18Z",
"last_modified_date": "2017-08-18T10:02:23Z",
"author": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
},
"form_id": 1345,
"approvals": [
[
{
"person": {
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com",
"type": "user"
},
"approval_choice": "waiting"
}
],
[
{
"person": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
},
"approval_choice": "waiting"
}
]
],
"fields": [
{
"id": 1,
"type": "text",
"name": "Purpose",
"value": "IT conference in Amsterdam"
},
{
"id": 2,
"type": "money",
"name": "Amount",
"value": 10306.25
},
{
"id": 3,
"type": "catalog",
"name": "Payment type",
"value": {
"item_id": 845,
"headers": [
"Payment types"
],
"values": [
"IT Conference"
]
}
},
{
"id": 4,
"type": "table",
"name": "Payment Schedule",
"value": [
{
"row_id": 0,
"cells": [
{
"id": 9,
"type": "date",
"name": "Date",
"value": "2017-08-26",
"parent_id": 4,
"row_id": 0
},
{
"id": 6,
"type": "money",
"name": "Amount",
"value": 10000,
"parent_id": 4,
"row_id": 0
}
]
},
{
"row_id": 1,
"cells": [
{
"id": 9,
"type": "date",
"name": "Date",
"value": "2017-08-27",
"parent_id": 4,
"row_id": 1
},
{
"id": 6,
"type": "money",
"name": "Amount",
"value": 306.25,
"parent_id": 4,
"row_id": 1
}
]
}
]
}
],
"comments": [
{
"id": 13767,
"create_date": "2017-08-17T14:31:18Z",
"author": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
},
"reassigned_to": {
"id": 1730,
"first_name": "John"
"last_name": "Snow",
"email": "John.Snow@gmail.com",
"type": "user"
},
"approvals_added": [
[
{
"person": {
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com",
"type": "user"
},
"step": 1
},
{
"person": {
"id": 1725,
"first_name": "Jane",
"last_name": "Doe",
"email": "Jane.Doe@gmail.com",
"type": "user"
},
"step": 1
}
],
[
{
"person": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
},
"step": 2
}
]
],
"field_updates": [
{
"id": 1,
"type": "text",
"name": "Purpose",
"text": "IT conference in Amsterdam"
},
{
"id": 2,
"type": "money",
"name": "Amount",
"number": 10306.25
},
{
"id": 3,
"type": "catalog",
"name": "Payment type",
"value": {
"item_id": 845,
"headers": [
"Payment types"
],
"values": [
"IT Conference"
]
}
},
{
"id": 4,
"type": "table",
"name": "Payment Schedule",
"value": [
{
"row_id": 0,
"cells": [
{
"id": 9,
"type": "date",
"name": "Date",
"value": "2017-08-26",
"parent_id": 4,
"row_id": 0
},
{
"id": 6,
"type": "money",
"name": "Amount",
"value": 10000,
"parent_id": 4,
"row_id": 0
}
]
},
{
"row_id": 1,
"cells": [
{
"id": 9,
"type": "date",
"name": "Date",
"value": "2017-08-27",
"parent_id": 4,
"row_id": 1
},
{
"id": 6,
"type": "money",
"name": "Amount",
"value": 306.25,
"parent_id": 4,
"row_id": 1
}
]
}
]
}
]
},
{
"id": 13768,
"create_date": "2017-08-18T10:00:11Z",
"author": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
},
"text": ""
"approvals_removed": [
[{
"id": 1725,
"first_name": "Jane",
"last_name": "Doe",
"email": "Jane.Doe@gmail.com",
"type": "user"
},
"step": 1
]
]
},
{
"id": 13768,
"create_date": "2017-08-18T10:02:23Z",
"author": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com",
"type": "user"
},
"text": "It's done.",
"action": "finished"
}
]
}
}
curl
curl -X POST \
https://api.pyrus.com/v4/tasks/11613/comments \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"text": "It's done.",
"action": "finished"
}'
Parameters
At least one of the fields below must be filled in the task comment. Only the values of the fields that you have passed in the request will be updated.
| text | Comment text. |
| subject | Task subject. Applicable only for a simple task. |
| due_date | The task due date (either due_date or due can be used). |
| due | The task due date with time (either due_date or due can be used). |
| duration | The duration of the event in minutes (it can only be used with due). |
| action |
|
| approval_choice |
|
| reassign_to | id or email of a new responsible person. |
| approvals_added | An array of approval steps that contains an array of people's id or email. Applicable only for a form task. |
| approvals_removed | An array of approval steps that contains an array of people's id or email. Applicable only for a form task. |
| approvals_rerequested | An array of approval steps that contains an array of people's id or email. Applicable only for a form task. |
| participants_added | An array of people's id or email. Applicable only for a simple task. |
| participants_removed | An array of people's id or email. Applicable only for a simple task. |
| field_updates | An array of new form values. Every value includes a field's id and value. You can find additional information about the field types in the Form fields format section. |
| attachments | An array of unique identifiers of uploaded files. You can upload the file and get its identifier using the files/upload method. |
| added_list_ids | An array of identifiers of lists to which you want to add the task. |
| removed_list_ids | An array of identifiers of lists from which you want to remove the task. |
| scheduled_date | Schedule a task on a specified date. Task will be returned to the inbox at 7 am in the client's timezone. Date Format: YYYY-MM-DD. |
| scheduled_datetime_utc | Schedule a task for a specified time in the utc time zone. Date Format: YYYY-MM-DDThh:mm:ssZ |
| cancel_schedule | Cancel schedule. Task will be returned to the inbox. |
| channel | The comment will be sent via the external channel. (email). Applicable only for a form task. Format:
"channel": {
"type": "email"
}
|