Use the Microsoft Graph API to work with Microsoft Teams

Important: APIs under the /beta version in Microsoft Graph are in preview and are subject to change. Use of these APIs in production applications is not supported.

Microsoft Teams is a chat-based workspace in Office 365 that provides built-in access to team-specific calendars, files, OneNote notes, Planner plans, and more.

Key resources in Microsoft Teams

Resource Methods
team list your teams, list all teams, create, read, update, delete, clone, archive, unarchive
group add member, remove member, add owner, remove owner, get files, get notebook, get plans, get calendar
channel list, create, read, update, delete
teamsTab list, create, read, update, delete
teamsApp list, publish, update, remove
teamsAppInstallation list, install, upgrade, remove
(Preview) chatMessage and chatThread list, create, read
(Preview) call answer, reject, redirect, mute, unmute, update metadata, change screen sharing role, list participants, invite participants, mute all participants

Teams and groups

In Microsoft Graph, Microsoft Teams is represented by a group resource. Both Microsoft Teams and Office 365 groups address the various needs of group collaboration. Almost all the group-based features apply to Microsoft Teams and Office 365 groups, such as group calendar, files, notes, photo, plans, and so on. The main difference between a team and an Office 365 group is the mode of communication between members. Team members communicate by persistent chat in the context of a specific team. Office 365 group members communicate by group conversations, which are email conversations that occur in the context of a group in Outlook.

Any group that has a team has a resourceProvisioningOptions property that contains "Team".

Note: The Group.resourceProvisioningOptions property can be changed. Do not add or remove "Team" from that collection; otherwise, you'll get incorrect results when you list all teams.

The following are the differences at the API level between teams and groups:

Note: If you use the groups API in a Microsoft Teams app rather than in a standalone app - for example as part of a tab or bot running in Microsoft Teams - follow the guidance in the article Using Microsoft Graph in your Microsoft Teams pages.

Membership changes in Microsoft Teams

To add members and owners to a team, change the membership of the group with the same ID.

Use case Verb URL
Add member POST /groups/{id}/members/$ref
Remove member DELETE /groups/{id}/members/{userId}/$ref
Add owner POST /groups/{id}/owners/$ref
Remove owner DELETE /groups/{id}/owners/{userId}/$ref
Update team PATCH /teams/{id}

We recommend that when you add an owner, you also add that user as a member. If a team has an owner who is not also a member, ownership and membership changes might not show up immediately in Microsoft Teams. In addition, different apps and APIs will handle that differently. For example, Microsoft Teams will show teams that the user is either a member or an owner of, while the Microsoft Teams PowerShell cmdlets and the /me/joinedTeams API will only show teams the user is a member of. To avoid confusion, add all owners to the members list as well.

Known issue: when DELETE /groups/{id}/owners is called, the user is also removed from the /groups/{id}/members list. To work around this, we recommend that you remove the user from both owners and members, then wait 10 seconds, then add them back to members.

When adding and removing members and owners, don't put braces { } around the ID.

Speed Syntax
Fast https://graph.microsoft.com/beta/groups/02bd9fd6-8f93-4758-87c3-1fb73740a315/members/48d31887-5fad-4d73-a9f5-3c356e68a038/$ref
Slow https://graph.microsoft.com/beta/groups/{02bd9fd6-8f93-4758-87c3-1fb73740a315}/members/{48d31887-5fad-4d73-a9f5-3c356e68a038}/$ref

Similarly, if the userId in the URL or payload is expressed as a UPN rather than as a GUID, the performance will be slower.

Speed Syntax
Fast 48d31887-5fad-4d73-a9f5-3c356e68a038
Slow john@example.com

When the slower path is taken, if a current team member or owner is signed in to the Microsoft Teams application/website, the change will be reflected within an hour. If none of those users are signed in to the Microsoft Teams application/website, the change will not be reflected until an hour after one of them signs in.

See also

Microsoft Teams API overview