Task Lists


Get all task lists for a project

GET /projects/{project_id}/tasklists.json
GET /projects/{project_id}/tasklists.json?responsible-party-id={id}
GET /projects/{project_id}/tasklists.json?getOverdueCount=yes
GET /projects/{project_id}/tasklists.json?responsible-party-id={id}&getOverdueCount=yes
GET /projects/{project_id}/tasklists.json?status=completed&getCompletedCount=yes

Retrieves all project task lists

Options:

  • Passing getOverdueCount will return the number of overdue tasks overdue-count for each task list. 
  • Passing getCompletedCount will return the number of completed tasks completed-count for each task list.
  • Status: You can use the status option to restrict the Task Lists returned - valid values are allactive, and completed. The default is "active"
  • Passing showMilestones=1 will add Milestone information in to the response, if a Milestone is attached to the Task List

Response

{
    "tasklists": [
        {
            "projectid": "999",
            "name": "Inbox",
            "description": "",
            "milestone-id": "",
            "uncompleted-count": "1",
            "complete": false,
            "private": "0",
            "overdue-count": "0",
            "project-name": "demo",
            "pinned": false,
            "id": "999",
            "position": "3999",
            "completed-count": "1",
            "milestone": {
                "project-id": 999,
                "canComplete": true,
                "creator-lastname": "Mackey",
                [...]
            },
        }
    ],
    "STATUS": "OK"
}

Pagination:

By default we'll send back 250 task list/todo list records per page. Inspect the Response Headers for the following values:

  • X-Page (The current page being returned)
  • X-Pages (The total number of pages available)
  • X-Records (The total number of items available
  • You can request a specific page by calling the same API call and adding the parameter &page=n where n is the page you want. e.g: &page=2 for page 2, &page=5 for page 5.

Retrieve Single task list

GET /tasklists/{id}.json

Retrieves the task list corresponding to the submitted integer ID.

Response

{
    "todo-list": {
        "projectid": "999",
        "name": "Inbox",
        "description": "",
        "milestone-id": "",
        "uncompleted-count": "1",
        "complete": false,
        "private": "0",
        "overdue-count": "0",
        "project-name": "demo",
        "pinned": false,
        "id": "999",
        "position": "3999",
        "completed-count": "1"
    },
    "STATUS": "OK"
}

See Todo Section in Data Reference


Update list

PUT /tasklists/{id}.json

Updates the specified task list record with the changes indicated by the submitted data.

Request

{
    "todo-list": {
      "name": "Todos",
      "milestone-id": "",
      "description": "A basic todo list for the project",
      "private": "0",
      "grant-access-to":""
    }
}

See Todo Section in Data Reference

Response

Returns HTTP status code 200 on success, or any other code on error.


Create list

POST /projects/{project_id}/tasklists.json

Creates a new task list based on the submitted JSON or XML data. If you wish to base the new list on a task list template that you’ve created previously, you can specify the todo-list-template-id field in the data, and the new list will default to the name, description, and tasks indicated by that template.

Task List Template Options

When you're creating the tasklist using a todo-list-template-id you can pass the following:

  • todo-list-template-id
  • todo-list-template-start-date (Blank or YYYYMMDD format e.g: 20150314)
  • todo-list-template-keep-off-weekends (Boolean: default false)
  • todo-list-template-assignments (Blank or struct)

"todo-list-template-assignments" : {
	"Developer" : "1,2",
	"Designer" : "4",
	"Project Manager" : "1"
}

The format of the todo-list-template-assignments struct should be the role name and the value being a comma separated list of user-ids to assign the task to. 

Additonal Options

  • You can pass 'addToTop:true' to force the new item to the top of the tasklists list. The default is false which adds the item to the bottom of the list of tasklists.


Request

{
    "todo-list": {
      "name": "Master",
      "private": false,
      "pinned": true,
      "milestone-id": "",
      "description": "A master todo list for the project",
      "todo-list-template-id":  ""
    }
}

See Todo Section in Data Reference

Response

Returns HTTP status code 201 (“Created”) on success, with the Location header set to the “Get list” URL for the new list. The new list’s ID can be extracted from that URL. On failure, a non-200 status code will be returned, possibly with error information as the response’s content.


Delete a task list

DELETE /tasklists/{id}.json

Destroys the given task list and all of its associated tasks

Response

Returns HTTP status code 200 on success.


Reorder lists

PUT /projects/{project_id}/tasklists/reorder.json

Reorders the lists in the project according to the ordering given. Any lists that are not explicitly specified will be positioned after the lists that are specified.

Request

{
  "todo-lists": [
    {
      "todo-list": {
        "id": "1000"
      }
    },
    {
      "todo-list": {
        "id": "999"
      }
    }
  ]
}

Response

Returns HTTP status code 200 on success.


Copy a Task list, or copy a Task list to another project

PUT to /tasklist/{tasklist_id}/copy.json

Request

{
	"projectId": 999,
	"includeCompletedTasks": 1
}

Response

Returns HTTP status code 200 on success.

Move a Task list to another project

PUT to /tasklist/{tasklist_id}/move.json

Move an existing Task list to another Project, based on its Project ID

Request

{
    "projectId": "999"
}

Response

Returns HTTP status code 200 on success.


Template Task Lists: Get all template task lists

GET /tasklists/templates.json

Retrieves all template task lists on your Teamwork Account

Note:

  • This is only available for API Keys associated with Administrators in the Owner Company

Response

{
  "tasklists": [
    {
      "name": "Example Template",
      "description": "",
      "uncompleted-count": "2",
      "id": "830",
      "complete": false,
      "private": false,
      "position": "3996"
    }
    :
    :
    :
  ],
  "STATUS": "OK"
}