Microsoft To Do API: How to Read and Write Tasks
There is no product called the Microsoft To Do API. To Do is a client on top of Microsoft Graph, and the tasks you see in the app are Graph resources. Once that clicks, everything else follows.
This is what you need to read and write those tasks programmatically, and the things that trip people up on the way.
The endpoints
Two resource types, nested.
Task lists are the containers you see in the sidebar:
GET /me/todo/lists
POST /me/todo/listsTasks live inside a list:
GET /me/todo/lists/{listId}/tasks
POST /me/todo/lists/{listId}/tasks
PATCH /me/todo/lists/{listId}/tasks/{taskId}
DELETE /me/todo/lists/{listId}/tasks/{taskId}Steps, which the app calls subtasks, hang off a task as checklist items:
GET /me/todo/lists/{listId}/tasks/{taskId}/checklistItems
POST /me/todo/lists/{listId}/tasks/{taskId}/checklistItemsEverything is under the Graph base URL and versioned, so a real call looks like https://graph.microsoft.com/v1.0/me/todo/lists.
Permissions
The scopes you’ll ask for:
Tasks.ReadWritefor the signed-in user’s own tasks, which is the normal caseTasks.Readif you only need to readTasks.ReadWrite.Sharedto reach lists shared with the user
These are delegated permissions, meaning they act as a signed-in user. That’s the important constraint: To Do is a personal task store, so there is no clean application-permission path for a daemon to write into arbitrary users’ task lists the way there is for mail or calendar. If your design assumed a background service writing tasks for everyone in the tenant, check this early rather than late.
Registration is the standard route. Create an app registration in Microsoft Entra ID, add the delegated Graph permissions, and use the normal OAuth authorization code flow. Personal Microsoft accounts and work or school accounts are both supported, which is not true of every Graph workload.
The data model, and where it surprises people
A task carries title, status, importance, isReminderOn, body, and a set of date fields.
Dates are objects, not strings. dueDateTime and reminderDateTime are dateTimeTimeZone values with a dateTime and a separate timeZone. Sending a bare ISO string is the most common first failure.
Due dates are dates pretending to be timestamps. The app treats a due date as a day, but the API models it with a time component. Round-tripping a due date through a different time zone is how tasks quietly land a day early or late. Set the time zone explicitly and stop assuming UTC.
Status is an enum, not a boolean. It’s notStarted, inProgress, completed, waitingOnOthers, or deferred. Only two of those are reachable from the app’s checkbox, so data written by the API can be in a state the UI can’t express.
Recurrence is a pattern object, mirroring the calendar recurrence shape. Completing a recurring task generates the next occurrence server-side, so you should not create the next one yourself.
Smart lists are not lists. My Day, Important, Planned, and Flagged Email are views computed from task properties, so they don’t appear in GET /me/todo/lists as containers you can write into. To put something in Important you set importance, and to affect Planned you set a due date.
Deltas and change notifications
For sync rather than one-off writes, use delta queries on the tasks collection so you pull only what changed since your last token rather than re-reading every list.
Graph change notifications, the subscription mechanism, do support To Do task resources, so you can be told about changes rather than polling. Subscriptions expire and must be renewed on a schedule, which is the part people forget until their integration silently goes quiet a few days after launch.
The Outlook overlap
Tasks, flagged emails, and Outlook tasks share a store, so a task written through the To Do endpoints can surface in Outlook, and an email flagged in Outlook appears in the Flagged Email view.
There is also an older /me/outlook/tasks surface associated with the legacy Outlook Tasks model. New work belongs on the /me/todo/ endpoints. If you find a tutorial using the Outlook tasks path, check its date before following it.
If you’d rather not write the integration
Building against Graph is reasonable when the logic is yours. It’s a poor use of a week when what you actually want is “when this happens, make a task.”
Carly covers that shape without the app registration. Its workflows fire on real events, such as an email arriving or a meeting ending, and an AI agent can read the content and decide what the task should say rather than pattern-matching a subject line. That judgment step is the part that’s genuinely hard to write yourself, because the rule you’d need is “is this a commitment I made?” rather than a keyword.
To be precise about what’s available today: Carly has no native Microsoft To Do connector. To Do connects through Graph with your own credentials, which you paste on the integrations page, and Composio is a third route in. Workflow steps are free, and AI agents start at $35/month. If a native connector would change the calculation for you, that’s worth raising on a call with the team.
FAQ
Does Microsoft To Do have its own API?
No. To Do tasks are exposed through Microsoft Graph, under the /me/todo/ endpoints. There is no separate To Do API product or key.
What permission do I need to write Microsoft To Do tasks?
Tasks.ReadWrite as a delegated permission, or Tasks.ReadWrite.Shared if you need lists shared with the user. These act on behalf of a signed-in user rather than as a background service.
Can a background service write tasks for any user in my tenant?
Not cleanly. The To Do task endpoints are built around delegated permissions, so a daemon writing into arbitrary users’ personal task lists is not a supported pattern the way it is for mail or calendar. Verify this against the current Graph permissions reference before designing around it.
Can I use the API to add a task to My Day?
Not directly. My Day is a computed view rather than a list you can write into. You influence the smart lists by setting task properties such as importance and dueDateTime.
Do personal Microsoft accounts work with the To Do endpoints?
Yes. Both personal accounts and work or school accounts are supported, which is not the case for every Microsoft Graph workload.
Ready to automate your busywork?
Carly schedules, researches, and briefs you—so you can focus on what matters.
See what people say
"Before Carly, I relied on a Calendly link, but the whole process felt impersonal and not very professional. Carly changed that by handling all the back-and-forth, so I'm no longer stuck in endless email threads trying to line up schedules.
Now Carly reaches out to candidates, shares my real-time availability, lets them pick a slot, then sends a Zoom link and drops it straight into my calendar. She sends reminders to both of us before each call, which has significantly reduced no-shows and last-minute confusion.
On top of scheduling, Carly acts like a full executive assistant, sending me my schedule the night before so I can prepare for each call. It reminds me of the old x.ai assistant, but Carly is noticeably smarter, faster, and better suited to my healthcare recruitment business."
