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
Show response

{
  "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
Show response

{
  "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"
    }
  ]
}
Show response

{
  "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
            }
          ]
        }
      ]
    }
  ]
}
Show response

{
  "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.
* required field

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

{
  "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
  • finished — close task
  • reopened — reopen task
approval_choice
  • approved
  • rejected
  • revoked
  • acknowledged
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.

Was this article helpful?

Yes, thanks! No, I have a question