| title | Create team |
|---|---|
| description | Create a new team. |
| author | anandjo |
| ms.localizationpriority | high |
| ms.subservice | teams |
| doc_type | apiPageType |
| ms.date | 06/10/2024 |
Namespace: microsoft.graph
Create a new team.
Note
When you create a team, the SharePoint site of the general channel might fail to provision. If the site fails to provision after 5 minutes, use the Get filesFolder API to trigger provisioning.
[!INCLUDE national-cloud-support]
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.
[!INCLUDE permissions-table]
Note
- The Teamwork.Migrate.All permission is only supported for migration. In the future, Microsoft may require you or your customers to pay additional fees based on the amount of data imported.
- The Group.ReadWrite.All and Directory.ReadWrite.All permissions are supported only for backward compatibility. We recommend that you update your solutions to use an alternative permission listed in the previous table and avoid using these permissions going forward.
POST /teams| Header | Value |
|---|---|
| Authorization | Bearer {token}. Required. Learn more about authentication and authorization. |
| Content-Type | application/json. Required. |
In the request body, supply a JSON representation of a team object. Optionally, specify a value for the firstChannelName property to name the first channel that is created. The default value of the first channel is General.
If successful, this API returns a 202 Accepted response that contains a link to the teamsAsyncOperation.
Here's an example of a minimal request. By omitting other properties, the client is implicitly taking defaults from the pre-defined template represented by template.
POST https://graph.microsoft.com/v1.0/teams
Content-Type: application/json
{
"template@odata.bind": "https://graph.microsoft.com/v1.0/teamsTemplates('standard')",
"displayName": "My Sample Team",
"description": "My sample team’s description",
"firstChannelName": "My first channel of the sample team",
}[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')/operations('3a6fdce1-c261-48bc-89de-1cfef658c0d5')
Content-Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')
Content-Length: 0Here's an example of a minimal request using application permissions. By omitting other properties, the client is implicitly taking defaults from the predefined template represented by template. When issuing a request with application permissions, a user must be specified in the members collection.
POST https://graph.microsoft.com/v1.0/teams
Content-Type: application/json
{
"template@odata.bind":"https://graph.microsoft.com/v1.0/teamsTemplates('standard')",
"displayName":"My Sample Team",
"description":"My sample team’s description",
"firstChannelName": "My first channel of the sample team",
"members":[
{
"@odata.type":"#microsoft.graph.aadUserConversationMember",
"roles":[
"owner"
],
"user@odata.bind":"https://graph.microsoft.com/v1.0/users('0040b377-61d8-43db-94f5-81374122dc7e')"
}
]
}[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')/operations('3a6fdce1-c261-48bc-89de-1cfef658c0d5')
Content-Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')
Content-Length: 0Example 3: Create a team with multiple channels, installed apps, and pinned tabs using delegated permissions
Here's a request with a full payload. The client can override values in the base template and add to array-valued items to the extent allowed by validation rules for the specialization.
POST https://graph.microsoft.com/v1.0/teams
Content-Type: application/json
{
"template@odata.bind": "https://graph.microsoft.com/v1.0/teamsTemplates('standard')",
"visibility": "Private",
"displayName": "Sample Engineering Team",
"description": "This is a sample engineering team, used to showcase the range of properties supported by this API",
"firstChannelName": "My First Channel of the team",
"channels": [
{
"displayName": "Announcements 📢",
"isFavoriteByDefault": true,
"description": "This is a sample announcements channel that is favorited by default. Use this channel to make important team, product, and service announcements."
},
{
"displayName": "Training 🏋️",
"isFavoriteByDefault": true,
"description": "This is a sample training channel, that is favorited by default, and contains an example of pinned website and YouTube tabs.",
"tabs": [
{
"teamsApp@odata.bind": "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps('com.microsoft.teamspace.tab.web')",
"displayName": "A Pinned Website",
"configuration": {
"contentUrl": "https://learn.microsoft.com/microsoftteams/microsoft-teams"
}
},
{
"teamsApp@odata.bind": "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps('com.microsoft.teamspace.tab.youtube')",
"displayName": "A Pinned YouTube Video",
"configuration": {
"contentUrl": "https://tabs.teams.microsoft.com/Youtube/Home/YoutubeTab?videoId=X8krAMdGvCQ",
"websiteUrl": "https://www.youtube.com/watch?v=X8krAMdGvCQ"
}
}
]
},
{
"displayName": "Planning 📅 ",
"description": "This is a sample of a channel that is not favorited by default, these channels will appear in the more channels overflow menu.",
"isFavoriteByDefault": false
},
{
"displayName": "Issues and Feedback 🐞",
"description": "This is a sample of a channel that is not favorited by default, these channels will appear in the more channels overflow menu."
}
],
"memberSettings": {
"allowCreateUpdateChannels": true,
"allowDeleteChannels": true,
"allowAddRemoveApps": true,
"allowCreateUpdateRemoveTabs": true,
"allowCreateUpdateRemoveConnectors": true
},
"guestSettings": {
"allowCreateUpdateChannels": false,
"allowDeleteChannels": false
},
"funSettings": {
"allowGiphy": true,
"giphyContentRating": "Moderate",
"allowStickersAndMemes": true,
"allowCustomMemes": true
},
"messagingSettings": {
"allowUserEditMessages": true,
"allowUserDeleteMessages": true,
"allowOwnerDeleteMessages": true,
"allowTeamMentions": true,
"allowChannelMentions": true
},
"discoverySettings": {
"showInTeamsSearchAndSuggestions": true
},
"installedApps": [
{
"teamsApp@odata.bind": "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps('com.microsoft.teamspace.tab.vsts')"
},
{
"teamsApp@odata.bind": "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps('1542629c-01b3-4a6d-8f76-1938b779e48d')"
}
]
}[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /teams('958e8cf8-169a-42aa-8599-5c1c5479c0ca')/operations('00000000-0000-0000-0000-000000000000')
Content-Location: /teams('958e8cf8-169a-42aa-8599-5c1c5479c0ca')
Content-Length: 0The following example shows how you can create a new team from a group, given a groupId.
A few things to note about this call:
- To create a team, the group you create it from must have at least one owner.
- The team that's created always inherits properties such as display name, visibility, specialization, and members from the group. Therefore, when you make this call with the group@odata.bind property, the inclusion of team displayName, visibility, specialization, or members@odata.bind properties return an error.
- If the group was created less than 15 minutes ago, it's possible for the Create team call to fail with a 404 error code due to replication delays. We recommend that you retry the Create team call three times, with a 10-second delay between calls.
- Specifying a first channel name with the firstChannelName property isn't supported when you create a team from a group.
POST https://graph.microsoft.com/v1.0/teams
Content-Type: application/json
{
"template@odata.bind": "https://graph.microsoft.com/v1.0/teamsTemplates('standard')",
"group@odata.bind": "https://graph.microsoft.com/v1.0/groups('71392b2f-1765-406e-86af-5907d9bdb2ab')"
}[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /teams('71392b2f-1765-406e-86af-5907d9bdb2ab')/operations('9698b2b8-9636-4f49-b7a8-10dadfa7062a')
Content-Location: /teams('71392b2f-1765-406e-86af-5907d9bdb2ab')
Content-Length: 0Here's a request that converts an existing group with extended properties that will create the team with multiple channels, installed apps, and pinned tabs.
To learn more about supported base template types and supported properties, see Get started with Teams templates.
POST https://graph.microsoft.com/v1.0/teams
Content-Type: application/json
{
"template@odata.bind":"https://graph.microsoft.com/v1.0/teamsTemplates('standard')",
"group@odata.bind":"https://graph.microsoft.com/v1.0/groups('dbd8de4f-5d47-48da-87f1-594bed003375')",
"channels":[
{
"displayName":"Class Announcements 📢",
"isFavoriteByDefault":true
},
{
"displayName":"Homework 🏋️",
"isFavoriteByDefault":true
}
],
"memberSettings":{
"allowCreateUpdateChannels":false,
"allowDeleteChannels":false,
"allowAddRemoveApps":false,
"allowCreateUpdateRemoveTabs":false,
"allowCreateUpdateRemoveConnectors":false
},
"installedApps":[
{
"teamsApp@odata.bind":"https://graph.microsoft.com/v1.0/appCatalogs/teamsApps('com.microsoft.teamspace.tab.vsts')"
},
{
"teamsApp@odata.bind":"https://graph.microsoft.com/v1.0/appCatalogs/teamsApps('1542629c-01b3-4a6d-8f76-1938b779e48d')"
}
]
}[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')/operations('3a6fdce1-c261-48bc-89de-1cfef658c0d5')
Content-Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')
Content-Length: 0Base template types are special templates that Microsoft created for specific industries. These base templates often contain proprietary apps that aren't available in the store and team properties that aren't yet supported individually in Microsoft Teams templates.
To create a team from a non-standard base template, you want to change the template@odata.bind property in the request body from standard to point to the specific base template you’d like to create.
To learn more about supported base template types, see Get started with Teams templates.
Note
It can take up to 24 hours for Teams users to see a custom template change in the gallery.
POST https://graph.microsoft.com/v1.0/teams
Content-Type: application/json
{
"template@odata.bind": "https://graph.microsoft.com/v1.0/teamsTemplates('educationClass')",
"displayName": "My Class Team",
"description": "My Class Team’s Description"
}[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')/operations('3a6fdce1-c261-48bc-89de-1cfef658c0d5')
Content-Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')
Content-Length: 0Base template types can be extended with additional properties, enabling you to build on an existing base template with additional team settings, channels, apps, or tabs.
To learn more about supported base template types and supported properties, see Get started with Teams templates.
POST https://graph.microsoft.com/v1.0/teams
Content-Type: application/json
{
"template@odata.bind":"https://graph.microsoft.com/v1.0/teamsTemplates('educationClass')",
"displayName":"My Class Team",
"description":"My Class Team’s Description",
"channels":[
{
"displayName":"Class Announcements 📢",
"isFavoriteByDefault":true
},
{
"displayName":"Homework 🏋️",
"isFavoriteByDefault":true
}
],
"memberSettings":{
"allowCreateUpdateChannels":false,
"allowDeleteChannels":false,
"allowAddRemoveApps":false,
"allowCreateUpdateRemoveTabs":false,
"allowCreateUpdateRemoveConnectors":false
},
"installedApps":[
{
"teamsApp@odata.bind":"https://graph.microsoft.com/v1.0/appCatalogs/teamsApps('com.microsoft.teamspace.tab.vsts')"
},
{
"teamsApp@odata.bind":"https://graph.microsoft.com/v1.0/appCatalogs/teamsApps('1542629c-01b3-4a6d-8f76-1938b779e48d')"
}
]
}[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')/operations('3a6fdce1-c261-48bc-89de-1cfef658c0d5')
Content-Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')
Content-Length: 0The following example shows how to create a team for imported messages.
Note: In the future, Microsoft may require you or your customers to pay additional fees based on the amount of data imported.
Note: Teams created in migration mode only supports the
standardtemplate.
POST https://graph.microsoft.com/v1.0/teams
Content-Type: application/json
{
"@microsoft.graph.teamCreationMode": "migration",
"template@odata.bind": "https://graph.microsoft.com/v1.0/teamsTemplates('standard')",
"displayName": "My Sample Team",
"description": "My Sample Team’s Description",
"createdDateTime": "2020-03-14T11:22:17.067Z"
}HTTP/1.1 202 Accepted
Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')/operations('3a6fdce1-c261-48bc-89de-1cfef658c0d5')
Content-Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')If the request is unsuccessful, this method returns a 400 Bad Request response code.
400 Bad RequestThe following are common reasons for this response:
- createdDateTime is set in the future.
- createdDateTime is correctly specified but the teamCreationMode instance attribute is missing or set to an invalid value.
Here's an example of a minimal request using application permissions. By omitting other properties, the client is implicitly taking defaults from the predefined template represented by template. When issuing a request with application permissions, a user must be specified in the members collection.
POST https://graph.microsoft.com/v1.0/teams
Content-Type: application/json
{
"template@odata.bind":"https://graph.microsoft.com/v1.0/teamsTemplates('standard')",
"displayName":"My Sample Team",
"description":"My Sample Team’s Description",
"members":[
{
"@odata.type":"#microsoft.graph.aadUserConversationMember",
"roles":[
"owner"
],
"user@odata.bind":"https://graph.microsoft.com/v1.0/users('jacob@contoso.com')"
}
]
}[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')/operations('3a6fdce1-c261-48bc-89de-1cfef658c0d5')
Content-Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')
Content-Length: 0- Complete migration for a team
- Import third-party platform messages to Teams using Microsoft Graph
- Create channel
- Available templates
- Getting started with Retail Teams templates
- Getting started with Healthcare Teams templates
- Creating a group with a team
- Microsoft Graph service-specific throttling limits