Tasks API Calls

Retrieve all tasks on a task list, project or at top level

Requests

  • GET /tasks.json
    • Get all tasks across all projects
  • GET /projects/{id}/tasks.json
    • Get all tasks on a given project
  • GET /tasklists/{id}/tasks.json
    • Get all tasks on a given task list

Options

Attribute

Req/Opt

Default

Description

filter

Optional

 anytime

Tasks can be filtered by due dates using the following options:

  • all

  • anytime

  • overdue

  • today

  • tomorrow

  • thisweek

  • within7

  • within14

  • within30

  • within365

  • nodate

  • nostartdate

  • completed

Additionally, you can choose to include the start dates in this critera by setting ignore-start-dates to false.

page

Optional

1

Optionally, you can set the page from which to start retrieving results. This is usually used in conjunction with the parameter pageSize.

For example:

  • ?page=2&pageSize=10 will retrieve results 10-20.

pageSize

Optional

250

The amount of tasks returned can be limited using this parameter. Normally used in conjunction with the page parameter.

startdate

Optional

 

Tasks within a range of dates can be returned by setting a startdate and enddate. The format should be YYYYMMDD.

For example:

  • ?startdate=20140512&enddate=20140513 will get all of the tasks from the 12th of May 2014 till the 13th of May 2014.

enddate

Optional

 

Must be used in conjunction with startdate, see above.

updatedAfterDate

Optional

 

Will only return tasks that have been updated after a specified date. Timestamp must be in the following format: YYYYMMDDHHMMSS.

For example:

  • ?updatedAfterDate=20131123201022 will only return tasks updated after 23rd of November 2013 at 20:10:22. (UTC)

completedAfterDate Optional  

Will only return tasks that have been completed after a specified date. Timestamp must be in the following format: YYYYMMDDHHMMSS

For example:

  • ?completedAfterDate=20141123201022 will only return tasks completed after 23rd of November 2014 at 20:10:22. (UTC)
completedBeforeDate Optional   Will only return tasks that have been completed before a specified date. Timestamp must be in the following format: YYYYMMDDHHMMSS

For example:

  • ?completedBeforeDate=20150101235959 will only return tasks completed before 1st January 2015 at 23:59:59. (UTC)

showDeleted

Optional

no

Tasks that have been deleted can be shown by setting this parameter to yes.

includeCompletedTasks

Optional

false

Tasks that have been marked as completed can be shown by setting this parameter to true.

includeCompletedSubtasks

Optional

false

Sub-tasks that have been marked as completed can be shown by setting this parameter to true if you have requested to include sub-tasks

creator-ids

Optional

 0

For requesting tasks made by a specific person or people.

For example:

  • 44 would return tasks made by user 44.

  • 44,45 would return tasks made by users 44 and/or 45 etc.

include

Optional

 

Extra tasks that can be included with the filter option.

  • nodate

  • nostartdate

  • noduedate

  • overdue

responsible-party-ids

Optional

 

Tasks can be filtered by the person/people a task is assigned to.

For example:

  • -1 would return all tasks with an assigned person.

  • 0 would return all tasks with no assignment.

  • 32 would return tasks assigned to user 32.

  • 32,55 would return tasks assigned to users 32 and/or 55 etc.

sort

Optional

duedate

Tasks can be sorted by the following options

  • duedate

  • startdate

  • dateadded

  • priority

  • project

  • company

getSubTasks

Optional

yes

Subtasks can be excluded from the results by adding this parameter with no as the value.

nestSubTasks

Optional

no

Subtasks can be nested within the parent task object by adding this paramter with yes as the value.

getFiles

Optional

false

Files attached to tasks can be returned within the task object by setting this parameter to true.

includeToday

Optional

true

When using the filter option with any of the following options; within7,within14,within30,within365. You can choose to exclude deadlines for today by passing this parameter as false.

ignore-start-dates

Optional

false

When using the filter option, you can choose to include start dates matching the filtering critera by passing this parameter as true. By default, only due dates are checked against the filter.

tag-ids Optional  

A comma separated list of tag ids to filter tasks on

       

Response

{
    "todo-items": [
        {
            "project-id": "23101",
            "order": "2000",
            "comments-count": "0",
            "created-on": "2014-05-08T15:07:23Z",
            "canEdit": true,
            "has-predecessors": "2",
            "id": "439458",
            "completed": false,
            "position": "2000",
            "estimated-minutes": "0",
            "description": "",
            "progress": "0",
            "harvest-enabled": false,
            "responsible-party-lastname": "User",
            "parentTaskId": "12345",
            "company-id": "2",
            "creator-avatar-url": "http://demo1company.teamwork.com/images/avatar.jpg",
            "creator-id": "28726",
            "project-name": "demo",
            "start-date": "20140508",
            "tasklist-private": "0",
            "lockdownId": "",
            "canComplete": true,
            "responsible-party-id": "28726",
            "creator-lastname": "User",
            "has-reminders": true,
            "todo-list-name": "test",
            "has-unread-comments": false,
            "due-date-base": "20140524",
            "private": "0",
            "responsible-party-summary": "Demo U.",
            "status": "new",
            "todo-list-id": "59415",
            "predecessors": [
                {
                    "id": "439459",
                    "type": "complete"
                }
            ],
            "parent-task": {
                "content": "sample parent task",
                "id": "12345"
            },
            "content": "a task",
            "boardColumn": [
                {
                    id: 32,
                    name: "My Inbox Board",
                    color: "#99DF72"
                }
            ],
            "responsible-party-type": "Person",
            "company-name": "Demo 1 Company",
            "creator-firstname": "Demo",
            "last-changed-on": "2014-05-13T08:12:49Z",
            "due-date": "20140524",
            "has-dependencies": "0",
            "attachments-count": "0",
            "priority": "",
            "responsible-party-firstname": "Demo",
            "viewEstimatedTime": true,
            "responsible-party-ids": "28726",
            "responsible-party-names": "Demo U.",
            "tasklist-lockdownId": "",
            "canLogTime": true,
            "timeIsLogged": "0",
            "tags": [
                {
                    "id": 5,
                    "name": "api",
                    "color": "#b1da34"
                },
                {
                    "id": 4,
                    "name": "documentation",
                    "color": "#A9C3F9"
                }
            ]
        }
    ],
    "STATUS": "OK"
}

Notes:

  • responsible-party-ids is only returned if the task is assigned to one or more people. If it is not returned then the task is considered assigned to Anyone
  • DLM is a time stamp and stands for Date Last Modified. We use this internally for our caching system to make sure we can return data to the API calls quickly. Its not guaranteed to be in the response and can be safely ignored if you see it.
  • status is the current status of the task and could be one of the following: deletedcompletedreopenednew
  • private Private will return a 0, 1 or 2. An open task will be '0', A private task will be '1' and a task which is in a private list will be a '2' as it will inherit the privacy from the parent task list (or parent task)

See Todo Section in Data Reference

Notes

  1. A flag canEdit is returned with each task.

Retrieve a task

GET /tasks/{id}.json

Uses the integer ID to retrieve a single task.

Options

Attribute

Req/Opt

Default

Description

getFiles

Optional

true

Files attached to tasks can be returned within the task object by setting this parameter to true.

nestSubTasks

Optional

false

Sub tasks can be nested within each returned task object by setting this parameter to true.

includeCompletedSubtasks

Optional

false

Used in conjunction with nestSubTasks, this parameter can be used to include completed subtasks by setting it to true.

Notes:

  • responsible-party-ids is only returned if the task is assigned to one or more people. If it is not returned then the task is considered assigned to Anyone
  • private Private will return a 0, 1 or 2. An open task will be '0', A private task will be '1' and a task which is in a private list will be a '2' as it will inherit the privacy from the parent task list (or parent task)

Response

{
    "todo-item": {
        "canComplete": true,
        "project-id": "999",
        "creator-lastname": "User",
        "has-reminders": false,
        "todo-list-name": "Todos",
        "has-unread-comments": false,
        "due-date-base": "20140405",
        "order": "2001",
        "comments-count": "0",
        "private": "0",
        "status": "new",
        "todo-list-id": "999",
        "predecessors": [],
        "created-on": "2014-04-01T15:52:15Z",
        "canEdit": true,
        "content": "Write documentation",
        "has-predecessors": "0",
        "company-name": "Demo 1 Company",
        "id": "999",
        "creator-firstname": "Demo",
        "last-changed-on": "2014-04-01T15:53:02Z",
        "due-date": "20140405",
        "has-dependencies": "0",
        "completed": false,
        "position": "2001",
        "attachments-count": "0",
        "estimated-minutes": "0",
        "description": "",
        "boardColumn": [
                {
                    id: 32,
                    name: "My Inbox Board",
                    color: "#99DF72"
                }
        ],
        "priority": "",
        "progress": "0",
        "harvest-enabled": false,
        "viewEstimatedTime": true,
        "parentTaskId": "",
        "company-id": "2",
        "tasklist-lockdownId": "",
        "creator-avatar-url": "http://demo1company.teamwork.com/images/avatar.jpg",
        "canLogTime": true,
        "creator-id": "999",
        "project-name": "demo",
        "attachments": [],
        "start-date": "20140402",
        "parent-task": {
            "content": "sample parent task",
            "id": "12345"
         },
        "tasklist-private": "0",
        "timeIsLogged": "0",
        "lockdownId": "",
        "tags": [
            {
                "id": 5,
                "name": "api",
                "color": "#b1da34"
            },
            {
                "id": 4,
                "name": "documentation",
                "color": "#A9C3F9"
            }
        ]
    },
    "STATUS": "OK"
}

Response (if the Task is completed)

If a Task is already completed, the following fields will also be visible

{  
   "todo-items":[  
      {  
         [..]
         "status":"completed",
         "completed":true,
         "completed_on":"2017-04-20T12:50:19Z",
         [..]
      }
   ]
}

See Todo Section in Data Reference


Retrieve Task Dependencies

GET /tasks/{id}/dependencies.json

This will list any other Tasks that rely on this task to be completed first.

Response

{  
   "dependents":[  
      {  
         "responsible-party-id":"12345",
         "predecessorMust":"complete",
         "name":"my task",
         "id":"123456789",
         "hardness":"strong",
         "projectId":"54321",
         "dependentCant":"complete",
         "responsible-party-summary":"Daniel M.",
         "responsible-party-names":"Daniel M."
      }
   ],
   "STATUS":"OK"
}


Mark a task complete

PUT /tasks/{id}/complete.json

The specified task is marked as complete

Response

Returns HTTP status code 200 on success.


Mark a task uncomplete

PUT /tasks/{id}/uncomplete.json

The specified task is marked as un-complete (if called on an already un-complete task, has no effect).

Response

Returns HTTP status code 200 on success


Add a task

POST /tasklists/{id}/tasks.json

For the specified task list, creates a task.

Options

Attribute

Req/Opt

Default

Description

content

Required

 

The name of the task you are adding.

description

Optional

 

Tasks can be assigned a description.

parentTaskId

Optional

 

Set this to the ID of a parent task if you wish to make your task a subtask.

progress Optional 0 Set the progress from 0 to 90

notify

Optional

 

This parameter can be set to true to notify people assigned to this task by email.

responsible-party-id

Optional

-1

This can be used to assign the new task to a person or group of people.

For example:

  • -1 would assign the task to everyone

  • 32 would assign the task to user 32.

  • 32,55 would assign the task to users 32 and 55 etc.

start-date

Optional

 

Tasks can be assigned a date to start on. The format should be YYYYMMDD.

due-date

Optional

 

Tasks can be assigned a date for when they are due to be finished. The format should be YYYYMMDD.

priority

Optional

None

Tasks can be assigned the following priorities:

  • not set

  • low

  • medium

  • high

attachments

Optional

 

Existing files can be attached to the task by specifying a comma-separated list of File IDs.

pendingFileAttachments

Optional

 

New files can be attached using this option (see the uploading files section for more info). This is a comma-separated list of PendingFileRef's.

predecessors

Optional

 

An array of predecessor objects can be passed to specify which tasks need to have a specified state before this task can be marked as completed.

Each predecessor object should contain two keys:

  • id - The ID of the task that predecesses this one.
  • type - The state the task needs to be, can be "complete" or "start".

See the sample request below for an example.

estimated-minutes

Optional

0

Set an estimated number of minutes for a task to be completed by setting this parameter.

positionAfterTask

Optional

-2

A task can be placed after another task by setting this parameter to a task ID.

Additionally, some other options are available:

  • -2 - Ignore

  • -1 - Place task at the top of the list

  • 0 - Place task at the bottom of the list

tags Optional   A comma separated list of tags for the task
commentFollowerIds Optional   A comma separated list of user ids to add as followers for comments on this task
changeFollowerIds Optional   A comma separated list of user ids to add as followers for changes on this task
private Optional   Set to 1 to make the task Private. Setting a 0 will set the Task back to normal
grant-access-to Optional   Used in relation to private. If you set a Task as private (1), you can optionally add one or more User IDs to make the task visible to
columnId Optional   Used to put a new Task directly in to a Column in the Boards view

Request

{
  "todo-item": {
    "content": "Test Task",
    "notify": false,
    "description": "Test Task Sub Item",
    "due-date": "20140405",
    "start-date": "20140402",
    "estimated-minutes": "0",
    "private": 0,
    "grant-access-to": "",
    "priority": "low",
    "progress": "20",
    "attachments": [],
    "pendingFileAttachments": "",
    "responsible-party-id": 0,
    "predecessors": [
    	{
            "id": 439492,
            "type": "complete"
        }
    ],
    "tags":"api,documentation",
    "positionAfterTask": -1
  }
}


See Todo Section in Data Reference

Response

Returns HTTP status code 201 (Created) on success. The new item’s integer ID is also returned in the headers.

Adding a sub-task

You can create a sub-task on an existing task using a URL in the format:

POST /tasks/{id}.json


Edit a task

PUT /tasks/{id}.json

Updates an existing task. See the list of options from "Add a task".

Request

{
  "todo-item": {
    "content": "Task Item",
    "notify": false,
    "description": "Task Item Description",
    "due-date": "20140405",
    "start-date": "20140402",
    "private": "0",
    "grant-access-to": "",
    "priority": "high",
    "progress": "20",
    "estimated-minutes": "0",
    "responsible-party-id": "999",
    "attachments": [],
    "tasklistId": "",
    "pendingFileAttachments": "",
    "tags":"api,documentation",
    "columnId":"123"
  }
}
See Todo Section in Data Reference

Response

Returns HTTP status code 200 on success.


Destroy a task

DELETE /tasks/{id}.json

Deletes the given task.

Response

Returns HTTP status code 200 on success.


Reorder the tasks

PUT /tasklists/{id}/tasks/reorder.json

Re-orders tasks on the specified task list. Completed tasks cannot be reordered and any tasks not specified will be sorted after the tasks explicitly specified. 

Request

{
  "todo-items": [
    {
      "todo-item": {
        "id": "1000"
      }
    },
    {
      "todo-item": {
        "id": "999"
      }
    }
  ]
}

Response

Returns HTTP status code 200 on success.


Completed tasks

GET /completedtasks.json

Retrieve completed Tasks in the last 1 month. You can use the statedate and enddate to go further back in time.

Options

Attribute

Req/Opt

Default

Description

page

Optional

1

Optionally, you can set the page from which to start retrieving results. This is usually used in conjunction with the parameter pageSize.

For example:

  • ?page=2&pageSize=10 will retrieve results 10-20.

pageSize

Optional

250

The amount of tasks returned can be limited using this parameter. Normally used in conjunction with the page parameter.

startdate

Optional

 

Tasks within a range of dates can be returned by setting a startdate and enddate. The format should be YYYYMMDD.

For example:

  • ?startdate=20140512&enddate=20140513 will get all of the tasks from the 12th of May 2014 till the 13th of May 2014.

enddate

Optional

 

Must be used in conjunction with startdate, see above.

includeArchivedProjects

Optional

false Set to true or false to include archived Projects in the response

Change the completed date on close tasks

There is a 'allow-update' parameter that can be used to allow the completed date of a Task to be updated on a closed task. A completer-id is optional if you want to change the person that completed the task.

PUT to /tasks/{task_id}.json

Request

{
    "todo-item": {
        "allow-update":true,
        "completed-on":"yyyymmddhhmmss",
        "completer-id":{userId}
    }
}

Response

Returns HTTP status code 200 on success.

{
"STATUS": "OK"
}


Get Task Followers

To get a list of Users that are fllowing the activity of a given Task

GET to /tasks/{task_id}/followers.json

Optionally, you can pass a returnUserInfo=true paramter to expand on the user information.

Response - including the ?returnUserInfo=true

{
	"followers": [
		{
			"avatarUrl": "https://path/to/person.jpg",
			"firstName": "Joe",
			"companyName": "My Company",
			"followingChanges": true,
			"followingComments": true,
			"id": "12345",
			"companyId": "1",
			"lastName": "Bloggs"
		}
	],
	"STATUS": "OK"
}

Response - not including the ?returnUserInfo=true parameter

{
	"commentFollowerIds": [
		"12345"
	],
	"STATUS": "OK",
	"changeFollowerIds": [
		"12345"
	]
}


Set Task Followers

To set one or more users as Followers of a specified Task

PUT to /tasks/{task_id}.json

Request

{
	"todo-item": {
		"use-defaults": false,
		"commentFollowerIds": "12345,34567",
		"changeFollowerIds": "12345"
	}
}

Response

{
	"affectedTaskIds": "123456789",
	"STATUS": "OK"
}


Remove Task Followers

To remove all users from following a Task, submit the same JSON as adding followers, without passing any User IDs

PUT to /tasks/{task_id}.json

Request

{
	"todo-item": {
		"use-defaults": false,
		"commentFollowerIds": "",
		"changeFollowerIds": ""
	}
}

Response

{
	"affectedTaskIds": "123456789",
	"STATUS": "OK"
}


Quickly add multiple tasks

This allows you to add several tasks to a task list in a single API call

POST to /tasklists/{task_list_id}/quickadd.json

Request

{
    "content": "this is task one\nthis is task two\nthis is task three",
   "tasklistId": {task_list_id},
    "creator-id": {user_id},
    "notify": false,
    "private": false,
    "todo-item": {
        "responsible-party-id": "0",
        "start-date": "",
        "due-date": ""
    }
}

Response

{  
   "tasklistId":"{task_list_id}",
   "success":"2",
   "taskIds":"{task_id},{task_id},{task_id}",
   "STATUS":"OK",
   "failed":"0"
}

 


See "Todo" Section in Data Reference