[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 tonull
.
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
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
Minimum required scope
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
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
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
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
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
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 askipToken
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 askipToken
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:
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.)
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 includePreference-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:
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
anddeltaToken
. - The second request uses that
deltatoken
. The second response returns one sync'd object, anextLink
andskipToken
.
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
Minimum required scope
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
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
Minimum required scope
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
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
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
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
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
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
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
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
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
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
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
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.
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