Edit

Share via

Create teamworkSection

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 section in a user's teamwork.

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 permissions Higher privileged permissions
Delegated (work or school account) TeamworkSection.ReadWrite Not available.
Delegated (personal Microsoft account) Not supported. Not supported.
Application TeamworkSection.ReadWrite.All Not available.

HTTP request

POST /users/{user-id}/teamwork/sections

Request headers

Header Value
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-Type application/json. Required.
If-Match The value of the @microsoft.graph.sectionsVersion annotation returned when you list sections, or the @odata.etag value from any previously retrieved section. Required for optimistic concurrency control.

Request body

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

The following table lists the properties that you can set when you create a teamworkSection.

Property Type Description
displayIcon sectionDisplayIcon The icon displayed for the section. Optional. The skinTone property of the icon can't be set and is derived from user settings.
displayName String The display name of the section. Required. Maximum length is 50 characters. Display names are case-sensitive and must be unique within a user's sections. The following names are reserved for system-defined sections and can't be used: RecentChats, QuickViews, TeamsAndChannels, MutedChats, MeetingChats, EngageCommunities.
isExpanded Boolean Indicates whether the section is expanded in the user interface. Optional. The default value is true.
sortType sectionSortType The sort order of items in the section. Optional. The default value is userDefinedCustomOrder. The valid values for user-defined sections are: mostRecent, unreadThenMostRecent, userDefinedCustomOrder, unknownFutureValue. The nameAlphabetical member isn't valid for user-defined sections.

Response

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

Note

The response includes an updated @odata.etag value. Use this value as the If-Match header for any subsequent mutation operations.

The following errors are possible.

Response code Message
400 Bad Request The 'displayName' property is required and must not be empty.
400 Bad Request The 'displayName' property must not exceed 50 characters.
400 Bad Request The section display name contains invalid characters or format.
400 Bad Request The 'id', 'createdDateTime', 'lastModifiedDateTime', 'sectionType', or 'isHierarchicalViewEnabled' property is read-only and must not be provided when creating a section.
400 Bad Request The 'displayIcon.contentUrl' property is not supported, or the 'displayIcon.displayName' or 'displayIcon.skinTone' property is read-only and must not be provided.
400 Bad Request The maximum number of sections has been reached.
409 Conflict A section with this display name already exists. Returned when the requested displayName matches an existing user-defined section or one of the reserved system-defined section names (RecentChats, QuickViews, TeamsAndChannels, MutedChats, MeetingChats, EngageCommunities). The comparison is case-sensitive.
412 Precondition Failed The If-Match header value doesn't match the current section hierarchy version. List sections again to retrieve the current @microsoft.graph.sectionsVersion annotation and retry.
428 Precondition Required The If-Match header is required for this operation.

Examples

Request

The following example shows a request.

POST https://graph.microsoft.com/beta/users/10f8c3a6-3e2a-4e8b-9c7d-5a4b6c8d9e0f/teamwork/sections
Content-type: application/json
If-Match: "1742515200"

{
  "displayName": "Project Alpha",
  "displayIcon": {
    "iconType": "🚀"
  },
  "sortType": "mostRecent"
}

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
Location: https://graph.microsoft.com/beta/users/10f8c3a6-3e2a-4e8b-9c7d-5a4b6c8d9e0f/teamwork/sections/c3d4e5f6-a7b8-9012-cdef-123456789012

{
  "@odata.type": "#microsoft.graph.teamworkSection",
  "@odata.etag": "\"1742515210\"",
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "displayName": "Project Alpha",
  "displayIcon": {
    "iconType": "🚀",
    "displayName": "Rocket",
    "contentUrl": null,
    "skinTone": null
  },
  "sectionType": "userDefined",
  "sortType": "mostRecent",
  "isExpanded": true,
  "isHierarchicalViewEnabled": false,
  "createdDateTime": "2026-03-08T10:00:00Z",
  "lastModifiedDateTime": "2026-03-08T10:00:00Z"
}
  • Last updated on