Teams are the most efficient way to manage groups of users in monday.com. Teams are comprised of one or multiple users, and every user can be a part of multiple teams (or none).
As a developer working with monday.com, it is important to familiarize yourself with the teams
API so you know how to access team data. This document will walk you through the available queries and mutations to read and modify the teams
object via the API.
Queries
Required scope: teams:read
Querying teams
will return metadata about one or several teams. This method accepts one argument and returns an array.
You can query teams
directly at the root, or you can nest it within a users
query to return the teams a specific user is part of. Please note that nesting your query will increase its complexity.
query {
teams {
name
picture_url
users {
created_at
phone
}
}
}
let query = "query { teams { name picture_url users { created_at phone } } }";
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
query : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to reduce the number of results returned in your teams
query.
Argument | Description |
---|---|
ids [ID!] | The unique identifiers of the specific teams to return. |
Fields
You can use the following field(s) to specify what information your teams
query will return. Please note that some fields will have their own arguments.
Field | Description | Supported arguments |
---|---|---|
id ID! | The team's unique identifier. | |
name String! | The team's name. | |
owners [User!]! | The users that are the team's owners. | ids [ID!] |
picture_url String | The team's picture URL. | |
users [User] | The team's users. | emails [String] ids [ID!] kind UserKind limit Int name String newest_first Boolean non_active Boolean page Int |
Mutations
Add teams to a board
Required scope: boards:write
The add_teams_to_board
mutation allows you to add teams to a board via the API. You can also specify what fields to query back when you run the mutation.
mutation {
add_teams_to_board (board_id: 1234567890, kind: owner, team_ids: [654321, 123456]) {
id
}
}
let query = 'mutation { add_teams_to_board (board_id: 1234567890, kind: owner, team_ids: [654321,123456]) { id } }';
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query' : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to define which teams to add to the board.
Argument | Description |
---|---|
board_id ID! | The board's unique identifier. |
kind BoardSubscriberKind | The team's role: subscriber or owner. If the argument is not used, the team will be added as a subscriber. Please note that this argument is only available in API versions 2024-01 and later. |
team_ids [ID!]! | The unique identifiers of the teams to add to the board. |
Add users to a team
Required scope: teams:write
The add_users_to_team
mutation allows you to add users to a team via the API. This mutation returns the ChangeTeamMembershipResult
type which allows you to specify what fields to query back when you run the mutation.
mutation {
add_users_to_team (team_id: 7654321, user_ids: [123456, 654321, 012345]) {
successful_users {
name
email
}
failed_users {
name
email
}
}
}
let query = "mutation { add_users_to_team (team_id:7654321, user_ids: [123456, 654321, 012345]) { successful_users { name email } failed_users { name email }}}";
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
query : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to specify which users to add to the team.
Argument | Description |
---|---|
team_id ID! | The unique identifier of the team to add users to. |
user_ids [ID!]! | The unique identifiers of the users to add to the team. |
Add teams to a workspace
Required scope: workspaces:write
The add_teams_to_workspace
mutation allows you to add teams to a workspace via the API. You can also specify what fields to query back when you run the mutation.
mutation {
add_teams_to_workspace (workspace_id: 1234567, kind: owner, team_ids: [123456, 654321, 012345]) {
id
}
}
let query = 'mutation { add_teams_to_workspace (workspace_id: 1234567, kind: owner, team_ids: [123456, 654321, 012345]) { id } }';
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query' : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to define which teams to add to the workspace.
Arguments | Description |
---|---|
kind WorkspaceSubscriberKind | The team's role: owner or subscriber. |
team_ids [ID!]! | The unique identifiers of the teams to add to the workspace. |
workspace_id ID! | The workspace's unique identifier. |
Delete teams from a board
Required scope: boards:write
The delete_teams_from_board
mutation allows you to delete teams from a board via the API. You can also specify what fields to query back when you run the mutation.
Pro tip
delete_teams_from_board
is only available in API versions2024-01
and later.
query {
delete_teams_from_board (board_id: 1234567890, team_ids: [123456, 654321, 012345]) {
id
}
}
let query = 'mutation { delete_teams_from_board (board_id: 1234567890, team_ids: [123456, 654321, 012345]) { id } }';
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query' : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to define which teams to delete from the board.
Arguments | Description |
---|---|
board_id ID! | The board's unique identifier. |
team_ids [ID!]! | The unique identifiers of the teams to delete from the board. |
Remove users from a team
Required scope: teams:write
The remove_users_from_team
mutation allows you to remove users from a team via the API. This mutation returns the ChangeTeamMembershipResult
type which allows you to specify what fields to query back when you run the mutation.
mutation {
remove_users_from_team (team_id: 7654321, user_ids: [123456, 654321, 012345]) {
successful_users {
name
email
}
failed_users {
name
email
}
}
}
let query = "mutation { remove_users_from_team (team_id:7654321, user_ids: [123456, 654321, 012345]) { successful_users { name email } failed_users { name email }}}";
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
query : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to specify which users to remove from the team.
Argument | Description |
---|---|
team_id ID! | The unique identifier of the team to remove users from. |
user_ids [ID!]! | The unique identifiers of the users to remove from the team. |
Delete teams from a workspace
Required scope: workspaces:write
The delete_teams_from_workspace
mutation allows you to delete teams from a workspace via the API. You can also specify what fields to query back when you run the mutation.
mutation {
delete_teams_from_workspace (workspace_id: 1234567, team_ids: [123456, 654321, 012345]) {
id
}
}
let query = 'mutation { delete_teams_from_workspace (workspace_id: 1234567, team_ids: [123456, 654321, 012345]) { id } }';
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query' : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to define which teams to delete from the workspace.
Arguments | Description |
---|---|
team_ids [ID!]! | The unique identifiers of the teams to delete from the workspace. |
workspace_id ID! | The workspace's unique identifier. |
Join our developer community!
We've created a community specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎