編輯

Create task

Namespace: microsoft.graph

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.

Create a new task object.

API availability

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet
✅ ❌ ❌ ❌

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type Least privileged permission Higher privileged permissions
Delegated (work or school account) Not supported. Not supported.
Delegated (personal Microsoft account) Not supported. Not supported.
Application Not supported. Not supported.

HTTP request

POST /planner/tasks_v2

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-Type application/json. Required.

Request body

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

You can specify the following properties when creating a task.

Property Type Description
displayName String Title of the task. Required.
planId String ID of the plan that contains the task. Required. Immutable after creation.
bucketId String ID of the bucket that the task belongs to. Optional.
goalIds String collection IDs of the goals that the task is associated with. Optional.
status plannerTaskStatus Indicates progress on the task. The possible values are: notStarted, inProgress, completed, blocked, unknownFutureValue. Optional.
priority Int32 Priority of the task. Supported values range from 0 (urgent) to 10 (low). Optional.
percentComplete Int32 Percentage of the task's completion, ranging from 0 to 100. Optional.
startDateTime dateWithOptionalTime Date and, optionally, time the task is scheduled to start. Optional.
dueDateTime dateWithOptionalTime Date and, optionally, time the task is due. Optional.
finishDateTime dateWithOptionalTime Date and, optionally, time the task was finished. Optional.
notes itemBody Additional details or notes about the task. Optional.
recurrence plannerTaskRecurrence Recurrence pattern for the task, if it repeats. Optional.
planView taskPlanView Task view settings scoped to the plan, such as applied category IDs. Optional.
personalView taskPersonalView Per-user personal view settings for the task, such as My Day membership. Optional.
parentTaskId String ID of the parent task, if this task is a subtask. Optional.
extensions extensionFieldCollection Custom extension field values set on the entity. Supports $select. Optional.
checklist checklistItemV4 collection Checklist items to create with the task by using a deep insert. Optional.
links contentLink collection Content links to create with the task by using a deep insert. Optional.
userAssignments userAssignment collection Assignments to create with the task. Identify each assignee by user.id. Optional.

The planId property is required at creation and can't be changed afterward. Don't copy audit metadata, computed flags, or other read-only properties from a GET response into this request.

For startDateTime, dueDateTime, and finishDateTime, specify only date. The time, timeZone, and isTimeSpecified components aren't writable.

You can create a task and supported related objects in one POST request. This is a deep insert: include new checklist items, content links, or user assignments as arrays in the task request body. Omit a collection when you don't need it, or use an empty array; don't send null for these collections. The service generates identifiers and audit metadata for the new objects.

Deep insert isn't a standalone POST to a child collection, a $ref operation, or an instruction to replace a collection during PATCH. Support for one nested collection doesn't imply support for arbitrary relationships. Feature availability also depends on the plan's capabilities.

Properties such as parentTaskId and recurrence depend on the plan's supported features. Don't assume every property in the table is available for every plan.

Response

If successful, this method returns a 201 Created response code and a task object in the response body.

Examples

Example 1: Create a task

Request

The following example shows a request.

POST https://graph.microsoft.com/beta/planner/tasks_v2
Content-Type: application/json

{
  "@odata.type": "#microsoft.graph.task",
  "displayName": "Prepare quarterly report",
  "planId": "b3d9f9a2-3e14-4a4b-9b2b-6b6d9e6a2f31",
  "bucketId": "9c9c7a3d-5b7f-45e9-9df9-9f8b0f7edc9a",
  "status": "notStarted",
  "priority": 5,
  "percentComplete": 0,
  "startDateTime": {
    "date": "2026-06-01"
  },
  "dueDateTime": {
    "date": "2026-06-15"
  },
  "notes": {
    "@odata.type": "microsoft.graph.itemBody",
    "content": "Compile Q2 sales figures and prepare summary slides.",
    "contentType": "text"
  }
}

Response

The following example shows the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "@odata.type": "#microsoft.graph.task",
  "id": "86d64a5b-109d-39c9-dd43-d7fffb6a1670",
  "displayName": "Prepare quarterly report",
  "planId": "b3d9f9a2-3e14-4a4b-9b2b-6b6d9e6a2f31",
  "bucketId": "9c9c7a3d-5b7f-45e9-9df9-9f8b0f7edc9a",
  "status": "notStarted"
}

Example 2: Create a task with checklist items and assignees

Request

This request creates a task, two checklist items, and an assignment to an existing user. Replace planId and user.id with identifiers accessible to the caller. Don't supply IDs, assignedBy, or assignedDateTime for the new assignment.

POST https://graph.microsoft.com/beta/planner/tasks_v2
Content-Type: application/json

{
  "@odata.type": "#microsoft.graph.task",
  "displayName": "Prepare launch announcement",
  "planId": "b3d9f9a2-3e14-4a4b-9b2b-6b6d9e6a2f31",
  "checklist": [
    {
      "displayName": "Review the announcement",
      "isChecked": false
    },
    {
      "displayName": "Approve the publication date",
      "isChecked": false
    }
  ],
  "userAssignments": [
    {
      "user": {
        "id": "a96b71cc-d742-4b79-9c2a-a56287b7b2c7"
      }
    }
  ]
}

Response

The following response is shortened. To read the created related objects, get the returned task with $expand=checklist,userAssignments.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "@odata.type": "#microsoft.graph.task",
  "id": "86d64a5b-109d-39c9-dd43-d7fffb6a1670",
  "displayName": "Prepare launch announcement",
  "planId": "b3d9f9a2-3e14-4a4b-9b2b-6b6d9e6a2f31"
}