[DEPRECATED] Outlook Task REST API reference (version 2.0)

Applies to: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Note

Version 2.0 of the Outlook REST API is deprecated.

As announced on November 17, 2020, version 2.0 of the Outlook REST API has been deprecated. The v2.0 REST endpoint will be fully decommissioned in March 2024, and the v2.0 documentation will be removed shortly afterwards. Migrate existing apps to use Microsoft Graph. See a comparison to start your migration.

The Outlook Task REST API lets you create, read, synchronize, update, and delete a user's tasks that are secured by Azure Active Directory in Office 365. The user's account can be on Office 365 or a Microsoft account (Hotmail.com, Live.com, MSN.com, Outlook.com, and Passport.com).

Note

For simplicity of reference, the rest of this article uses Outlook.com to include these Microsoft account domains.

Not interested in v2.0 of the API? In the table of contents on the left, go to the Office 365 REST API reference section and select the version you want.

Overview

You can use a task in Outlook to track a work item. You can note its start, due, or actual completion dates, its progress or status, or whether it's recurring or requires reminding.

Tasks are organized in task folders which are in turn organized in task groups. Each mailbox has a default task folder (with the Name property Tasks) and a default task group (Name property is My Tasks).

Using the Task REST API

Authentication

Like other Outlook REST API, for every request to the Task REST API, you should include a valid access token. Getting an access token requires you to have registered and identified your app, and obtained the appropriate authorization.

You can find out more about some streamlined registration and authorization options for you. Keep this in mind as you proceed with the specific operations in the Task REST API.

Version of API

This API has been promoted from preview to General Availability (GA) status. It is supported in the v2.0 and beta versions of the Outlook REST API.

Target user

The Task API requests are always performed on behalf of the signed-in user.

See Use the Outlook REST API for more information common to all subsets of the Outlook REST API.

URL parameters

The examples in this article use the following placeholders as parameters of REST request URLs.

Parameter	Type	Description
URL parameters
attachment_id	string	The numeric ID of an attachment, unique in the user's mailbox.
folder_id	string	The default Tasks well-known folder name, or a numeric ID of a task folder, unique in the user's mailbox.
group_id	string	The numeric ID of a task group, unique in the user's mailbox.
task_id	string	The numeric task ID, unique in the user's mailbox.

Specifying the StartDateTime and DueDateTime properties

When creating a task:

• StartDateTime and DueDateTime are optional, but setting StartDateTime requires setting DueDateTime to the same or later date.
• If you set only the StartDateTime, the DueDateTime will be automatically set to the same value as the StartDateTime.
• If you set DueDateTime to null, then StartDateTime will also be automatically set to null.

If you choose to set StartDateTime or DueDateTime when creating or updating a task:

• Specify the date and time zone information.
• Don't specify a specific time in these properties, as the POST (or PATCH) method always ignores it and assumes midnight in the specified time zone.
• By default, the POST (or PATCH) method converts the value to UTC and returns that in UTC in the response.

For example, if you specify April 26 in Eastern Standard Time (EST) in the StartDateTime:

  "StartDateTime": {
      "DateTime": "2016-04-26T09:00:00",
      "TimeZone": "Eastern Standard Time"
  }

POST (or PATCH) ignores the time portion, converts April 26 midnight in EST to UTC and returns that value in UTC in the response:

  "StartDateTime": {
    "DateTime": "2016-04-26T04:00:00.0000000",
    "TimeZone": "UTC"
  }

You can use the Prefer: outlook.timezone header to have all the date-related properties in the response represented in a time zone different than UTC.

Returning date-related properties in a custom time zone

Date-related properties in the Task resource include the following:

• CompletedDateTime
• CreatedDateTime
• DueDateTime
• LastModifiedDateTime
• ReminderDateTime
• StartDateTime

By default, the POST, GET, PATCH, and Complete operations return date-related properties in their REST responses in UTC. You can use the Prefer: outlook.timezone header to have all the date-related properties in the response represented in a time zone different than UTC. The following example returns date-related properties in EST in the corresponding response:

Prefer: outlook.timezone="Eastern Standard Time"

See Use the Outlook REST API for more information common to all subsets of the Outlook REST API.

Create tasks

Minimum required scope

• https://outlook.office.com/tasks.readwrite

Create a task. There are 2 main scenarios.

You can create a task in the default task group (My Tasks) and default task folder (Tasks) of the user's mailbox. In this case, you don't need to specify any task group or task folder.

POST https://outlook.office.com/api/v2.0/me/tasks

You can also create a task in a specific task folder:

POST https://outlook.office.com/api/v2.0/me/taskfolders('{folder_id}')/tasks

In the request body, supply a JSON representation of the task to create.

See more information about setting StartDateTime and DueDateTime.

Find out how to specify a certain time zone for all date-related properties in the response.

Response

Success status code: 201 Created

Response body: The created task.

Sample request

The first example creates a task in the specified task folder, and expresses StartDateTime and DueDateTime in Pacific Standard Time (PST) in the request body.

POST https://outlook.office.com/api/v2.0/me/taskfolders('AAMkADIyAAAhrbPXAAA=')/tasks
Content-Type: application/json

{
  "Subject": "Shop for dinner",
  "StartDateTime": {
      "DateTime": "2016-04-23T18:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "DueDateTime":  {
      "DateTime": "2016-04-25T13:00:00",
      "TimeZone": "Pacific Standard Time"
  }
}

Sample response

The POST method ignores the time portion in the request body and assumes the time to be always midnight in the specified time zone (PST). Then, by default, the POST method converts and shows all the date-related properties in UTC in the response.

Status code: 201 Created

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/TaskFolders('AAMkADIyAAAhrbPXAAA%3D')/Tasks/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Tasks('AAMkADIyAAAhrb_PAAA=')",
  "@odata.etag": "W/\"hmM7Eb/jgEec8l3+gkJEawAAIbAOlw==\"",
  "Id": "AAMkADIyAAAhrb_PAAA=",
  "CreatedDateTime": "2016-04-22T05:44:01.2012012Z",
  "LastModifiedDateTime": "2016-04-22T05:44:02.9980882Z",
  "ChangeKey": "1/KC9Vmu40G3DwB6Lgs7MAAAIOJMxw==",
  "Categories": [ ],
  "AssignedTo": null,
  "Body": {
    "ContentType": "Text",
    "Content": ""
  },
  "CompletedDateTime": null,
  "DueDateTime": {
    "DateTime": "2016-04-25T07:00:00.0000000",
    "TimeZone": "UTC"
  },
  "HasAttachments":false,
  "Importance": "Normal",
  "IsReminderOn": false,
  "Owner": "Administrator",
  "ParentFolderId": "AQMkADA1MTkAAAAIBEgAAAA==",
  "Recurrence": null,
  "ReminderDateTime": null,
  "Sensitivity": "Normal",
  "StartDateTime": {
    "DateTime": "2016-04-23T07:00:00.0000000",
    "TimeZone": "UTC"
  },
  "Status": "NotStarted",
  "Subject": "Shop for dinner"
}

Sample request

To show how the Prefer: outlook.timezone header works, the next example creates a task, expresses StartDateTime and DueDateTime in Eastern Standard Time (EST), and includes a Prefer header of Pacific Standard Time (PST).

POST https://outlook.office.com/api/v2.0/me/tasks HTTP/1.1

Content-Type: application/json
Prefer: outlook.timezone="Pacific Standard Time"

{
  "Subject": "Shop for children's weekend",
  "StartDateTime": {
      "DateTime": "2016-05-03T09:00:00",
      "TimeZone": "Eastern Standard Time"
  },
  "DueDateTime":  {
      "DateTime": "2016-05-05T16:00:00",
      "TimeZone": "Eastern Standard Time"
  }
}

Sample response

Just like in the last example, the POST method ignores the time portion of StartDateTime and DueDateTime in the request body and assumes the time to be always midnight in the specified time zone (EST).

Since the Prefer header specifies PST, the POST method expresses all the date-related properties in the response in PST. In particular, for the StartDateTime and DueDateTime properties, the POST method converts midnight in EST to PST and returns them in PST in the response.

Status code: 201 Created

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Tasks/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('86b6ceaf-57f7-4278-97c4-4da0a97f6cdb@70559e59-b378-49ea-8e53-07a3a3d27f5b')/Tasks('AAMkADA1MHgwAAA=')",
    "@odata.etag": "W/\"1/KC9Vmu40G3DwB6Lgs7MAAAIW9XXA==\"",
    "Id": "AAMkADA1MHgwAAA=",
    "CreatedDateTime": "2016-04-22T15:19:18.9526004-07:00",
    "LastModifiedDateTime": "2016-04-22T15:19:19.015101-07:00",
    "ChangeKey": "1/KC9Vmu40G3DwB6Lgs7MAAAIW9XXA==",
    "Categories": [
    ],
    "AssignedTo": null,
    "Body": {
        "ContentType": "Text",
        "Content": ""
    },
    "CompletedDateTime": null,
    "DueDateTime": {
        "DateTime": "2016-05-04T21:00:00.0000000",
        "TimeZone": "Pacific Standard Time"
    },
    "HasAttachments":false,
    "Importance": "Normal",
    "IsReminderOn": false,
    "Owner": "Administrator",
    "ParentFolderId": "AQMkADA1MTEgAAAA==",
    "Recurrence": null,
    "ReminderDateTime": null,
    "Sensitivity": "Normal",
    "StartDateTime": {
        "DateTime": "2016-05-02T21:00:00.0000000",
        "TimeZone": "Pacific Standard Time"
    },
    "Status": "NotStarted",
    "Subject": "Shop for children's weekend"
}

Get tasks

• Get all tasks
• Get a task

Get all tasks

Minimum required scope

• https://outlook.office.com/tasks.read

Get multiple tasks.

You can get all the tasks in the signed-in user's mailbox.

GET https://outlook.office.com/api/v2.0/me/tasks

Or you can get all the tasks in a specific folder:

GET https://outlook.office.com/api/v2.0/me/taskfolders('{folder_id}')/tasks

If there is more than one task group, and you want to get all the tasks in a specific task group, first get all the task folders in that task group, and then get the tasks in each of these task folders.

Response

Success status code: 200 OK

Response body: A task collection

By default, date-related properties in the response are expressed in UTC. Find out how to specify a certain time zone for all date-related properties in the response.

Sample request

The following example gets all the tasks in the user's mailbox.

GET https://outlook.office.com/api/v2.0/me/tasks

Sample response

Status code: 200 OK

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Tasks",
  "value": [
    {
      "@odata.id": "https://outlook.office.com/api/v2.0/Users('86b6ceaf-57f7-4278-97c4-4da0a97f6cdb@70559e59-b378-49ea-8e53-07a3a3d27f5b')/Tasks('AAMkADA1MTrfAAA=')",
      "@odata.etag": "W/\"1/KC9Vmu40G3DwB6Lgs7MAAAIOJMxw==\"",
      "Id": "AAMkADA1MTrfAAA=",
      "CreatedDateTime": "2016-04-22T05:44:01.2012012Z",
      "LastModifiedDateTime": "2016-04-22T05:44:02.9980882Z",
      "ChangeKey": "1/KC9Vmu40G3DwB6Lgs7MAAAIOJMxw==",
      "Categories": [ ],
      "AssignedTo": null,
      "Body": {
        "ContentType": "Text",
        "Content": ""
      },
      "CompletedDateTime": null,
      "DueDateTime": {
        "DateTime": "2016-04-25T07:00:00.0000000",
        "TimeZone": "UTC"
      },
      "HasAttachments":false,
      "Importance": "Normal",
      "IsReminderOn": false,
      "Owner": "Administrator",
      "ParentFolderId": "AQMkADA1MTBEgAAAA==",
      "Recurrence": null,
      "ReminderDateTime": null,
      "Sensitivity": "Normal",
      "StartDateTime": {
        "DateTime": "2016-04-23T07:00:00.0000000",
        "TimeZone": "UTC"
      },
      "Status": "NotStarted",
      "Subject": "Shop for dinner"
    },
    {
      "@odata.id": "https://outlook.office.com/api/v2.0/Users('86b6ceaf-57f7-4278-97c4-4da0a97f6cdb@70559e59-b378-49ea-8e53-07a3a3d27f5b')/Tasks('AAMkADA1MTrgAAA=')",
      "@odata.etag": "W/\"1/KC9Vmu40G3DwB6Lgs7MAAAIOJMyQ==\"",
      "Id": "AAMkADA1MTrgAAA=",
      "CreatedDateTime": "2016-04-22T06:03:35.9279794Z",
      "LastModifiedDateTime": "2016-04-22T06:03:35.9436052Z",
      "ChangeKey": "1/KC9Vmu40G3DwB6Lgs7MAAAIOJMyQ==",
      "Categories": [ ],
      "AssignedTo": null,
      "Body": {
        "ContentType": "Text",
        "Content": ""
      },
      "CompletedDateTime": null,
      "DueDateTime": {
        "DateTime": "2016-04-27T04:00:00.0000000",
        "TimeZone": "UTC"
      },
      "HasAttachments":false,
      "Importance": "Normal",
      "IsReminderOn": false,
      "Owner": "Administrator",
      "ParentFolderId": "AQMkADA1MTBEgAAAA==",
      "Recurrence": null,
      "ReminderDateTime": null,
      "Sensitivity": "Normal",
      "StartDateTime": {
        "DateTime": "2016-04-26T04:00:00.0000000",
        "TimeZone": "UTC"
      },
      "Status": "NotStarted",
      "Subject": "Shop for dinner"
    }
  ]
}

Get a task

Minimum required scope

• https://outlook.office.com/tasks.read

Get a specific task.

GET https://outlook.office.com/api/v2.0/me/tasks('{task_id}')

Response

Success status code: 200 OK

Response body: The requested task.

By default, date-related properties in the response are expressed in UTC. Find out how to specify a certain time zone for all date-related properties in the response.

Sample request

GET https://outlook.office.com/api/v2.0/me/tasks('AAMkADA1MTrgAAA=')

Sample response

Status code: 200 OK

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Tasks/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Tasks('AAMkADA1MTrgAAA=')",
  "@odata.etag": "W/\"hmM7Eb/jgEec8l3+gkJEawAAIa/+kw==\"",
  "Id": "AAMkADA1MTrgAAA=",
  "CreatedDateTime": "2016-04-22T06:03:35.9279794Z",
  "LastModifiedDateTime": "2016-04-22T06:03:35.9436052Z",
  "ChangeKey": "1/KC9Vmu40G3DwB6Lgs7MAAAIOJMyQ==",
  "Categories": [ ],
  "AssignedTo": null,
  "Body": {
    "ContentType": "Text",
    "Content": ""
  },
  "CompletedDateTime": null,
  "DueDateTime": {
    "DateTime": "2016-04-27T04:00:00.0000000",
    "TimeZone": "UTC"
  },
  "HasAttachments":false,
  "Importance": "Normal",
  "IsReminderOn": false,
  "Owner": "Administrator",
  "ParentFolderId": "AQMkADA1MTBEgAAAA==",
  "Recurrence": null,
  "ReminderDateTime": null,
  "Sensitivity": "Normal",
  "StartDateTime": {
    "DateTime": "2016-04-26T04:00:00.0000000",
    "TimeZone": "UTC"
  },
  "Status": "NotStarted",
  "Subject": "Shop for dinner"
}

Update tasks

Minimum required scope

• https://outlook.office.com/tasks.readwrite

Change writeable properties of a task.

PATCH https://outlook.office.com/api/v2.0/me/tasks/{task_id}

In the request body, supply a JSON representation of the writable properties to update in the task.

See more information about setting StartDateTime and DueDateTime.

The CompletedDateTime property can be set by the Complete action, or explicitly by a PATCH operation. If you use PATCH to set CompletedDateTime, make sure you set Status to Completed as well.

By default, date-related properties in response are expressed in UTC. Find out how to specify a custom time zone for all date-related properties in the response.

Response

Success status code: 200 OK

Response body: The updated task.

Sample request

The following example modifies the DueDateTime and uses the Prefer: outlook.timezone header to specify the date-related properties to be expressed in Eastern Standard Time (EST) in the response.

PATCH https://outlook.office.com/api/v2.0/me/tasks('AAMkADA1MTHgwAAA=')

Prefer: outlook.timezone="Eastern Standard Time"
Content-Type: application/json

{
  "DueDateTime":  {
      "DateTime": "2016-05-06T16:00:00",
      "TimeZone": "Eastern Standard Time"
  }
}

Sample response

Status code: 200 OK

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Tasks/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Tasks('AAMkADA1MTHgwAAA=')",
  "@odata.etag": "W/\"hmM7Eb/jgEec8l3+gkJEawAAIa/+lg==\"",
  "Id": "AAMkADA1MTHgwAAA=",
    "CreatedDateTime": "2016-04-22T18:19:18.9526004-04:00",
    "LastModifiedDateTime": "2016-04-22T18:38:20.5541528-04:00",
    "ChangeKey": "1/KC9Vmu40G3DwB6Lgs7MAAAIW9XXg==",
    "Categories": [
    ],
    "AssignedTo": null,
    "Body": {
        "ContentType": "Text",
        "Content": ""
    },
    "CompletedDateTime": null,
    "DueDateTime": {
        "DateTime": "2016-05-06T00:00:00.0000000",
        "TimeZone": "Eastern Standard Time"
    },
    "HasAttachments":false,
    "Importance": "Normal",
    "IsReminderOn": false,
    "Owner": "Administrator",
    "ParentFolderId": "AQMkADA1MTIBEgAAAA==",
    "Recurrence": null,
    "ReminderDateTime": null,
    "Sensitivity": "Normal",
    "StartDateTime": {
        "DateTime": "2016-05-03T00:00:00.0000000",
        "TimeZone": "Eastern Standard Time"
    },
    "Status": "NotStarted",
    "Subject": "Shop for children's weekend"
}

Delete tasks

Minimum required scope

• https://outlook.office.com/tasks.readwrite

Delete the specified task in the user's mailbox.

DELETE https://outlook.office.com/api/v2.0/me/tasks('{task_id}')

Response

Success status code: 204 No Content

Response body: None

Sample request

DELETE https://outlook.office365.com/api/v2.0/me/tasks('AAMkADIyAAAhrb_QAAA=')

Sample response

Status code: 204 No Content

Complete tasks

Minimum required scope

• https://outlook.office.com/tasks.readwrite

Complete a task and set the CompletedDateTime property to the current date, and Status property to Completed.

POST https://outlook.office.com/api/v2.0/me/tasks('{task_id}')/complete

Note

CompletedDateTime represents the date when the task is finished. The time portion of the CompletedDateTime is set to midnight UTC by default.

An app can specify a custom time zone in a Prefer request header. The following is an example to set CompletedDateTime to the Pacific Standard Time (PST) time zone:

Prefer: outlook.timezone="Pacific Standard Time"

This request header sets all date-related properties in the response to the specified time zone.

Response

Success status code: 200 OK

Response body: The completed task in a task collection. If you are completing a task in a recurring series, the task collection will contain the completed task in the series, and the next task in the series.

Sample request

The following example marks the specified task as complete. Because it specifies Pacific Standard Time (PST) in the Prefer: outlook.timezone header, the CompletedDateTime and other date-related properties in the response are expressed in PST.

POST https://outlook.office.com/api/v2.0/me/tasks('AAMkADA1MT15rfAAA=')/complete

Prefer: outlook.timezone="Pacific Standard Time"

Sample response

Status code: 200 OK

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Tasks",
  "value": [
    {
      "@odata.id": "https://outlook.office365.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Tasks('AAMkADA1MT15rfAAA=')",
      "@odata.etag": "W/\"hmM7Eb/jgEec8l3+gkJEawAAIa/+lw==\"",
      "Id": "AAMkADA1MT15rfAAA=",
      "CreatedDateTime": "2016-04-21T22:44:01.2012012-07:00",
      "LastModifiedDateTime": "2016-04-22T19:28:38.5300447-07:00",
      "ChangeKey": "1/KC9Vmu40G3DwB6Lgs7MAAAIW9XYQ==",
      "Categories": [
      ],
      "AssignedTo": null,
      "Body": {
          "ContentType": "Text",
          "Content": ""
      },
      "CompletedDateTime": {
          "DateTime": "2016-04-22T00:00:00.0000000",
          "TimeZone": "Pacific Standard Time"
      },
      "DueDateTime": {
          "DateTime": "2016-04-25T00:00:00.0000000",
          "TimeZone": "Pacific Standard Time"
      },
      "HasAttachments":false,
      "Importance": "Normal",
      "IsReminderOn": false,
      "Owner": "Administrator",
      "ParentFolderId": "AQMkADA1MTIBEgAAAA==",
      "Recurrence": null,
      "ReminderDateTime": null,
      "Sensitivity": "Normal",
      "StartDateTime": {
          "DateTime": "2016-04-21T00:00:00.0000000",
          "TimeZone": "Pacific Standard Time"
      },
      "Status": "Completed",
      "Subject": "Shop for dinner"
    }
  ]
}

Synchronize tasks or task folders

Minimum required scope

• http://outlook.office.com/tasks.readwrite

You can synchronize tasks in a task folder, or task folders in a user's mailbox. Synchronizing tasks is a per-folder operation, for example, you can synchronize all of the tasks in your default task folder Tasks. To synchronize tasks in a folder hierarchy, you need to synchronize each task folder individually. The processes to synchronize tasks or task folders are similar, typically requiring a round of two or more sync requests, each of which is a GET call.

Use the GET method much like the way you get tasks in a folder, or get task folders in a mailbox, except that you include certain request headers, and deltaToken or a skipToken when appropriate.

Request headers

• You must specify the Prefer: odata.track-changes header in all sync requests, except those that include a skipToken that is returned from a previous sync request. In the first response, look for the Preference-Applied: odata.track-changes header to confirm that the resource supports synchronizing before proceeding. (More information about a skipToken in sample second response data for tasks if you are synchronizing tasks, or sample second response data for task folders, if you are synchronizing task folders.)
• You can specify the Prefer: odata.maxpagesize={x} header to indicate the maximum number of tasks (or task folders, depending on which you are synchronizing) that each sync request returns.

Here's a typical round of synchronizing:

1. Make the initial GET request with the mandatory Prefer: odata.track-changes header. The initial response to a sync request always returns a deltaToken. (The second and subsequent GET requests differ from the first GET request by including either a deltaToken or a skipToken received in a previous response.)

2. If the first response returns the Preference-Applied: odata.track-changes header, you can proceed with synchronizing the resource.

   • Make a second GET request. Specify the Prefer: odata.track-changes header and the deltaToken returned from the first GET to determine if there are any additional instances of the resource to sync. The second request will return additional instances, and either a skipToken if there are more instances available, or a deltaToken if the last instance has been synchronized, in which case you can stop.

   • Continue synchronizing by sending a GET call and including a skipToken that's returned from the previous call. Stop when you get a final response that contains an @odata.deltaLink header with a deltaToken again, which indicates the sync is complete.

Take a look at the syntax for the initial and subsequent calls in a round of sync.

To synchronize tasks in a task folder

Initial request:

GET https://outlook.office.com/api/v2.0/me/TaskFolders('{folder_id}')/Tasks

Second request, or first request of a subsequent round:

GET https://outlook.office.com/api/v2.0/me/TaskFolders('{folder_id}')/Tasks/?$deltatoken={delta_token}

Third or subsequent request in the same round; stop when you get a response that contains an @odata.deltaLink header with a deltaToken again:

GET https://outlook.office.com/api/v2.0/me/TaskFolders('{folder_id}')/Tasks/?$skiptoken={skip_token}

To synchronize task folders in a mailbox

Initial request:

GET https://outlook.office.com/api/v2.0/me/TaskFolders

Second request, or first request of a subsequent round:

GET https://outlook.office.com/api/v2.0/me/TaskFolders/?$deltatoken={delta_token}

Third or subsequent request in the same round; stop when you get a response that contains an @odata.deltaLink header with a deltaToken again:

GET https://outlook.office.com/api/v2.0/me/TaskFolders/?$skiptoken={skip_token}

Parameters

Parameter	Type	Description
Header parameters
Prefer	odata.track-changes	Indicates that the request is a synchronization request. Required for the first 2 GET requests in a round.
Prefer	odata.maxpagesize	Sets the number of messages to be returned in each response. Optional.
URL parameters
deltaToken	string	The deltaToken string returned as part of the value for @odata.deltaLink in the previous sync response.
skipToken	string	The skipToken string returned as part of the value for @odata.nextLink in the previous sync response.

Note

• When specifying Prefer: odata.track-changes in the initial request, if the response supports sync, the response would include Preference-applied: odata.track-changes in the header.
• If you attempt to sync a resource that isn't supported, or if this is not the initial sync request, you will not see the Preference-applied header in the response.
• For better response time, use the $select query parameter to get only the properties useful to your scenario.
• You cannot use the $filter, $orderby, $search, and $top query parameters.

Response body

• If synchronizing tasks: the requested Task objects in a collection.

• If synchronizing task folders: the requested TaskFolder objects in a collection.

The number of objects depends on the value set in the Prefer: odata.maxpagesize request header.

Example

The following shows two sets of examples:

• Synchronize tasks in a task folder
• Synchronize task folders.

Each example shows the initial and second sync requests.

• Each request specifies Prefer: odata.maxpagesize=1 to return only one object (task or task folder, respectively) at a time.
• The initial response returns one sync'd object, a deltaLink and deltaToken.
• The second request uses that deltatoken. The second response returns one sync'd object, a nextLink and skipToken.

Iterate through the sync process and use in the next GET call the skipToken returned from the previous sync request until you get a sync response that contains a deltaLink and deltaToken as below:

"@odata.deltaLink": “https://outlook.office.com/api/v2.0/me/TaskFolders('AQMkAGMw80AAAIBEgAAAA==')/Tasks/?%24deltaToken=294a8f04cc0345c5ae093d484629e186”

When this happens, this round of sync is complete. Save the deltaToken for the next round of sync.

Sample initial request (synchronize tasks)

	GET https://outlook.office.com/api/v2.0/me/TaskFolders('AQMkAGMwAAAIBEgAAAA==')/Tasks HTTP/1.1
	Prefer: odata.maxpagesize=1
  Prefer: odata.track-changes

Sample initial response data (synchronize tasks)

HTTP/1.1 200 OK
Preference-Applied: odata.track-changes

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#me/TaskFolders('AQMkAGMwAAAIBEgAAAA%3D%3D')/Tasks",
  "value": [
    {
      "@odata.id": "https://outlook.office.com/api/v2.0/Users('47ec4680-f443-4f9c-a3e5-f7660f0aceae@b4ffe6c0-e717-4104-acd1-e9dfe38ff5f9')/Tasks('AAMkAGMwQsKVevNAAAG1VNmAAA=')",
      "@odata.etag": "W/\"3JfzyLwJe0mPNcULClXrzQAABtYBDw==\"",
      "Id": "AAMkAGMwQsKVevNAAAG1VNmAAA=",
      "CreatedDateTime": "2016-02-29T20:51:25.2226052Z",
      "LastModifiedDateTime": "2016-02-29T20:51:25.2538576Z",
      "ChangeKey": "3JfzyLwJe0mPNcULClXrzQAABtYBDw==",
      "Categories": [ ],
      "AssignedTo": null,
      "Body": {
        "ContentType": "Text",
        "Content": ""
      },
      "CompletedDateTime": null,
      "DueDateTime": null,
      "HasAttachments":false,
      "Importance": "Normal",
      "IsReminderOn": false,
      "Owner": "Administrator",
      "ParentFolderId": "AQMkAGMwAAAIBEgAAAA==",
      "Recurrence": null,
      "ReminderDateTime": null,
      "Sensitivity": "Normal",
      "StartDateTime": null,
      "Status": "NotStarted",
      "Subject": "another task"
    }
  ],
  "@odata.deltaLink": "https://outlook.office.com/api/v2.0/me/TaskFolders('AQMkAGMwAAAIBEgAAAA==')/Tasks/?%24deltatoken=175e2e04482e431ea96e89145c212f8c"
}

Sample second request (synchronize tasks)

	GET https://outlook.office.com/api/v2.0/me/TaskFolders('AQMkAGMwAAAIBEgAAAA==')/Tasks/?%24deltatoken=175e2e04482e431ea96e89145c212f8c HTTP/1.1
	Prefer: odata.maxpagesize=1
  Prefer: odata.track-changes

Sample second response data (synchronize tasks)

HTTP/1.1 200 OK

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#me/TaskFolders('AQMkAGMwAAAIBEgAAAA%3D%3D')/Tasks/$delta",
  "value": [
    {
      "@odata.id": "https://outlook.office.com/api/v2.0/Users('47ec4680-f443-4f9c-a3e5-f7660f0aceae@b4ffe6c0-e717-4104-acd1-e9dfe38ff5f9')/Tasks('AAMkAGMwQsKVevNAAAG1VNlAAA=')",
      "@odata.etag": "W/\"3JfzyLwJe0mPNcULClXrzQAABtYBDQ==\"",
      "Id": "AAMkAGMwQsKVevNAAAG1VNlAAA=",
      "CreatedDateTime": "2016-02-29T20:51:02.5955351Z",
      "LastModifiedDateTime": "2016-02-29T20:51:03.9703679Z",
      "ChangeKey": "3JfzyLwJe0mPNcULClXrzQAABtYBDQ==",
      "Categories": [ ],
      "AssignedTo": null,
      "Body": {
        "ContentType": "Text",
        "Content": ""
      },
      "CompletedDateTime": null,
      "DueDateTimeTime": null,
      "HasAttachments":false,
      "Importance": "Normal",
      "IsReminderOn": false,
      "Owner": "Administrator",
      "ParentFolderId": "AQMkAGMwAAAIBEgAAAA==",
      "Recurrence": null,
      "ReminderDateTime": null,
      "Sensitivity": "Normal",
      "StartDateTime": null,
      "Status": "NotStarted",
      "Subject": "another task"
    }
  ],
  "@odata.nextLink": "https://outlook.office.com/api/v2.0/me/TaskFolders('AQMkAGMw80AAAIBEgAAAA==')/Tasks/?%24skipToken=0fbce2031e844a2f9d13d8bee5ebe2c6"
}

Continue synchronizing tasks and use in the next GET call the skiptoken returned in @odata.nextLink of the previous response, until the final response contains an @odata.deltaLink and a deltaToken. Save the deltaToken for the next round of sync.

Sample initial request (synchronize task folders)

	GET https://outlook.office.com/api/v2.0/me/TaskFolders HTTP/1.1
	Prefer: odata.maxpagesize=1
	Prefer: odata.track-changes

Sample initial response data (synchronize task folders)

HTTP/1.1 200 OK
Preference-Applied: odata.track-changes

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#me/TaskFolders",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('5bcd7334-a6c5-4f95-a370-319e077dfe10@e288a0d0-ab74-431b-9699-a3721aabb08f')/TaskFolders('AAMkAGJiAAAAAAESAAA=')",
            "Id": "AAMkAGJiAAAAAAESAAA=",
            "ChangeKey": "PG2a661l00Cy9qH3YxmDfwAAAAAAPA==",
            "Name": "Tasks",
            "IsDefaultFolder":true,
            "ParentGroupKey": "0006f0b7-0000-0000-c000-000000000046"
        }
    ],
    "@odata.deltaLink": "https://outlook.office.com/api/v2.0/me/TaskFolders/?%24deltatoken=OyZKBDxtmuutZdNAsvah92MZg38AAAAAZwkBAAAA"
}

Sample second request (synchronize task folders)

	GET https://outlook.office.com/api/v2.0/me/TaskFolders/?%24deltatoken=OyZKBDxtmuutZdNAsvah92MZg38AAAAAZwkBAAAA HTTP/1.1
	Prefer: odata.maxpagesize=1
	Prefer: odata.track-changes

Sample second response data (synchronize task folders)

HTTP/1.1 200 OK

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#me/TaskFolders/$delta",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('5bcd7334-a6c5-4f95-a370-319e077dfe10@e288a0d0-ab74-431b-9699-a3721aabb08f')/TaskFolders('AAMkAGI5AAAunDbWAAA=')",
            "Id": "AAMkAGI5AAAunDbWAAA=",
            "ChangeKey": "PmebZ1wYAUaTmrKkvU9LIQAALqEkaw==",
            "Name": "Bingo",
            "IsDefaultFolder":false,
            "ParentGroupKey": "db0823f2-93bd-4db6-8038-98bbc5f39a45"
        }
    ],
    "@odata.nextLink": "https://outlook.office.com/api/v2.0/me/TaskFolders/?%24skipToken=x_zCAz5nm2dcGAFGk5qypL1PSyEAAC6cRncCAAAA"
}

Continue synchronizing and use in the next GET call the skiptoken returned in @odata.nextLink of the previous response, until the final response contains an @odata.deltaLink and a deltaToken. In this example, the third request returns a deltaToken and synchronizing is complete for this round.

Sample third request (synchronize task folders)

	GET https://outlook.office.com/api/v2.0/me/TaskFolders/?%24skipToken=x_zCAz5nm2dcGAFGk5qypL1PSyEAAC6cRncCAAAA HTTP/1.1
	Prefer: odata.maxpagesize=1

Sample third response data (synchronize task folders)

HTTP/1.1 200 OK

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#me/TaskFolders/$delta",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('5bcd7334-a6c5-4f95-a370-319e077dfe10@e288a0d0-ab74-431b-9699-a3721aabb08f')/TaskFolders('AAMkAGI5AAAunDbVAAA=')",
            "Id": "AAMkAGI5AAAunDbVAAA=",
            "ChangeKey": "PmebZ1wYAUaTmrKkvU9LIQAALqEkZA==",
            "Name":"Volunteer",
            "IsDefaultFolder":false,
            "ParentGroupKey": "db0823f2-93bd-4db6-8038-98bbc5f39a45"
        }
    ],
    "@odata.deltaLink":"https://outlook.office.com/api/v2.0/me/taskfolders/?%24deltaToken=x_zCBD5nm2dcGAFGk5qypL1PSyEAAC6cRncEAAAA"
}

Get attachments

• Get an attachment collection
• Get an attachment

Get an attachment collection

Minimum required scope

• https://outlook.office.com/tasks.read

Get the attachments from a particular task.

GET https://outlook.office.com/api/v2.0/me/tasks('{task_id}')/attachments

Response type

An attachment collection which can be of the type FileAttachment or ItemAttachment.

Sample request

The following example returns all the attachments of the specified task, which include a file and an event item.

GET https://outlook.office.com/api/v2.0/me/tasks('AAMkADNkN3qGAAA=')/attachments

Sample response

Status code: 200

{
    "@odata.context":"https://outlook.office.com/api/v2.0/$metadata#Me/Tasks('AAMkADNkN3qGAAA%3D')/Attachments",
    "value":[
        {
            "@odata.type":"#Microsoft.OutlookServices.FileAttachment",
            "@odata.id":"https://outlook.office.com/api/v2.0/Users('fdcbcf34-2505-4d07-be5b-0a55b699d157@41a5b830-45ac-4f1b-9bfc-baafa3b7db2e')/Tasks('AAMkADNkN3qGAAA=')/Attachments('AAMkADNkNRT6JOBs=')",
            "Id":"AAMkADNkNRT6JOBs=",
            "LastModifiedDateTime":"2016-11-22T02:24:21Z",
            "Name":"Holiday notice",
            "ContentType":"application/octet-stream",
            "Size":244,
            "IsInline":false,
            "ContentId":null,
            "ContentLocation":null,
            "ContentBytes":"bWFjIGFuZCBjaGVlc2U="
        },
        {
            "@odata.type":"#Microsoft.OutlookServices.ItemAttachment",
            "@odata.id":"https://outlook.office.com/api/v2.0/Users('fdcbcf34-2505-4d07-be5b-0a55b699d157@41a5b830-45ac-4f1b-9bfc-baafa3b7db2e')/Tasks('AAMkADNkNS3qGAAA=')/Attachments('AAMkADNkNJVnQIe9r0=')",
            "Id":"AAMkADNkNJVnQIe9r0=",
            "LastModifiedDateTime":"2016-12-01T22:27:13Z",
            "Name":"Holiday event",
            "ContentType":null,
            "Size":2473,
            "IsInline":false
        }
    ]
}

Get an attachment

Minimum required scope

• https://outlook.office.com/tasks.read

Get an attachment on a particular task.

GET https://outlook.office.com/api/v2.0/me/tasks('{task_id}')/attachments('{attachment_id}')

Response type

The requested file attachment or item attachment.

Sample request (file attachment)

The following example gets a specific attachment on a task, which is a file attachment.

GET https://outlook.office.com/api/v2.0/me/tasks('AAMkADNkN3qGAAA=')/attachments('AAMkADNkNRT6JOBs=')

Sample response

Status code: 200

{
    "@odata.context":"https://outlook.office.com/api/v2.0/$metadata#Me/Tasks('AAMkADNkN3qGAAA%3D')/Attachments/$entity",
    "@odata.type":"#Microsoft.OutlookServices.FileAttachment",
    "@odata.id":"https://outlook.office.com/api/v2.0/Users('fdcbcf34-2505-4d07-be5b-0a55b699d157@41a5b830-45ac-4f1b-9bfc-baafa3b7db2e')/Tasks('AAMkADNkN3qGAAA=')/Attachments('AAMkADNkNRT6JOBs=')",
    "Id":"AAMkADNkNRT6JOBs=",
    "LastModifiedDateTime":"2016-11-22T02:24:21Z",
    "Name":"Holiday notice",
    "ContentType":"application/octet-stream",
    "Size":244,
    "IsInline":false,
    "ContentId":null,
    "ContentLocation":null,
    "ContentBytes":"bWFjIGFuZCBjaGVlc2U="
}

Sample request (item attachment)

The following example gets a specific attachment on a task, which is an event item.

GET https://outlook.office.com/api/v2.0/me/tasks('AAMkADNkNS3qGAAA=')/attachments('AAMkADNkNJVnQIe9r0=')

Sample response

Status code: 200

{
    "@odata.context":"https://outlook.office.com/api/v2.0/$metadata#Me/Tasks('AAMkADNkNS3qGAAA%3D')/Attachments/$entity",
    "@odata.type":"#Microsoft.OutlookServices.ItemAttachment",
    "@odata.id":"https://outlook.office.com/api/v2.0/Users('fdcbcf34-2505-4d07-be5b-0a55b699d157@41a5b830-45ac-4f1b-9bfc-baafa3b7db2e')/Tasks('AAMkADNkNS3qGAAA=')/Attachments('AAMkADNkNJVnQIe9r0=')",
    "Id":"AAMkADNkNJVnQIe9r0=",
    "LastModifiedDateTime":"2016-12-01T22:27:13Z",
    "Name":"Holiday event",
    "ContentType":null,
    "Size":2473,
    "IsInline":false
}

Add attachments

You can add a file, item (message, event or contact), or a link to a file as an attachment to a task.

• Add a file attachment
• Add an item attachment
• Add a reference attachment

Add a file attachment

Minimum required scope

• https://outlook.office.com/tasks.readwrite

Add a file as an attachment to a task.

POST https://outlook.office.com/api/v2.0/me/tasks('{task_id}')/attachments

Required body parameter	Type	Description
@odata.type	string	#Microsoft.OutlookServices.FileAttachment
Name	string	The name of the attachment.
ContentBytes	binary	The content of the file to attach, in base64 encoding.

Response type

The new file attachment.

Sample request

POST https://outlook.office.com/api/v2.0/me/tasks('AAMkADNkN3qGAAA=')/attachments
Content-Type: application/json

{
    "@odata.type": "#Microsoft.OutlookServices.FileAttachment"",
    "Name": "Holiday notice",
    "ContentBytes": "bWFjIGFuZCBjaGVlc2U="
}

Sample response

Status code: 201 Created

{
    "@odata.context":"https://outlook.office.com/api/v2.0/$metadata#Me/Tasks('AAMkADNkN3qGAAA%3D')/Attachments/$entity",
    "@odata.type":"#Microsoft.OutlookServices.FileAttachment",
    "@odata.id":"https://outlook.office.com/api/v2.0/Users('fdcbcf34-2505-4d07-be5b-0a55b699d157@41a5b830-45ac-4f1b-9bfc-baafa3b7db2e')/Tasks('AAMkADNkN3qGAAA=')/Attachments('AAMkADNkNRT6JOBs=')",
    "Id":"AAMkADNkNRT6JOBs=",
    "LastModifiedDateTime":"2016-11-22T02:24:21Z",
    "Name":"Holiday notice",
    "ContentType":"application/octet-stream",
    "Size":244,
    "IsInline":false,
    "ContentId":null,
    "ContentLocation":null,
    "ContentBytes":"bWFjIGFuZCBjaGVlc2U="
}

Add an item attachment

Minimum required scope

• https://outlook.office.com/tasks.readwrite

Add an item (message, event, or contact) as an attachment to a task.

POST https://outlook.office.com/api/v2.0/me/tasks('{task_id}')/attachments

Required body parameter	Type	Description
@odata.type	string	#Microsoft.OutlookServices.ItemAttachment
Name	string	The name of the attachment.
Item	A Message, Event, or Contact entity.	The item to attach.

Response type

The new item attachment.

Sample request

POST https://outlook.office.com/api/v2.0/me/tasks('AAMkADNkN3qGAAA=')/attachments
Content-Type: application/json

{
    "@odata.type": "#Microsoft.OutlookServices.ItemAttachment",
    "Name": "Holiday event",
    "Item": {
        "@odata.type": "Microsoft.OutlookServices.Event",
        "Subject": "Discuss gifts for children",
        "Body": {
            "ContentType": "HTML",
            "Content": "Let's look for funding!"
         },
         "Start": {
             "DateTime": "2016-12-02T18:00:00",
             "TimeZone": "Pacific Standard Time"
          },
          "End": {
             "DateTime": "2016-12-02T19:00:00",
             "TimeZone": "Pacific Standard Time"
           }
    }
}

Sample response

Status code: 201 Created

{
    "@odata.context":"https://outlook.office.com/api/v2.0/$metadata#Me/Tasks('AAMkADNkN3qGAAA%3D')/Attachments/$entity",
    "@odata.type":"#Microsoft.OutlookServices.ItemAttachment",
    "@odata.id":"https://outlook.office.com/api/v2.0/Users('fdcbcf34-2505-4d07-be5b-0a55b699d157@41a5b830-45ac-4f1b-9bfc-baafa3b7db2e')/Tasks('AAMkADNkN23qGAAA=')/Attachments('AAMkADNkN2Jp5JVnQIe9r0=')",
    "Id":"AAMkADNkNJp5JVnQIe9r0=",
    "LastModifiedDateTime":"2016-12-01T22:27:13Z",
    "Name":"Holiday event",
    "ContentType":null,
    "Size":2473,
    "IsInline":false
}

Add a reference attachment

Minimum required scope

• https://outlook.office.com/tasks.readwrite

Add a link to a file as a reference attachment to a task.

POST https://outlook.office.com/api/v2.0/me/tasks('{task_id}')/attachments

Required body parameter	Type	Description
@odata.type	String	#Microsoft.OutlookServices.ReferenceAttachment
Name	String	The display name of the attachment. Required.
SourceUrl	String	URL to get the attachment content. If this is a URL to a folder, then for the folder to be displayed correctly in Outlook or Outlook on the web, set IsFolder to true. Required.

Specify the Name and SourceUrl parameters and any writable reference attachment properties in the request body.

Response type

The reference attachment.

Sample request

The following example adds a reference attachment to an existing task. The attachment is a link to a file on OneDrive for Business.

POST https://outlook.office.com/api/v2.0/me/tasks('AAMkADNkN3qGAAA=')/attachments
Content-Type: application/json

{
    "@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
    "Name": "Hydrangea picture",
    "SourceUrl": "https://contoso-my.sharepoint.com/personal/admin_contoso_onmicrosoft_com/_layouts/15/onedrive.aspx?id=%2Fpersonal%2Fadmin%5Fcontoso%5Fonmicrosoft%5Fcom%2FDocuments%2FHydrangeas%2Ejpg&parent=%2Fpersonal%2Fadmin%5Fcontoso%5Fonmicrosoft%5Fcom%2FDocuments",
    "ProviderType": "oneDriveBusiness",
    "Permission": "Edit",
    "IsFolder": "False"
}

Sample response

Status code: 201 Created

{
    "@odata.context":"https://outlook.office.com/api/v2.0/$metadata#Me/Tasks('AAMkADNkN3qGAAA%3D')/Attachments/$entity",
    "@odata.type":"#Microsoft.OutlookServices.ReferenceAttachment",
    "@odata.id":"https://outlook.office.com/api/v2.0/Users('fdcbcf34-2505-4d07-be5b-0a55b699d157@41a5b830-45ac-4f1b-9bfc-baafa3b7db2e')/Tasks('AAMkADNkN3qGAAA=')/Attachments('AAMkADNkNQG1Lnn5-o=')",
    "Id":"AAMkADNkNQG1Lnn5-o=",
    "LastModifiedDateTime":"2016-11-22T02:32:44Z",
    "Name":"Hydrangea picture",
    "ContentType":null,
    "Size":850,
    "IsInline":true,
    "SourceUrl":"https://contoso-my.sharepoint.com/personal/admin_contoso_onmicrosoft_com/_layouts/15/onedrive.aspx?id=%2Fpersonal%2Fadmin%5Fcontoso%5Fonmicrosoft%5Fcom%2FDocuments%2FHydrangeas%2Ejpg&parent=%2Fpersonal%2Fadmin%5Fcontoso%5Fonmicrosoft%5Fcom%2FDocuments",
    "ProviderType":"OneDriveBusiness",
    "ThumbnailUrl":null,
    "PreviewUrl":null,
    "Permission":"Edit",
    "IsFolder":false
}

Delete attachments

Delete an attachment of a task

Delete an attachment of a task

Minimum required scope

• https://outlook.office.com/tasks.readwrite

Delete the specified attachment of a task. The attachment can be a file attachment or item attachment.

DELETE https://outlook.office.com/api/v2.0/me/tasks('{task_id}')/attachments('{attachment_id}')

Sample request

DELETE https:/outlook.office.com/api/v2.0/me/tasks('AAMkADNkN3qGAAA=')/attachments('AAMkADNkNQG1Lnn5-o=')

Sample response

Status code: 204

Create task folders

Minimum required scope

• https://outlook.office.com/tasks.readwrite

Create a task folder.

You can create a task folder in the default task group (My Tasks) of the user's mailbox:

POST https://outlook.office.com/api/v2.0/me/taskfolders

Or you can create a task folder under a specified task group:

POST https://outlook.office.com/api/v2.0/me/taskgroups('{group_id}')/taskfolders

In the request body, supply a JSON representation of the TaskFolder to create.

Response

Success status code: 201 Created

Response body: The created TaskFolder.

Sample request

The following example creates a task folder called Volunteer in the default task group (My Tasks) of the user's mailbox.

POST https://outlook.office.com/api/v2.0/me/taskfolders
Content-Type: application/json

{
  "Name": "Volunteer"
}

Sample response

Status code: 201

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/TaskFolders/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/TaskFolders('AAMkADIyAAAhrbPWAAA=')",
  "Id": "AAMkADIyAAAhrbPWAAA=",
  "ChangeKey": "hmM7Eb/jgEec8l3+gkJEawAAIbAGig==",
  "IsDefaultFolder": false,
  "Name": "Volunteer",
  "ParentGroupKey": "0006f0b7-0000-0000-c000-000000000046"
}

Sample request

The next example creates a task folder called Cooking in the specified task group.

POST https://outlook.office.com/api/v2.0/me/taskgroups('AAMkADIyAAAhrbe-AAA')/taskfolders
Content-Type: application/json

{
  "Name": "Cooking"
}

Sample response

Status code: 201

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/TaskGroups('AAMkADIyAAAhrbe-AAA%3D')/TaskFolders/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/TaskFolders('AAMkADIyAAAhrbPXAAA=')",
  "Id": "AAMkADIyAAAhrbPXAAA=",
  "ChangeKey": "hmM7Eb/jgEec8l3+gkJEawAAIbAOlA==",
  "IsDefaultFolder": false,
  "Name": "Cooking",
  "ParentGroupKey": "63d640cf-946f-4734-9c29-60dda7b76acb"
}

Get task folders

Minimum required scope

• https://outlook.office.com/tasks.read

Get multiple task folders.

You can get all task folders in the user's mailbox:

GET https://outlook.office.com/api/v2.0/me/taskfolders

Or you can get task folders in a specific task group:

GET https://outlook.office365.com/api/v2.0/me/taskgroups('{group_id}')/taskfolders

Response

Success status code: 200 OK

Response body: A taskfolder collection.

Sample request

The following example gets all the task folders in the user's mailbox.

GET https://outlook.office.com/api/v2.0/me/taskfolders

Sample response

Status code: 200 OK

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/TaskFolders",
  "value": [
    {
      "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/TaskFolders('AAMkADIyAAAAABrJAAA=')",
      "Id": "AAMkADIyAAAAABrJAAA=",
      "ChangeKey": "hmM7Eb/jgEec8l3+gkJEawAAAAAeAA==",
      "IsDefaultFolder": false,
      "Name": "Monthly tasks",
      "ParentGroupKey": "0006f0b7-0000-0000-c000-000000000046"
    },
    {
      "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/TaskFolders('AAMkADIyAAAAAAESAAA=')",
      "Id": "AAMkADIyAAAAAAESAAA=",
      "ChangeKey": "hmM7Eb/jgEec8l3+gkJEawAAAAAAPA==",
      "IsDefaultFolder": true,
      "Name": "Tasks",
      "ParentGroupKey": "0006f0b7-0000-0000-c000-000000000046"
    }
  ]
}

The next example gets all the task folders in the specified task group.

GET https://outlook.office365.com/api/v2.0/me/taskgroups('AAMkADIyAAAhrbe-AAA=')/taskfolders

Sample response

Status code: 200 OK

{
  "@odata.context": "https://outlook.office365.com/api/v2.0/$metadata#Me/TaskGroups('AAMkADIyAAAhrbe-AAA%3D')/TaskFolders",
  "value": [
    {
      "@odata.id": "https://outlook.office365.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/TaskFolders('AAMkADIyAAAhrbPXAAA=')",
      "Id": "AAMkADIyAAAhrbPXAAA=",
      "ChangeKey": "hmM7Eb/jgEec8l3+gkJEawAAIbAOlA==",
      "IsDefaultFolder": false,
      "Name": "Cooking",
      "ParentGroupKey": "63d640cf-946f-4734-9c29-60dda7b76acb"
    }
  ]
}

Update task folders

Minimum required scope

• https://outlook.office.com/tasks.readwrite

Update the writable properties of a task folder.

You cannot change the Name property value of the default task folder, Tasks.

A task folder ID is unique in the user's mailbox.

PATCH https://outlook.office.com/api/v2.0/me/taskfolders('{folder_id}')

In the request body, supply a JSON representation of the writable properties to update in the TaskFolder.

Response

Success status code: 200 OK

Response body: The updated TaskFolder.

Sample request

The following example changes the name of the task folder to Charity work.

PATCH https://outlook.office.com/api/v2.0/me/taskfolders('AAMkADIyAAAhrbPWAAA=')
Content-Type: application/json

{
  "Name": "Charity work"
}

Sample response

Status code: 200 OK

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/TaskFolders/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/TaskFolders('AAMkADIyAAAhrbPWAAA=')",
  "Id": "AAMkADIyAAAhrbPWAAA=",
  "ChangeKey": "hmM7Eb/jgEec8l3+gkJEawAAIbAKfQ==",
  "IsDefaultFolder": false,
  "Name": "Charity work",
  "ParentGroupKey": "0006f0b7-0000-0000-c000-000000000046"
}

Delete task folders

Minimum required scope

• https://outlook.office.com/tasks.readwrite

Delete the specified task folder.

Attempting to delete the default task folder Tasks would return HTTP 400 Bad Request.

DELETE https://outlook.office.com/api/v2.0/me/taskfolders('{folder_id}')

Response

Success status code: 204 No Content

Response body: None.

Sample request

DELETE https://outlook.office365.com/api/v2.0/me/taskfolders('AAMkADIyAAAhrbPXAAA=')

Sample response

Status code: 204

Create task groups

Minimum required scope

• https://outlook.office.com/tasks.readwrite

Create a task group in the user's mailbox.

POST https://outlook.office.com/api/v2.0/me/taskgroups

In the request body, supply a JSON representation of the TaskGroup to create.

Response

Success status code: 201 Created

Response body: The created TaskGroup.

Sample request

POST https://outlook.office.com/api/v2.0/me/taskgroups
Content-Type: application/json

{
  "Name": "Leisure tasks"
}

Sample response

Status code: 201

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/TaskGroups/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/TaskGroups('AAMkADIyAAAhrbe-AAA=')",
  "Id": "AAMkADIyAAAhrbe-AAA=",
  "ChangeKey": "hmM7Eb/jgEec8l3+gkJEawAAIbAGjg==".
  "IsDefaultGroup": false,
  "Name": "Leisure tasks",
  "GroupKey": "63d640cf-946f-4734-9c29-60dda7b76acb"
}

Get task groups

Minimum required scope

• https://outlook.office.com/tasks.readwrite

Get all the task groups in the user's mailbox.

The response always includes the default task group My Tasks, and any other task groups that have been created in the mailbox.

GET https://outlook.office.com/api/v2.0/me/taskgroups

Response

Success status code: 200 OK

Response body: A TaskGroup collection.

Sample request

GET https://outlook.office.com/api/v2.0/me/taskgroups

Sample response

Status code: 200

{
  "@odata.context": "https://outlook.office365.com/api/v2.0/$metadata#Me/TaskGroups",
  "value": [
    {
      "@odata.id": "https://outlook.office365.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/TaskGroups('AAMkADIyAAADJ5pYAAA=')",
      "Id": "AAMkADIyAAADJ5pYAAA=",
      "ChangeKey": "hmM7Eb/jgEec8l3+gkJEawAAInHxLA==",
      "IsDefaultGroup": true,
      "Name": "My Tasks",
      "GroupKey": "0006f0b7-0000-0000-c000-000000000046"
    },
    {
      "@odata.id": "https://outlook.office365.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/TaskGroups('AAMkADIyAAAhrbe-AAA=')",
      "Id": "AAMkADIyAAAhrbe-AAA=",
      "ChangeKey": "hmM7Eb/jgEec8l3+gkJEawAAInHxKw==",
      "IsDefaultGroup": false,
      "Name": "Leisure Tasks",
      "GroupKey": "63d640cf-946f-4734-9c29-60dda7b76acb"
    }
  ]
}

Update task groups

Minimum required scope

• https://outlook.office.com/tasks.readwrite

Update the writable properties of a task group.

PATCH https://outlook.office.com/api/v2.0/me/taskgroups('{group_id}')

In the request body, supply a JSON representation of the writable properties to update in the TaskGroup, such as the Name property.

Response

Success status code: 200 OK

Response body: The updated task.

Sample request

The following example changes the name of a task group to "Personal Tasks". Note that you cannot modify the name of the default task group "My Tasks".

PATCH https://outlook.office.com/api/v2.0/me/taskgroups('AAMkADIyAAAhrbe-AAA=')
Content-Type: application/json

{
  "Name": "Personal Tasks"
}

Sample response

Status code: 200

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/TaskGroups/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/TaskGroups('AAMkADIyAAAhrbe-AAA=')",
  "Id": "AAMkADIyAAAhrbe-AAA=",
  "ChangeKey": "hmM7Eb/jgEec8l3+gkJEawAAIbAGjw==",
  "IsDefaultGroup": false,
  "Name": "Personal Tasks",
  "GroupKey": "63d640cf-946f-4734-9c29-60dda7b76acb"
}

Delete task groups

Minimum required scope

• https://outlook.office.com/tasks.readwrite

Delete the specified task group.

Attempting to delete the default task group My Tasks would return HTTP 400 Bad Request.

DELETE https://outlook.office.com/api/v2.0/me/taskgroups('{group_id}')

Response

Success status code: 204 No Content

Response body: The updated task.

Sample request

DELETE https://outlook.office365.com/api/v2.0/me/taskgroups('AAMkADIyAAAhrbe-AAA=')

Sample response

Status code: 204

Next steps

Whether you're ready to start building an app or just want to learn more, we've got you covered.

• Get started with Mail, Calendar, and Contacts REST APIs.
• Want samples? We've got them.

Or, learn more about using the Office 365 platform:

• Outlook REST API on the Outlook Dev Center
• Overview of developing on the Office 365 platform
• Office 365 app authentication and resource authorization
• Manually register your app with Azure AD so it can access Office 365 APIs
• Use the Outlook REST API
• Mail REST APIs reference
• Calendar REST APIs reference
• Contacts REST APIs reference
• Resource reference for the Mail, Calendar, Contacts, and Task REST APIs