We are committed to providing a rich task infrastructure through the Microsoft Graph To-Do tasks APIs so partners and customers can build delightful task experiences for their users. We’ve been listening to customers’ requests for new features, and we’re excited to share that we’re releasing new capabilities in the To Do APIs, including file attachments on tasks, support for categories, and more.

Attachments

We’ve introduced support for fetching, uploading and deleting file attachments on a task on the beta endpoint. There are two methods to upload attachments on a task:

1. To attach files of any size, create an upload session, and iteratively use PUT call to upload ranges of bytes of the file until you have uploaded the entire file. See attach files to a To Do task for an example.
2. If the file size is under 3 MB, you can do a single POST on the attachment’s navigation property of todoTask; See create attachment for an example.

Categories

Categories lets you easily tag or label tasks in To Do and it has been one of the top requests from partners. We recently released categories support on the Microsoft Graph v1 endpoint.

Now, developers will get the categories as part of the response when querying for users’ task. Each category corresponds to the displayName property of an outlookCategory that the user has defined.

Example

GET https://graph.microsoft.com/v1.0/me/todo/lists/<list-id>/tasks/<task-id>
HTTP/1.1 200 OK
        {
            "importance": "high",
            "isReminderOn": false,
            "status": "completed",
            "title": "Review Q1 marketing",
            "createdDateTime": "2022-04-28T12:18:39.2889451Z",
            "lastModifiedDateTime": "2022-06-01T04:22:16.0704279Z",
            "categories": [
                "Planning",
                "Urgent"
],
            "id": "AAMj1YgAGEuIMbwAAAA==",
            "body": {
                "content": "",
                "contentType": "text"
            }
            }

checklistItems

To Do allows breaking down a complex task into more actionable, smaller steps. Now, you can also create, read, update, and delete steps using the checklistItem on the Microsoft Graph v1 endpoint.

Examples

Retrieve checklistitems as part of Tasks resource

GET https://graph.microsoft.com/v1.0/me/todo/lists/<list-id>/tasks/<task-id>

HTTP/1.1 200 OK
        {
            "importance": "normal",
            "isReminderOn": false,
            "status": "notStarted",
            "title": "Review Q1 marketing",
            "createdDateTime": "2022-06-14T04:52:14.3497205Z",
            "lastModifiedDateTime": "2022-06-14T04:54:37.3021207Z",
            "categories": [],
            "id": "AQMkADAwA==",
            "body": {
                "content": "",
                "contentType": "text"
            },
            "checklistItems": [
                {
                    "displayName": "Review introduction",
                    "createdDateTime": "2022-06-14T04:53:25.0246583Z",
                    "isChecked": false,
                    "id": "f341acf2-b3e2-45ae-883d-b6490d240735"
                },
                {
                    "displayName": "Share with colleagues",
                    "createdDateTime": "2022-06-14T04:54:27.7648563Z",
                    "isChecked": false,
                    "id": "9357655e-577b-41e7-ada4-8f90692b84ef"
                }
            ]
        }

Get a specified checklistItem

GET https://graph.microsoft.com/v1.0/me/todo/lists/<list-id>/tasks/<task-id>/checklistItems/<checklistItem-id>

HTTP/1.1 200 OK
                {
                    "displayName": "Review introduction",
                    "createdDateTime": "2022-06-14T04:53:25.0246583Z",
                    "isChecked": false,
                    "id": "f341acf2-b3e2-45ae-883d-b6490d240735"
                }

Create a checklistItem

POST https://graph.microsoft.com/v1.0/me/todo/lists/<list-id>/tasks/<task-id>/checklistItems
{
     "displayName": "Get feedback",
}

HTTP/1.1 201 Created
{
    "displayName": "Get feedback",
    "createdDateTime": "2022-06-14T05:07:45.6021029Z",
    "isChecked": false,
    "id": "c55af287-11ce-4db9-beff-f9427963f4a1"
}

For more information and examples, see the detailed documentation for checklistItems.

StartDateTime

We are introducing a new property in beta, startDateTime, that shows the date in a specified time zone at which the task is scheduled to start. You can see this property while querying users To Do tasks.

Example

GET https://graph.microsoft.com/beta/me/todo/lists/<list-id>/tasks/<task-id>
HTTP/1.1 200 OK
        {
            "importance": "high",
            "isReminderOn": false,
            "status": "completed",
            "title": "Review Q1 marketing",
            "createdDateTime": "2022-04-28T12:18:39.2889451Z",
            "lastModifiedDateTime": "2022-06-01T04:22:16.0704279Z",
            "categories": [
                "Planning",
                "Urgent"
],
     "startDateTime": { 
  "dateTime": "2012-07-23T07:00:00.0000000", 
  "timeZone": "UTC" 
      }, 
            "id": "AAMj1YgAGEuIMbwAAAA==",
            "body": {
                "content": "",
                "contentType": "text"
            }
            }

Retirement of Tasks (preview) APIs at me/tasks

The to-do API set built on baseTask was retired on May 31, 2022 and will stop returning data on August 31, 2022. We made this change to bring clarity for developers around which APIs to use to access users’ tasks.

What do I need to do?

If you’re testing or building an application with any of the below resource, please plan to use the recommended resources from To Do tasks API.

Thank you for continuing with us on our journey as we continue to improve productivity for everyone. If you have any feedback, suggestions or question, email us or let us know on our feedback page.

Happy coding!