Microsoft To Do

1. Overview

Microsoft To Do is a cloud-based task management application that allows users to manage their tasks from a smartphone, tablet, and computer. It is part of the Microsoft 365 suite of products.

With the GoInsight Microsoft To Do node, you can seamlessly integrate task management into your automated workflows. This allows you to programmatically manage your task lists, individual tasks, and associated resources. Key capabilities include:

• List Management: Create, retrieve, update, and delete task lists.
• Task Management: Add new tasks to specific lists, retrieve existing tasks, update their properties (like status or due date), and delete them.
• Linked Resource Management: Attach, view, update, and remove external resources (like links to documents or emails) associated with a task.

2. Prerequisites

Before using this node, you need to have a valid Microsoft To Do account, which is typically included with a Microsoft 365 subscription or available as a free standalone service. You may need appropriate permissions within your Microsoft organization to create and manage API credentials.

3. Credentials

For a detailed guide on how to obtain and configure your credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on the following resources: List, Task, and Linked Resource.

Operation Details

Create a List

Creates a new task list in Microsoft To Do. The returned ListId is required for subsequent task operations (Create Task, Get Tasks, Update Task, etc.). Microsoft To Do allows duplicate list names.

Input Parameters:

• DisplayName: The name/title of the task list (e.g., 'Work Tasks', 'Shopping List'). This is what you'll see in the Microsoft To Do app.

Output:

• ListId (string): The unique identifier of the created task list. Use this ID for subsequent task operations (Create Task, Get Tasks, etc.). Empty string if creation failed.
• DisplayName (string): The display name of the task list. Empty string if creation failed.
• IsOwner (bool): Indicates whether the user is the owner of the list. Always true for newly created lists. False if creation failed.
• IsShared (bool): Indicates whether the list is shared with other users. False for newly created lists (sharing is configured separately). False if creation failed.
• WellknownListName (string): Special list type identifier. Possible values: empty string (regular custom list, most common), 'defaultList' (user's default Tasks list), 'flaggedEmails' (list for flagged emails from Outlook), 'unknownFutureValue' (reserved). For newly created lists, this is usually empty. Empty string if creation failed.
• OriginalStatusCode (number): The original HTTP status code from Microsoft Graph API. 0=Request did not reach upstream, 201=Created successfully, 400=Bad request, 401=Unauthorized, 429=Rate limited.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error description if failed, empty if successful. For rate limit (429), includes retry delay.

Get Lists

Retrieves all task lists from Microsoft To Do for the authenticated user (supports batch retrieval).

Options:

• Top: Maximum number of lists to return. Default 50, max 999. Most users have fewer than 50 lists.
• Skip: Number of lists to skip for pagination. Example: Skip=50 skips the first 50 and returns from 51st.

Output:

• Lists (object-array): Array of task list objects. Each list contains: id (string, unique identifier for use in other actions), displayName (string, list name), isOwner (boolean, whether current user owns this list), isShared (boolean, whether list is shared), wellknownListName (string: defaultList, flaggedEmails, or none).
• Count (number): Number of lists returned in this response (not total count across all pages).
• HasMore (boolean): Whether there are more lists available. true means you can call again with increased Skip value to get more data.
• NextLink (string): The API URL for the next page of results (if HasMore is true). Empty string if no more data.
• OriginalStatusCode (number): The original HTTP status code from Microsoft Graph API. 0=Request did not reach upstream, 200=Success, 401=Unauthorized, 429=Rate limited.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error description if failed, empty if successful. For rate limit (429), includes retry delay.

Update a List

Updates the display name of a specified task list in Microsoft To Do. This is a PATCH operation - only the displayName field will be updated, other properties (isShared, etc.) remain unchanged.

Input Parameters:

• ListId: The unique identifier of the task list to update. Obtain from Get Lists action.
• DisplayName: The new display name for the task list. This is the only updatable property via this action.

Output:

• ListId (string): The unique identifier of the updated task list. Empty string if update failed.
• DisplayName (string): The updated display name of the task list. Empty string if update failed.
• IsOwner (bool): Indicates whether the user is the owner of the list. False if update failed.
• IsShared (bool): Indicates whether the list is shared with other users. False if update failed.
• WellknownListName (string): System preset list type identifier. Values: 'none' (user-created custom list), 'defaultList' (default Tasks list), 'flaggedEmails' (flagged emails list). Empty string if update failed.
• OriginalStatusCode (number): The original HTTP status code from Microsoft Graph API. 0=Request did not reach upstream, 200=Updated successfully, 400=Bad request, 401=Unauthorized, 403=Forbidden, 404=List not found, 429=Rate limited.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error description if failed, empty if successful. For rate limit (429), includes retry delay.

Delete a List

Permanently deletes a task list from Microsoft To Do. WARNING: This action cannot be undone - the list and ALL tasks within it will be permanently removed. The default 'Tasks' list cannot be deleted.

Input Parameters:

• ListId: The unique identifier of the task list to delete. Obtain from Get Lists action. Note: The default 'Tasks' list (wellknownListName='defaultList') cannot be deleted.

Output:

• Deleted (bool): Indicates whether the task list was successfully deleted. true if OriginalStatusCode is 204, false otherwise.
• OriginalStatusCode (number): The original HTTP status code from Microsoft Graph API. 0=Request did not reach upstream, 204=Deleted successfully, 400=Bad request, 401=Unauthorized, 403=Forbidden (cannot delete default list), 404=List not found, 429=Rate limited.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error description if failed, empty if successful. For rate limit (429), includes retry delay.

Create a Task

Creates a new task in a specified task list in Microsoft To Do. Use cases: convert emails to tasks, sync tasks from CRM systems, create follow-up reminders. WARNING: No duplicate checking. If retried, duplicates may be created. Workaround: Add unique identifier to Title, e.g., 'Report - 2025-01-15T10:30:00' or 'Order #12345'.

Input Parameters:

• TaskListId: The unique identifier (GUID string, e.g., AAMkADIyAAAhrbPWAAA=) of the task list where the task will be created. Obtain from Get Task Lists action (microsoft_to_do_get_lists), the ID is in the 'id' field of the list object.
• Title: The title of the task. Consider adding a unique identifier (e.g., timestamp) to avoid duplicates on retry.

Options:

• Body: Detailed content or notes for the task.
• Status: Task status based on work stage: 'notStarted' (default, in backlog), 'inProgress' (actively working), 'completed' (finished), 'waitingOnOthers' (blocked by external dependency, e.g., waiting for approval), 'deferred' (postponed, not urgent now).
• Importance: Task priority level: 'low' (nice-to-have, can delay), 'normal' (default, routine work), 'high' (urgent, needs immediate attention). Tip: high + notStarted = top priority in backlog.
• DueDateTime: Due date and time for the task. Format: YYYY-MM-DDTHH:MM:SS (the T separates date and time). Example: 2025-12-31T17:00:00 means December 31, 2025 at 5:00 PM.
• DueTimeZone: Time zone for the due date. Common values: UTC (default), Pacific Standard Time (US West), Eastern Standard Time (US East), China Standard Time (Beijing). Search Windows time zone names for your region.

Output:

• TaskId (string): The unique identifier of the created task. Use this ID to update, delete, or get the task. Empty string if creation failed.
• Title (string): The title of the task. Empty string if creation failed.
• Body (object): Task body content object. Structure: content (string, task notes), contentType (string, always 'text' - Microsoft To Do does not support HTML). Example: {"content": "Meeting notes", "contentType": "text"}. Empty object {} if no body provided.
• Status (string): The status of the task. Possible values: notStarted, inProgress, completed, waitingOnOthers, deferred. Empty string if creation failed.
• Importance (string): The priority of the task. Possible values: low, normal, high. Empty string if creation failed.
• DueDateTime (object): Due date object. Structure: dateTime (string, format YYYY-MM-DDTHH:MM:SS without timezone), timeZone (string, Windows timezone name like 'Pacific Standard Time' or 'UTC'). Example: {"dateTime": "2025-12-31T17:00:00", "timeZone": "UTC"}. Empty object {} if no due date.
• CreatedDateTime (string): The creation timestamp of the task in ISO 8601 format. Empty string if creation failed.
• LastModifiedDateTime (string): The last modification timestamp of the task in ISO 8601 format. Empty string if creation failed.
• OriginalStatusCode (number): The original HTTP status code from Microsoft Graph API. 0=Request did not reach upstream, 201=Created, 400=Bad request, 401=Unauthorized, 404=Task list not found, 429=Rate limited.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error description if the operation failed, empty string if successful. For rate limit (429), includes retry delay.

Get Tasks

Retrieves all tasks from a specified task list in Microsoft To Do (supports batch retrieval).

Input Parameters:

• TaskListId: The unique identifier of the task list to retrieve tasks from. Obtain this ID by calling Get Many Task Lists action.

Options:

• Top: Maximum number of tasks to return. Default 50, max 999. Set based on your needs to avoid retrieving too much data at once.
• Skip: Number of tasks to skip for pagination. Example: Skip=50 skips the first 50 tasks and returns from the 51st.

Output:

• Tasks (object-array): Array of task objects. Each task contains: id (string, unique identifier), title (string), status (notStarted/inProgress/completed/waitingOnOthers/deferred), importance (low/normal/high), createdDateTime (ISO 8601), lastModifiedDateTime (ISO 8601), body.content (string, may be empty), dueDateTime.dateTime (ISO 8601, may be null).
• Count (number): The number of tasks returned in this response (not total count).
• HasMore (boolean): Whether there are more tasks available. true means you can call again with increased Skip value to get more data.
• NextLink (string): The API URL for the next page of results (if HasMore is true). Empty string if no more data.
• OriginalStatusCode (number): The original HTTP status code from Microsoft Graph API. 0=Request did not reach upstream, 200=Success, 400=Bad request, 401=Unauthorized, 404=Task list not found, 429=Rate limited.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error description if failed, empty if successful. For rate limit (429), includes retry delay.

Update a Task

Updates the properties of a specified task in Microsoft To Do. This is a PATCH operation - only provided fields will be updated, other properties remain unchanged. At least one field to update must be provided.

Input Parameters:

• TaskListId: The unique identifier of the task list containing the task. Obtain from Get Lists action.
• TaskId: The unique identifier of the task to update. Obtain from Get Tasks action.

Options:

• Title: The new title for the task.
• Body: The new detailed content/notes for the task.
• Status: The new status for the task. Values: 'notStarted' (default, not begun), 'inProgress' (actively working), 'completed' (finished, auto-sets completion time), 'waitingOnOthers' (blocked by external dependency), 'deferred' (postponed).
• Importance: The new priority for the task. Values: 'low' (can be delayed), 'normal' (default priority), 'high' (urgent, needs immediate attention).
• DueDateTime: The new due date and time in format YYYY-MM-DDTHH:MM:SS (local time, not UTC). Must be used with DueTimeZone. Example: '2025-02-15T17:00:00' for Feb 15, 2025 at 5:00 PM.
• DueTimeZone: Time zone for the due date using Windows timezone identifier. Common values: 'Pacific Standard Time' (UTC-8), 'Eastern Standard Time' (UTC-5), 'China Standard Time' (UTC+8), 'UTC'. Defaults to UTC if not specified.

Output:

• TaskId (string): The unique identifier of the updated task. Empty string if update failed.
• Title (string): The updated title of the task. Empty string if update failed.
• Status (string): The updated status of the task. Empty string if update failed.
• Importance (string): The updated priority of the task. Empty string if update failed.
• LastModifiedDateTime (string): The last modification timestamp of the task in ISO 8601 format with UTC timezone (e.g., '2025-01-15T14:30:00Z'). The trailing 'Z' indicates UTC. Empty string if update failed.
• OriginalStatusCode (number): The original HTTP status code from Microsoft Graph API. 0=Request did not reach upstream, 200=Updated successfully, 400=Bad request, 401=Unauthorized, 403=Forbidden, 404=Task or list not found, 429=Rate limited.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error description if failed, empty if successful. For rate limit (429), includes retry delay.

Delete a Task

Permanently deletes a task from Microsoft To Do. WARNING: This action cannot be undone - the task and all its linked resources will be permanently removed.

Input Parameters:

• TaskListId: The unique identifier of the task list containing the task. Obtain from Get Lists action.
• TaskId: The unique identifier of the task to delete. Obtain from Get Tasks action.

Output:

• Deleted (bool): Indicates whether the task was successfully deleted. true if OriginalStatusCode is 204, false otherwise.
• OriginalStatusCode (number): The original HTTP status code from Microsoft Graph API. 0=Request did not reach upstream, 204=Deleted successfully, 400=Bad request, 401=Unauthorized, 403=Forbidden, 404=Task or list not found, 429=Rate limited.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error description if failed, empty if successful. For rate limit (429), includes retry delay.

Create a Linked Resource

Creates a linked resource object to associate a specified Microsoft To Do task with an item in a partner application (e.g., linking a task to an email or document).

Input Parameters:

• TaskListId: The unique identifier of the task list containing the task. Obtain this ID by calling Get Many Task Lists or Search Task Lists action.
• TaskId: The unique identifier of the task to which the linked resource will be added. Obtain this ID by calling Get Many Tasks or Search Tasks action within the specified task list.
• WebUrl: The URL that links to the external resource (e.g., a document, email, or web page). When users click this link in Microsoft To Do, they will be redirected to the partner application. Must be a valid HTTP/HTTPS URL.
• ApplicationName: The partner application name. Displayed in To Do to indicate link source. Common scenarios: 'Outlook' (emails), 'SharePoint' (documents), 'Teams' (messages), 'OneNote' (notes), or your custom app name.
• DisplayName: The title or display name of the linked entity that will be shown to users in Microsoft To Do.
• ExternalId: The unique identifier of the linked object in the partner application's system. This ID maintains the association between the To Do task and the external resource. For example, if linking to an email, use the email's message ID; if linking to a document, use the document ID.

Output:

• LinkedResourceId (string): The unique identifier of the created linked resource. Use this ID to update or delete the linked resource via Update Linked Resource or Delete Linked Resource actions. Empty string if creation failed.
• WebUrl (string): The URL of the linked entity, same as the input WebUrl. Users can click this URL in Microsoft To Do to open the external resource. Empty string if creation failed.
• ApplicationName (string): The name of the partner application, same as the input ApplicationName. Displayed in Microsoft To Do to indicate the link source. Empty string if creation failed.
• DisplayName (string): The display name of the linked resource as shown in Microsoft To Do. Empty string if creation failed.
• ExternalId (string): The external ID in the partner application's system, same as the input ExternalId. Empty string if creation failed.
• OriginalStatusCode (number): Original HTTP status code from Microsoft Graph API. 0=Not reached, 201=Created, 400=Bad request, 401=Unauthorized, 404=Not found, 429=Rate limited.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Error description if failed, empty if successful. For rate limit (429), includes retry delay.

Get Linked Resources

Retrieves all linked resources (documents, links, attachments) associated with a Microsoft To Do task. Returns all resources in a single call without pagination. If the task has no linked resources, returns an empty array (not an error).

Input Parameters:

• TaskListId: The unique identifier of the task list containing the task. Obtain from Get Lists action.
• TaskId: The unique identifier of the task whose linked resources to retrieve. Obtain from Get Tasks action.

Output:

• LinkedResources (object-array): Array of linked resource objects representing external documents, links, or app content associated with the task. Each object contains: id (unique identifier), webUrl (resource URL), applicationName (source app like Word/SharePoint), displayName (resource title), externalId (external system ID). Empty array if failed or no resources.
• Count (number): The number of linked resources retrieved. 0 if failed or no resources.
• OriginalStatusCode (number): The original HTTP status code from Microsoft Graph API. 0=Request did not reach upstream, 200=Success, 400=Bad request, 401=Unauthorized, 404=Task or list not found, 429=Rate limited.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error description if failed, empty if successful. For rate limit (429), includes retry delay.

Update a Linked Resource

Updates the properties of a linked resource object associated with a specified Microsoft To Do task. Uses PATCH semantics - only provided non-empty fields are updated; omitted fields retain their current values. At least one of WebUrl/ApplicationName/DisplayName/ExternalId must be provided.

Input Parameters:

• TaskListId: The unique identifier of the task list containing the task. Obtain from Get Many Task Lists action.
• TaskId: The unique identifier of the task containing the linked resource. Obtain from Get Tasks action.
• LinkedResourceId: The unique identifier of the linked resource to update. Obtain from Get Linked Resources action or from Create Linked Resource response.

Options:

• WebUrl: The updated URL linking to the external resource. At least one of WebUrl/ApplicationName/DisplayName/ExternalId must be provided. Example: https://example.com/updated-doc
• ApplicationName: The updated partner application name. At least one of WebUrl/ApplicationName/DisplayName/ExternalId must be provided.
• DisplayName: The updated display title shown in Microsoft To Do. At least one of WebUrl/ApplicationName/DisplayName/ExternalId must be provided.
• ExternalId: The updated external identifier in the partner system. At least one of WebUrl/ApplicationName/DisplayName/ExternalId must be provided.

Output:

• LinkedResourceId (string): The unique identifier of the updated linked resource. Empty string if update failed.
• WebUrl (string): The updated URL of the linked entity. Empty string if update failed.
• ApplicationName (string): The updated application name. Empty string if update failed.
• DisplayName (string): The updated display name. Empty string if update failed.
• ExternalId (string): The updated external ID. Empty string if update failed.
• OriginalStatusCode (number): The original HTTP status code from Microsoft Graph API. 0=Request did not reach upstream, 200=Success, 400=Bad request, 401=Unauthorized, 404=Not found, 429=Rate limited.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error description if failed, empty if successful. For rate limit (429), includes retry delay.

Delete a Linked Resource

Deletes a linked resource (attachment/link) from a specified Microsoft To Do task. WARNING: This operation is permanent and cannot be undone. The linked resource will be removed immediately, but the task itself and other linked resources will remain unchanged.

Input Parameters:

• TaskListId: The unique identifier of the task list containing the task. Obtain from Get Lists action. If the list does not exist, the API will return a 404 error.
• TaskId: The unique identifier of the task containing the linked resource. Obtain from Get Tasks action. The task must exist within the specified TaskListId.
• LinkedResourceId: The unique identifier of the linked resource to delete. Obtain from Get Linked Resources action or Create Linked Resource response. If already deleted, the API will return a 404 error.

Output:

• Deleted (bool): Indicates whether the linked resource was successfully deleted. true if OriginalStatusCode is 204, false otherwise.
• OriginalStatusCode (number): The original HTTP status code from Microsoft Graph API. 0=Request did not reach upstream, 204=Deleted successfully, 400=Bad request, 401=Unauthorized, 403=Forbidden, 404=Not found, 429=Rate limited.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Error description if failed, empty if successful. For rate limit (429), includes retry delay.

5. Example Usage

This section will guide you through creating a simple workflow that adds a new task to a specified list in your Microsoft To Do account.

The workflow will consist of a Start node, a Microsoft To Do node configured to "Create a Task", and an Answer node to display the result.

Step-by-Step Guide

1. Add the Tool Node:
   • In the workflow canvas, click the + button to add a new node.
   • Select the "Tools" tab in the pop-up panel.
   • Find and select "Microsoft To Do" from the list of tools.
   • From the list of supported operations for Microsoft To Do, click on "Create a Task". This will add the node to your canvas.
2. Configure the Node:
   • Click on the newly added "Create a Task" node to open its configuration panel on the right.
   • Credentials: In the "Credentials" field, click the dropdown menu and select your pre-configured Microsoft To Do credential.
   • Parameters: Fill in the required input parameters for the task.
   • TaskListId: Enter the unique ID of the task list where you want to create the new task. You can find this ID by first running a workflow with the "Get Lists" operation and copying the ListId from its output.
   • Title: Enter a title for your new task, for example, Follow up on Q3 report.
   • You can also fill in optional parameters like Importance or DueDateTime as needed.
3. Run and Validate:
   • Once all required parameters are correctly filled, any error indicators on the workflow canvas will disappear.
   • Click the "Test Run" button in the top-right corner of the canvas to execute the workflow.
   • After a successful execution, you can click the log icon in the top-right corner to view the detailed inputs and outputs of the node, confirming that the task was created and a TaskId was returned.

After completing these steps, your workflow is fully configured. When run, it will automatically create a new task in the specified Microsoft To Do list.

6. FAQs

Q: How do I find my TaskListId?

A: The easiest way to find a TaskListId is to use the "Get Lists" operation in a separate workflow. Run it once, and the output will contain an array of all your task lists, each with its DisplayName and ListId. You can then copy the required ListId for use in other operations.

Q: Why am I getting a 401 Unauthorized or 403 Forbidden error?

A: These errors typically indicate a problem with your credentials or permissions. Please check the following:

• Ensure your credentials are correct and have not expired.
• When you authorized the application in your Microsoft account, make sure you granted all the necessary permissions (scopes) required for managing tasks, such as Tasks.ReadWrite.

Q: What format should the DueDateTime parameter be in?

A: The DueDateTime parameter expects a string in the ISO 8601 format. The recommended format is YYYY-MM-DDTHH:MM:SS. For example, 2024-12-31T17:00:00.

7. Official Documentation

For more in-depth information about the Microsoft To Do API and its capabilities, please refer to the official Microsoft Graph API documentation:

Microsoft To Do API Overview