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 -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 -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 -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 -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 } ] } ] } ] }'
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. | ||
subscribers | An array of subscriber's and their decisions. Subscriber is a person receiving notification on task changes in their Inbox. | ||
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 -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" }'
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. For example: "approvals_added": [ [ { "id": 1234 } ], [], [ { "id": 4321 } ] ] |
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. |
subscribers_added | An array of people's id or email. |
subscribers_removed | An array of people's id or email. |
subscribers_rerequested | An array of people's id or email. |
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, Telegram, VK, Facebook, Web Widget, Mobile App). Applicable only for a form task. Format: "channel": { "type": "email" } "channel": { "type": "telegram" } "channel": { "type": "vk" } "channel": { "type": "facebook" } "channel": { "type": "web_widget" } "channel": { "type": "mobile_app" } |