Every monday.com user is part of an account or organization and has a unique set of user details. Users also have different roles within an account and can be admins, team members, members, viewers, guests, subscribers, board owners, or in a custom role. This information is accessible via the API through the users object.

As a developer working with monday.com, it is important to familiarize yourself with the users API so you know how to access user data. This document will walk you through the available queries and mutations to read and modify the users object via the API.

Queries

Required scope: users:read

Querying users will return metadata about one or multiple users. This method accepts various arguments and returns an array.

You can query users directly at the root or nest it within a teams query to return users from a specific team. Please note that nesting users in a teams query will increase its complexity.

query {
  users (limit: 50) {
    created_at
    email
    account {
      name
      id
    }
  }
}

let query = "query { users (limit: 50) { created_at email account { name 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 reduce the number of results returned in your users query.

Argument	Description
emails `[String]`	The specific user emails to return.
ids `[ID!]`	The unique identifier of the specific users to return.
kind `UserKind`	The kind of users you want to search by: all, non_guests, guests, or non_pending.
limit `Int`	The number of users to get.
name `String`	A fuzzy search of users by name.
newest_first `Boolean`	Lists the most recently created users at the top.
non_active `Boolean`	Returns the account's non-active users.
page `Int`	The page number to return. Starts at 1.

Fields

You can use the following field(s) to specify what information your users query will return. Please note that some fields will have their own arguments or fields.

Field	Field description	Supported arguments	Supported fields
account `Account!`	The user's account.
birthday `Date`	The user's date of birth. Returned as YYYY-MM-DD.
country_code `String`	The user's country code.
created_at `Date`	The user's creation date. Returned as YYYY-MM-DD.
current_language `String`	The user's language.
email `String!`	The user's email.
enabled `Boolean!`	Returns `true` if the user is enabled.
id `ID!`	The user's unique identifier.
is_admin `Boolean`	Returns `true` if the user is an admin.
is_guest `Boolean`	Returns `true` if the user is a guest.
is_pending `Boolean`	Returns `true` if the user didn't confirm their email yet.
is_view_only `Boolean`	Returns `true` if the user is only a viewer.
is_verified `Boolean`	Returns `true` if the user verified their email.
join_date `Date`	The date the user joined the account. Returned as YYYY-MM-DD.
last_activity `Date`	The last date and time the user was active. Returned as YYYY-MM-DDT00:00:00.
location `String`	The user's location.
mobile_phone `String`	The user's mobile phone number.
name `String!`	The user's name.
out_of_office `OutOfOffice`	The user's out-of-office status.		active `Boolean` disable_notifications `Boolean` end_date `Date` start_date `Date` type `String`
phone `String`	The user's phone number.
photo_original `String`	Returns the URL of the user's uploaded photo in its original size.
photo_small `String`	Returns the URL of the user's uploaded photo in a small size (150x150 px).
photo_thumb `String`	Returns the URL of the user's uploaded photo in thumbnail size (100x100 px).
photo_thumb_small `String`	Returns the URL of the user's uploaded photo in a small thumbnail size (50x50 px).
photo_tiny `String`	Returns the URL of the user's uploaded photo in tiny size (30x30 px).
sign_up_product_kind `String`	The product the user first signed up to.
teams `[Team]`	The user's teams.	ids `[ID!]`
time_zone_identifier `String`	The user's timezone identifier.
title `String`	The user's title.
url `String!`	The user's profile URL.
utc_hours_diff `Int`	The user’s UTC hours difference.

Mutations

Add users to a board

Required scope: boards:write

The add_users_to_board mutation allows you to add users to a board via the API. You can also specify what fields to query back from the user when you run the mutation.

mutation {
  add_users_to_board (board_id: 1234567890, user_ids: [123456, 234567, 345678], kind: owner) {
    id
  }
}

let query = "mutation { add_users_to_board (board_id:1234567890, user_ids: [123456, 234567, 345678], kind: owner) { 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 specify which users to add to the board and their roles.

Argument	Description
board_id `ID!`	The board's unique identifier.
kind `BoardSubscriberKind`	The user's role: subscriber or owner.
user_ids `[ID!]!`	The unique identifiers of the users 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 users to a workspace

Required scope: workspaces:write

The add_users_to_workspace mutation allows you to add users to a workspace via the API. You can also specify what fields to query back from the user when you run the mutation.

mutation {
  add_users_to_workspace (workspace_id: 1234567, user_ids: [123456, 654321, 012345], kind: subscriber) {
    id
  }
}

let query = "mutation { add_users_to_workspace (workspace_id: 1234567, user_ids: [123456, 654321, 012345], kind: subscriber) { 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 specify which users to add to the workspace and their roles.

Arguments	Description
kind `WorkspaceSubscriberKind`	The user's role: subscriber or owner.
user_ids `[ID!]!`	The unique identifiers of the users to add to the workspace.
workspace_id `ID!`	The workspace's unique identifier.

Delete subscribers from a board

The delete_subscribers_from_board mutation allows you to delete subscribers from a board via the API. You can also specify what fields to query back from the subscribers you delete from the board when you run the mutation.

mutation {
  delete_subscribers_from_board(board_id: 1234567890, user_ids: [12345678, 87654321, 01234567]) {
    id
  }
}

let query = 'mutation { delete_subscribers_from_board(board_id: 1234567890, user_ids: [12345678, 87654321, 01234567]) { 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 specify which subscribers to delete from the board.

Argument	Description
board_id `ID!`	The board's unique identifier.
user_ids `[ID!]!`	The unique identifiers of the users to unsubscribe 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 users from a workspace

Required scope: workspaces:write

The delete_users_from_workspace mutation allows you to delete users from a workspace via the API. You can also specify what fields to query back from the user when you run the mutation.

mutation {
  delete_users_from_workspace (workspace_id: 1234567, user_ids: [123456, 654321, 012345]) {
    id
  }
}

let query = "mutation { delete_users_from_workspace (workspace_id: 1234567, user_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 specify which users to delete from the workspace.

Arguments	Description
user_ids `[ID!]!`	The unique identifiers of the users to remove 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! 😎

Queries

Arguments

Fields

Mutations

Add users to a board

Arguments

Add users to a team

Arguments

Add users to a workspace

Arguments

Delete subscribers from a board

Arguments

Remove users from a team

Arguments

Delete users from a workspace

Arguments

📘Join our developer community!

📘
Join our developer community!