Use the Planner REST API

Article
01/04/2024

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

You can use the Planner API in Microsoft Graph to create tasks and assign them to users in a group in Microsoft 365.

Before you get started with the Planner API, it's helpful to understand how the main objects relate to each other and to Microsoft 365 groups.

Plan containers

In Microsoft Planner, plans are always contained in another resource. The containing resource, plannerPlanContainer, determines the authorization rules of the plan and all the tasks in it, and the lifecycle of the plan. You can create a plan in a container of one of the following types: driveItem, Microsoft 365 group, Planner project, roster, or user.

The most common type of container is a group.

Container type: Microsoft 365 groups

Plans are commonly contained in groups in the Planner API.

Group members are able to create, edit, resolve, and delete tasks in the plan. Group members can also change some plan-level properties, such as the name of the plan or label names. Additionally, when the group is deleted, all the plans in the group are automatically deleted. Conversely if a group is restored, then all the plans are automatically restored.

To get the plans owned by a group, make the following HTTP request.

GET /groups/{group-id}/planner/plans

When you create a new plan, set the container property on a plan object to make a group its container. Plans must be contained by a supported resource.

Note: The user who is creating the plan must be a member of the group that will contain the plan. When you create a new group by using Create group, you are not added to the group as a member. After the group is created, add yourself as a member by using group post members.

Container type: User

The user container type supports personal plans, where the user is the only user tracking their individual tasks. This provides the flexibility for users to share or collaborate on their personal plans. Plans that are created for a single user are automatically deleted when the user is deleted.

To create a new plan in a user's container, set the container property on a plan object with type being user.

{
    "container": {
        "id": "00000000-0000-0000-0000-000000000000",
        "type": "user"
    }
}

Alternatively, you can specify the URL for a user.

{
    "container": {
        "url": "https://graph.microsoft.com/beta/users/me"
    }
}

Users can upgrade their personal plans into group-based plans by moving the plan from the user container to a group container, changing the type of the container for the plan from user to group.

Plans

Plans are the containers of tasks. To create a task in a plan, set the planId property on the task object to the ID of the plan while creating the task. Tasks currently can't be created without plans. To retrieve the tasks in a plan, make the following HTTP request.

GET /planner/plans/{plan-id}/tasks

Tasks

Each task can be assigned to a user by adding an assignment in the assignments property on the task object. The ID of the user to assign the task is the name of the open property on assignments, and the orderHint property on the assignment must be specified.

Task and plan details

Planner resources are arranged into basic objects and detail objects. Basic objects provide access to common properties of the resources, suitable for list views, while the detail objects provide access to large properties of the resources suitable for drill-down views.

Visualization

Aside from task and plan data, the Planner API also provides resources for creating a common visualization of data across clients. Several types of visualization data are available for tasks, as listed in the following table.

Tasks are shown as	Tasks are ordered with information from
Flat list (tasks in a plan)	orderHint property on tasks
Flat list (tasks assigned to a user)	assigneePriority property on tasks
Board view with columns for assignees (assigned to task board)	assignedToTaskBoardTaskFormat object
Board view with columns for progress of the task towards completion (progress task board)	progressTaskBoardTaskFormat object
Board view with custom columns of tasks (bucket task board):	bucketTaskBoardTaskFormat object

The custom columns in the bucket task board are represented by bucket objects, and their order by orderHint property on the object.

The ordering principles are described in Planner order hints.

Track changes using delta query

Planner's delta query supports querying objects that the user is subscribed to.

Users are subscribed to the following objects.

Planner resource type	Subscribed instances
tasks	Created by the user Assigned to the user Belong to a plan that the user owns Contained in a plan shared with the user through the plan's sharedWith collection
plans	Shared with the user through the plan's sharedWith collection
buckets	Contained in a plan shared with the user through the plan's sharedWith collection

Populate the object cache for delta queries

If you want to use the Planner delta query API, maintain a local cache of objects that the user is interested in observing in order to apply the changes from the delta response feed.

The delta payload objects that the Planner delta query can currently return are of the following types:

Use the corresponding GET methods on the resource to obtain the initial state of objects to be populated into the local cache.

Differentiating between object creation and object modification

In certain scenarios, the caller might want to distinguish between object creation and object modification within Planner's delta query feed.

These guidelines can be used to infer object creation:

The createdBy property appears on newly created objects.
A newly created plannerTask object is followed by its corresponding plannerTaskDetails object.
A newly created plannerPlan object is followed by its corresponding plannerPlanDetails object.

Usage

The caller is expected to have a cache containing subscribed objects. For details about how to fill the local cache of subscribed objects, see Populate the object cache for delta queries.

Planner's delta query call flow is as follows:

The caller initiates a delta sync query, obtaining a nextLink and an empty collection of changes.
The caller must populate the object cache for delta queries with objects that the user is subscribed to, updating its cache.
The caller follows the nextLink provided in the initial delta sync query to obtain a new deltaLink to any changes since previous step.
The caller applies the changes in the returned delta response to the objects in its cache.
The caller follows the new deltaLink to obtain the next deltaLink and changes since the current deltaLink was generated.
The caller applies the changes (if any) and waits a short time before rerunning the previous step and this step.

Planner resource versioning

Planner versions all resources using etags. These etags are returned with @odata.etag property on each resource. PATCH and DELETE requests require the last etag known by the client to be specified with a If-Match header. Planner allows changes to older versions of resources, if the intended change doesn't conflict with newer changes accepted by the Planner service on the same resource. The clients can identify which etag for the same resource is newer by calculating which etag value is greater in ordinal string comparison. Each resource has a unique etag. Etag values for different resources, including resources with containment relationships, can't be compared. The client apps are expected to handle versioning related error codes 409 and 412 by reading the latest version of the item and resolving the conflicting changes.

Common Planner error conditions

In addition to general errors that apply to Microsoft Graph, some error conditions are specific to the Planner API.

400 Bad request

In some common scenarios, POST and PATCH requests can return a 400 status code. The following are some of the common causes:

Open Type properties had the wrong type specified or no type specified, or didn't contain any properties. For example, plannerAssignments properties with complex values need to declare @odata.type property with value microsoft.graph.plannerAssignment.
Order hint values didn't have the correct format. For example, an order hint value was set directly to the value returned to the client.
The data is logically inconsistent. For example, start date of task is later than due date of the task.

403 Forbidden

In addition to the general errors, the Planner API also returns the 403 status code when a service-defined limit is exceeded. If so, the code property on the error resource type indicates the type of the limit exceeded by the request. The following are the possible values for the limit types.

Value	Description
MaximumProjectsOwnedByUser	The maximum number of plans contained by a group limit was exceeded. The container property of the plannerPlan resource determines this limit.
MaximumProjectsSharedWithUser	The maximum number of plans shared with a user limit was exceeded. The sharedWith property on the plannerPlanDetails resource determines this limit.
MaximumTasksCreatedByUser	The maximum number of tasks created by a user limit was exceeded. The createdBy property on the plannerTask resource determines this limit.
MaximumTasksAssignedToUser	The maximum number of tasks assigned to a user limit was exceeded. The assignments property on the plannerTask resource determines this limit.
MaximumTasksInProject	The maximum number of tasks in a plan limit was exceeded. The planId property on the plannerTask resource determines this limit.
MaximumActiveTasksInProject	The maximum number of tasks that aren't completed in a plan limit was exceeded. The planId and percentComplete properties on the plannerTask resource determines this limit.
MaximumBucketsInProject	The maximum number of buckets in a plan limit was exceeded. The planId property on the plannerBucket resource determines this limit.
MaximumUsersSharedWithProject	The sharedWith property on the plannerPlanDetails resource contains too many values.
MaximumReferencesOnTask	The references property on the plannerTaskDetails resource contains too many values.
MaximumChecklistItemsOnTask	The checklist property on the plannerTaskDetails resource contains too many values.
MaximumAssigneesInTasks	The assignments property on the plannerTask resource contains too many values.
MaximumFavoritePlansForUser	The favoritePlanReferences property on the plannerUser resource contains too many values.
MaximumRecentPlansForUser	The recentPlanReferences property on the plannerUser resource contains too many values.
MaximumContextsOnPlan	The contexts property on the plannerPlan resource contains too many values.

412 Precondition Failed

All Planner API POST, PATCH, and DELETE requests require the If-Match header to be specified with the last known etag value of the resource that is subject to the request. The 412 status code can also be returned if the etag value specified in the request no longer matches a version of the resource in the service. In this case, the clients should read the resource again and get a new etag.