Learn how to read, add, and delete monday users via the platform API
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.
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 | Enum values |
---|---|---|
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 , guests , non_guests , 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 | Enum values |
---|---|---|
board_id ID! | The board's unique identifier. | |
kind BoardSubscriberKind | The 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
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 | Enum values |
---|---|---|
kind WorkspaceSubscriberKind | The 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. |
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! 😎