Reference
Apps DocsCommunity

Users

Learn how to read, add, and delete monday users via the platform API

Every monday.com user is part of an account or organization as an admin, team member, member, viewer, guest, subscriber, board owner, or in a custom role. Each user has a unique set of user details. This information is accessible via the API through the users endpoint.

Queries

Required scope: users:read

  • Returns an array containing metadata about one or multiple users
  • Can be queried directly at the root or nested within a teams query to return users from a specific team
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.

ArgumentDescriptionEnum values
emails [String]The specific user emails to return.
ids [ID!]The unique identifier of the specific users to return.
kind UserKindThe kind of users you want to search by.all, guests, non_guests, non_pending
limit IntThe number of users to get.
name StringA fuzzy search of users by name.
newest_first BooleanLists the most recently created users at the top.
non_active BooleanReturns the account's non-active users.
page IntThe 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.

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

Mutations

Add users to a board

Required scope: boards:write

This mutation allows you to add users to a board. You can also specify what fields to query back 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.

ArgumentDescriptionEnum values
board_id ID!The board's unique identifier.
kind BoardSubscriberKindThe user's role.owner, subscriber
user_ids [ID!]!The unique identifiers of the users to add to the board.

Add users to a team

Required scope: teams:write

This mutation allows you to add users to a team. It 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 users to a workspace

Required scope: workspaces:write

This mutation allows you to add users to a workspace. You can also specify what fields to query back 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.

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

Update a user's email domain

This mutation allows you to update a user's email domain. It returns the UpdateEmailDomainResult type which allows you to specify what fields to query back when you run the mutation.

🚧

Only available in API versions 2025-01 and later

mutation {
  update_email_domain (input: {new_domain: "[email protected]", user_ids: [123456, 654321]}) {
    updated_users {
      name
      is_admin
    }
    errors {
      user_id
      code
      message
    }
  }
}

Arguments

ArgumentDescriptionSupported fields
input UpdateEmailDomainAttributesInput!The attributes to update.new_domain String!
user_ids [ID!]!

Update a user's role

This mutation allows you to update a user's role. It returns the UpdateUsersRoleResult type which allows you to specify what fields to query back when you run the mutation.

Please keep the following in mind:

  • You can't update yourself.
  • There's a maximum of 200 users per mutation.
  • Only admins can use this mutation.

🚧

Only available in API versions 2025-01 and later

mutation {
  update_users_role (user_ids: [12345, 54321], new_role: ADMIN) {
    updated_users {
      name
      is_admin
    }
    errors {
      user_id
      code
      message
    }
  }
}

Arguments

ArgumentDescriptionEnum values
new_role BaseRoleName!The user's updated role. ADMIN
GUEST
MEMBER
VIEWER
user_ids [ID!]!The unique identifiers of the users to update. The maximum is 200.

Delete subscribers from a board

This mutation allows you to delete subscribers from a board. You can also specify what fields to query back 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.

ArgumentDescription
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

This mutation allows you to remove users from a team. It 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 users from a workspace

Required scope: workspaces:write

This mutation allows you to delete users from a workspace. 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.

ArgumentsDescription
user_ids [ID!]!The unique identifiers of the users to remove from the workspace.
workspace_id ID!!The workspace's unique identifier.

Deactivate users

This mutation allows you to deactivate users from a monday.com account. It returns the DeactivateUsersResult type which supports a set of fields that you can query back when you run the mutation.

Please keep the following in mind:

  • You can't deactivate yourself.
  • There's a maximum of 200 users per mutation.
  • Only admins can use this mutation.
  • Deactivating a user also deactivates the integrations and automations they've created. Read more about deactivating users here!

🚧

Only available in API versions 2025-01 and later

mutation {
  deactivate_users (user_ids: [54321, 12345]) {
    deactivated_users {
     id
     name
    }
    errors {
      message
      code
      user_id
    }
  }
}

Arguments

ArgumentsDescription
user_ids [ID!]!The unique identifiers of the users to deactivate. The maximum is 200.