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.
Methods
GET /tasks/{task-id}
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"
},
"responsible": {
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com"
},
"participants": [
{
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com"
},
{
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com"
}
],
"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"
},
"reassigned_to": {
"id": 1730,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com"
},
"participants_added": [
{
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com"
},
{
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com"
}
]
}
]
}
}
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"
},
"form_id": 1345,
"approvals": [
[
{
"person": {
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com"
},
"approval_choice": "waiting"
}
],
[
{
"person": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com"
},
"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"
},
{
"id": 6,
"type": "money",
"name": "Amount",
"value": 10000
}
]
},
{
"row_id": 1,
"cells": [
{
"id": 9,
"type": "date",
"name": "Date",
"value": "2017-08-27"
},
{
"id": 6,
"type": "money",
"name": "Amount",
"value": 306.25
}
]
}
]
}
],
"comments": [
{
"id": 13767,
"create_date": "2017-08-17T14:31:18Z",
"author": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com"
},
"reassigned_to": {
"id": 1730,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com"
},
"approvals_added": [
[
{
"person": {
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com"
},
"step": 1
},
{
"person": {
"id": 1725,
"first_name": "Jane",
"last_name": "Doe",
"email": "Jane.Doe@gmail.com"
},
"step": 1
}
],
[
{
"person": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com"
},
"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"
},
{
"id": 6,
"type": "money",
"name": "Amount",
"value": 10000
}
]
},
{
"row_id": 1,
"cells": [
{
"id": 9,
"type": "date",
"name": "Date",
"value": "2017-08-27"
},
{
"id": 6,
"type": "money",
"name": "Amount",
"value": 306.25
}
]
}
]
},
{
"id": 13768,
"create_date": "2017-08-18T10:00:11Z",
"author": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com"
},
"text": ""
"approvals_removed": [
[{
"person": {
"id": 1725,
"first_name": "Jane",
"last_name": "Doe",
"email": "Jane.Doe@gmail.com"
},
"step": 1
}]
]
}
]
}
]
}
}
POST /tasks
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"
},
"responsible": {
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com"
},
"participants": [
{
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com"
},
{
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com"
}
],
"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"
},
"reassigned_to": {
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com"
},
"participants_added": [
{
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com"
},
{
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"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"
},
"form_id": 1345,
"approvals": [
[
{
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com"
},
{
"id": 1725,
"first_name": "Jane",
"last_name": "Doe",
"email": "Jane.Doe@gmail.com"
}
],
[
{
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com"
}
]
],
"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"
},
{
"id": 6,
"type": "money",
"name": "Amount",
"value": 10000
}
]
}
]
}
],
"comments": [
{
"id": 13767,
"create_date": "2017-08-17T14:31:18Z",
"author": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com"
},
"reassigned_to": {
"id": 1730,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com"
},
"approvals_added": [
[
{
"person": {
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com"
},
"step": 1
},
{
"person": {
"id": 1725,
"first_name": "Jane",
"last_name": "Doe",
"email": "Jane.Doe@gmail.com"
},
"step": 1
}
],
[
{
"person": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com"
},
"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"
},
{
"id": 6,
"type": "money",
"name": "Amount",
"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. | |
|
| list_ids | An array of list identifiers. | |
|
| 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. | |
|
| 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. | |
POST /tasks/{task-id}/comments
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"
},
"form_id": 1345,
"approvals": [
[
{
"person": {
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com"
},
"approval_choice": "waiting"
}
],
[
{
"person": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com"
},
"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"
},
{
"id": 6,
"type": "money",
"name": "Amount",
"value": 10000
}
]
},
{
"row_id": 1,
"cells": [
{
"id": 9,
"type": "date",
"name": "Date",
"value": "2017-08-27"
},
{
"id": 6,
"type": "money",
"name": "Amount",
"value": 306.25
}
]
}
]
}
],
"comments": [
{
"id": 13767,
"create_date": "2017-08-17T14:31:18Z",
"author": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com"
},
"reassigned_to": {
"id": 1730,
"first_name": "John"
"last_name": "Snow",
"email": "John.Snow@gmail.com"
},
"approvals_added": [
[
{
"person": {
"id": 1733,
"first_name": "John",
"last_name": "Snow",
"email": "John.Snow@gmail.com"
},
"step": 1
},
{
"person": {
"id": 1725,
"first_name": "Jane",
"last_name": "Doe",
"email": "Jane.Doe@gmail.com"
},
"step": 1
}
],
[
{
"person": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com"
},
"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"
},
{
"id": 6,
"type": "money",
"name": "Amount",
"value": 10000
}
]
},
{
"row_id": 1,
"cells": [
{
"id": 9,
"type": "date",
"name": "Date",
"value": "2017-08-27"
},
{
"id": 6,
"type": "money",
"name": "Amount",
"value": 306.25
}
]
}
]
}
]
},
{
"id": 13768,
"create_date": "2017-08-18T10:00:11Z",
"author": {
"id": 1731,
"first_name": "Bob",
"last_name": "Smith",
"email": "Bob.Smith@gmail.com"
},
"text": ""
"approvals_removed": [
[{
"id": 1725,
"first_name": "Jane",
"last_name": "Doe",
"email": "Jane.Doe@gmail.com"
},
"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"
},
"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. |
| 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. |