Reference
Apps DocsCommunity

Teams

Learn how to query monday team data using the platform API

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).

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.

ArgumentDescription
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.

FieldDescriptionSupported 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 StringThe 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

Create team

Required scope: teams:write

The create_team mutation allows you to create a team via the API. You can also specify what fields to query back when you run the mutation.

🚧

Only available in API versions 2025-01 and later

mutation {
  create_team (input: {name: "New team", is_guest_team:false, subscriber_ids: [1234567890, 9876543210]}, options: {allow_empty_team: false}) {
    id
  }
}

let query = 'mutation { create_team (input: {name: \"New team\", is_guest_team:false, subscriber_ids: [1234567890, 9876543210]}, options: {allow_empty_team: false}) { 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 the new team's characteristics.

ArgumentDescriptionSupported fields
input CreateTeamAttributesInput!The new team's attributes.is_guest_team Boolean
name String!
parent_team_id ID
subscriber_ids [ID!]
options CreateTeamOptionsInputThe options for creating a new team.allow_empty_team Boolean

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.

ArgumentDescriptionEnum values
board_id ID!The board's unique identifier.
kind BoardSubscriberKindThe team's role. If the argument is not used, the team will be added as a subscriber.owner, subscriber
team_ids [ID!]!The unique identifiers of the teams to add to the board. You can pass -1 to subscribe everyone in an account to the board (see more here).

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.

ArgumentDescription
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.

ArgumentsDescriptionEnum values
kind WorkspaceSubscriberKindThe team's role.owner, subscriber
team_ids [ID!]!The unique identifiers of the teams to add to the workspace.
workspace_id ID!The workspace's unique identifier.

Delete team

Required scope: teams:write

The delete_team mutation allows you to delete a team via the API. You can also specify what fields to query back when you run the mutation.

🚧

Only available in API versions 2025-01 and later

mutation {
  delete_team (team_id: 1234567890) {
    id
  }
}

let query = 'mutation { delete_team (team_id: 1234567890) { 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.

ArgumentDescription
team_id ID!The unique identifier of the team to be deleted.

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.

mutation {
  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.

ArgumentsDescription
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.

ArgumentDescription
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.

ArgumentsDescription
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! 😎