Edit

Use the Microsoft To Do API

  • Article

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Use the Microsoft Graph To Do API built on todoTask to create an app that connects with tasks across Microsoft To Do clients. Build a variety of experiences with tasks, such as the following:

  • Create tasks from your app’s workflow, for example, from email or notifications, and save them in To Do. Use the linkedResource entity to store the link back to your app.
  • Sync your app’s existing tasks with To Do and create a single task view for better prioritization and manageability.
  • Manage To Do tasks in a custom business application.

The API supports both delegated and application permissions.

Before starting with the To Do API, take a look at the resources and how they relate to one another.

Screenshot highlighting To Do API entities. Screenshot shows list of task lists on the left, tasks within a specific task list in the center and, on the right, checklist items and linked resource along with other task properties.

Task list

In this API set, a task list is represented by todoTaskList which is a logical container of todoTask resources. You can currently create tasks only in a task list. To get all your task lists, make the following HTTP request:

GET /me/todo/lists

Task

In this API set, a task is represented by a todoTask resource which is a piece of work or personal item that can be tracked and completed. To get your tasks from a task list, make the following HTTP request:

GET /me/todo/lists/{todoTaskListId}/tasks

Checklist item

A checklistItem represents a subtask in a bigger todoTask. ChecklistItem allows breaking down a complex task into more actionable, smaller tasks. To get a checklistItem from a task, make the following HTTP request:

GET /me/todo/lists/{todoTaskListId}/tasks/{todoTaskId}/checklistItems/{checklistItems}

Linked resource

A linkedResource represents any item from a partner application related to the task, e.g. an item like email from where a task was created. You can use it to store information and the link back to the related item in your app. To get a linked resource from a task, make the following HTTP request:

GET /me/todo/lists/{todoTaskListId}/tasks/{todoTaskId}/linkedresources/{linkedResourceId}

Track changes using delta query

For performance reasons, you may want to maintain a local cache of objects, and periodically synchronize the local cache with the server, using delta query.

The following To Do API resources support delta query: