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

You can use the teams query to retrieve team data via the API.

Required scope: teams:read
Returns an array containing metadata about one or several teams
Can be queried directly at the root or nested within a users query (returns the teams a user is part of)

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 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. Some fields support their own arguments.

Field	Description	Supported Arguments
id `ID!`	The team's unique identifier.
name `String!`	The team's name.
owners `[User!]!`	The users who 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

The API allows you to create, update, and delete teams using the following mutations. These operations let you programmatically control a team's full lifecycle.

Create team

Required scope: teams:write

The create_team mutation creates a team via the API. You can specify which fields to return in the mutation response.

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 arguments to define the new team's characteristics.

Argument	Description	Supported Fields
input `CreateTeamAttributesInput!`	The new team's attributes.	is_guest_team `Boolean` name `String!` parent_team_id `ID` subscriber_ids `[ID!]`
options `CreateTeamOptionsInput`	The options for creating a new team.	allow_empty_team `Boolean`

Add teams to board

Required scope: boards:write

The add_teams_to_board mutation adds teams to a board via the API. You can specify which fields to return in the mutation response.

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 arguments to define which teams to add to the board.

Argument	Description	Enum Values
board_id `ID!`	The board's unique identifier.
kind `BoardSubscriberKind`	The 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 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 which fields to return in the mutation response.

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 arguments 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 workspace

Required scope: workspaces:write

The add_teams_to_workspace mutation adds teams to a workspace via the API. You can specify which fields to return in the mutation response.

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 arguments to define which teams to add to the workspace.

Arguments	Description	Enum Values
kind `WorkspaceSubscriberKind`	The 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.

Assign team owners

The assign_team_owners mutation assigns owners to a team via the API. It returns the AssignTeamOwnersResut type which allows you to specify which fields to return in the mutation response.

mutation {
  assign_team_owners(
    user_ids: [654321, 123456]
    team_id: 24681012
  ) {
    errors {
      message
      code
      user_id
    }
    team {
      owners {
        id
      }
    }
  }
}

let query = 'mutation { assign_team_owners (user_ids: [654321, 123456], team_id: 24681012) { errors { message code user_id } team { owners { 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 arguments to define which users to add as team owners.

Argument	Description
team_id `ID!`	The unique identifier of the team to assign owners to.
user_ids `[ID!]!`	The unique identifiers of the users to be assigned. Maximum of 200.

Remove team owners

The remove_team_owners mutation removes owners from a team via the API. It returns the RemoveTeamOwnersResult type which allows you to specify which fields to return in the mutation response.

mutation {
  remove_team_owners(
    user_ids: [
      654321
      123456
    ]
    team_id: 9876543210
  ) {
    errors {
      message
      code
      user_id
    }
    team {
      owners {
        id
      }
    }
  }
}

let query = 'mutation { remove_team_owners (user_ids: [654321, 123456], team_id: 24681012) { errors { message code user_id } team { owners { 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 arguments to define which users to remove as a team owner.

Argument	Description
team_id `ID!`	The unique identifier of the team to remove owners from.
user_ids `[ID!]!`	The unique identifiers of the users to be removed. The maximum is 200.

Remove users from team

Required scope: teams:write

The remove_users_from_team mutation removes users from a team via the API. It returns the ChangeTeamMembershipResult type which allows you to specify which fields to return in the mutation response.

mutation {
  remove_users_from_team(
    team_id: 7654321
    user_ids: [
      123456
      654321
      12345
    ]
  ) {
    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 arguments 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 team

Required scope: teams:write

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

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.

Argument	Description
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.

Arguments	Description
board_id `ID!`	The board's unique identifier.
team_ids `[ID!]!`	The unique identifiers of the teams to delete from the board.

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 specify which fields to return in the mutation response.

mutation {
  delete_teams_from_workspace(
    workspace_id: 1234567
    team_ids: [
      123456
      654321
      12345
    ]
  ) {
    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 arguments 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.