At Microsoft Build 2020, we introduced the new Microsoft Graph To Do APIs. Today, we’re excited to announce that APIs are now available in public preview on the beta endpoint of Graph.

Microsoft To Do and Planner form the backbone of tasks in Microsoft 365. To Do is ideal for managing personal tasks across work and life while Planner is great for team tasks. Tasks come from everywhere, and millions of people use To Do as single destination to understand and manage their personal tasks. Besides offering best in class mobile apps for Android, iOS, Windows, Mac, and web, To Do is also deeply integrated with Microsoft 365 hubs, Outlook, and Teams. Using the new APIs, developers can bring tasks from their apps into To Do and become a core part of users’ productivity stories in Microsoft 365.

API details

We have a todoTaskList entity, consisting of a collection of todoTask entities. Also, we are introducing a new entity called linkedResource which enables task completion. You can use it to store and display the link back to the item in your app from where the task was created.

The new APIs support work, school, and personal Microsoft accounts. The required permission scope is Tasks.ReadWrite. We’ll support the following endpoints:

Here are some examples of requests and responses with the new APIs.

1. List all task lists
2. Create task in a task list
3. Create linked resource

Use cases

Partners in our preview program are using To Do APIs to support the following use cases:

1. Create tasks from your app’s workflow (tasks from email, notifications, etc.) and save them into To Do. (Don’t forget to use the linkedResource entity to store the link back to your app!)
2. Sync your app’s existing tasks with To Do and create a single task view for better task prioritization and manageability.

3. Manage user To Do tasks in your custom business application.

To see this in action, check out our partner demos in our Build 2020 session.

Deprecation of Outlook Tasks APIs

Microsoft To Do is the upgraded version of the classic Outlook Tasks experience. The underlying storage and basic schema are exactly same. But with its new modern experience, To Do brings new modern task management capabilities like linkedResource, data extensions, and more.

We’re replacing the Outlook Tasks experience with To Do, starting with Outlook for the web. Replacing APIs is a crucial part of this modernization. Now that the To Do APIs are available in beta, developers should update any existing processes or integrations that use the Graph Outlook Tasks beta APIs so, they can use the new To Do APIs. We’re deprecating Outlook Tasks APIs with this release. Graph Outlook Tasks APIs will stop returning data after August 20, 2022.

Apart from the new capabilities, To Do APIs has most of the Outlook Task capabilities. Please note that outlookTaskGroup entity, extended properties and assignedTo, owner properties of outlookTask entity won’t be available in To Do APIs. We hope to release few other outlookTask properties like attachments, categories, etc. in future releases. Please let us know on our User Voice page if you would like us to prioritize any particular capability.

To transition to the new APIs, some query changes are necessary. For example, to get the properties and relationships of a task, the old query would look like:

GET https://graph.microsoft.com/beta/me/outlook/tasks/{id}

The new query will look like:

GET https://graph.microsoft.com/beta/me/todo/lists/{id}/tasks/{id}

For more information check out the documentation.

Next steps

We expect to make To Do APIs generally available on Microsoft Graph by the end of 2020. Our API roadmap contains previews of new capabilities like webhooks.

You can use the preview of To Do component from Microsoft Graph Toolkit for reusable, framework-agnostic web components and helpers for accessing and working with Microsoft Graph.

We can’t wait to see what you’ll do with the new To Do APIs.  You can explore them now on Microsoft Graph Explorer, and if you have any feedback, suggestions or question, email us at todofeedback@microsoft.com or let us know on our UserVoice page or on Stack Overflow.