Learn how to read, add, and delete monday users via the platform API
Every monday.com user belongs to an account or organization and is assigned a role, such as admin, member, viewer, guest, subscriber, board owner, or a custom role. Each user also has a unique profile containing their user details and permissions.
Queries
Get users
- 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
teamsquery (returns users from a specific team)
query {
users(limit: 50) {
created_at
email
account {
name
id
}
}
}const GET_USERS = "query { users (limit: 50) { created_at email account { name id }}}";
const seamlessApiClient = new SeamlessApiClient("2025-04");
const response = await seamlessApiClient.request(GET_USERS)Arguments
| Argument | Type | Description | Enum Values |
|---|---|---|---|
| emails | [String] (2026-04)[String!] (2026-07+) | The specific user emails to return. Starting in 2026-07, array elements must be non-null. | |
| ids | [ID!] | The unique identifier of the specific users to return. | |
| kind (DEPRECATED) | UserKind | The kind of users you want to search by. Deprecated in 2026-07 (@deprecated(reason: "Use user_kind instead.")). Still accepted at runtime; a removal version has not been announced. | allguestsnon_guestsnon_pending |
| limit | Int | The number of users to get. Starting in 2026-07, defaults to 200 and has a maximum of 1000. Queries with no limit returned all users in earlier versions; starting in 2026-07 they return at most 200. | |
| name | String | A fuzzy search of users by name. | |
| newest_first (DEPRECATED) | Boolean | Lists the most recently created users at the top. Deprecated in 2026-07 (@deprecated(reason: "Use sort instead.")). Still accepted at runtime; a removal version has not been announced. | |
| non_active (DEPRECATED) | Boolean | Returns the account's non-active users. Deprecated in 2026-07 (@deprecated(reason: "Use status instead.")). Still accepted at runtime; a removal version has not been announced. | |
| page | Int | The page number to return. Starts at 1. | |
| sort | [UsersSortInput!] | Sort users by one or more fields and directions. Replaces newest_first. Only available in versions 2026-07 and later. | |
| status | [UserStatus!] | Filter users by activation status. Defaults to [ACTIVE, PENDING] when omitted. Replaces non_active. Only available in versions 2026-07 and later. | ACTIVEINACTIVEPENDING |
| user_kind | UserKindFilterInput | Filter users by kind. Supports individual kinds and kind groups (for example, BASIC = admin + member + guest + view_only). Replaces kind. Only available in versions 2026-07 and later. | |
| visibility | String | Filter users by visibility. Only available in versions 2026-07 and later. |
Fields
| Field | Type | Field description | Supported Subfields |
|---|---|---|---|
| account | Account! | The user's account. | |
| account_id | ID! | The unique identifier of the account the user belongs to. Only available in versions 2026-07 and later. | |
| activity_logs | UserActivityLogsPage | The user's activity log events. Returns a paginated list of activity logs with cursor-based pagination. See Activity logs for arguments, field definitions, and rate-limit details. Only available in versions 2026-07 and later. | |
| bb_visitor_id | ID! | Opaque platform identifier for the user within the account. Only available in versions 2026-07 and later. | |
| became_active_at | ISO8601DateTime | The date and time when the user became active. Replaces join_date. Only available in versions 2026-07 and later. | |
| birthday | Date (2026-04)String (2026-07+) | The user's date of birth. Returned as YYYY-MM-DD. Starting in 2026-07, this field is typed as String instead of Date. | |
| country_code | String | The user's country code. | |
| created_at | Date (2026-04)ISO8601DateTime! (2026-07+) | The user's creation date. In 2026-04 and earlier, returned as Date (YYYY-MM-DD). Starting in 2026-07, returned as ISO8601DateTime! (for example, 2023-09-02T13:22:48.000Z) and non-null. | |
| current_language | String | The user's language. | |
| department | Department | The department the user is a member of (if any). Returns null if the user is not assigned to a department. Only available in versions 2026-04 and later. | |
| custom_field_metas | [CustomFieldMetas] | The user profile custom fields metadata. | description Stringeditable Booleanfield_type Stringflagged Booleanicon Stringid Stringposition Stringtitle String |
| custom_field_values | [CustomFieldValue] | The user profile custom field values. | custom_field_meta_id Stringvalue String |
| department | Department | The department(s) the user is a member of. Only available in versions 2026-04 and later. | |
String! | The user's email. | ||
| enabled (DEPRECATED) | Boolean! | Whether the user is enabled. Deprecated in 2026-07 and scheduled for removal in 2026-10. Use status (ACTIVE, INACTIVE) instead. | |
| greeting | String | The user's greeting. | |
| id | ID! | The user's unique identifier. | |
| invitation_method | InvitationMethod! | The method by which the user was added to the account. Only available in versions 2026-07 and later. | USERSCIMSSOAUTH_DOMAINFIRST_USERCONSOLIDATIONINTERNAL_CREATIONUNKNOWNSERVICE_PORTAL_AUTH_DOMAINSERVICE_PORTAL_USER_INVITATIONAPI_USER_CREATION |
| is_admin (DEPRECATED) | Boolean | Whether the user is an admin. Deprecated in 2026-07 and scheduled for removal in 2026-10. Compare kind == "admin" instead. | |
| is_deleted | Boolean! | Whether the user has been soft-deleted. Only available in versions 2026-07 and later. | |
| is_email_confirmed | Boolean! | Whether the user has confirmed their email address. Replaces is_verified. Only available in versions 2026-07 and later. | |
| is_guest (DEPRECATED) | Boolean | Whether the user is a guest. Deprecated in 2026-07 and scheduled for removal in 2026-10. Compare kind == "guest" instead. | |
| is_pending (DEPRECATED) | Boolean | Whether the user hasn't confirmed their email yet. Deprecated in 2026-07 and scheduled for removal in 2026-10. Compare status == PENDING instead. | |
| is_view_only (DEPRECATED) | Boolean | Whether the user is a viewer. Deprecated in 2026-07 and scheduled for removal in 2026-10. Compare kind == "view_only" instead. | |
| is_verified (DEPRECATED) | Boolean | Whether the user verified their email. Deprecated in 2026-07 and scheduled for removal in 2026-10. Use is_email_confirmed instead. | |
| join_date (DEPRECATED) | Date | The date the user joined the account. Returned as YYYY-MM-DD. Deprecated in 2026-07 and scheduled for removal in 2026-10. Use became_active_at instead. | |
| 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 Booleandisable_notifications Booleanend_date Datestart_date Datetype String |
| phone | String | The user's phone number. | |
| photo_original (DEPRECATED) | String | Returns the URL of the user's uploaded photo in its original size. Deprecated in 2026-07 and scheduled for removal in 2026-10. Use photo_url { original } instead. | |
| photo_small (DEPRECATED) | String | Returns the URL of the user's uploaded photo in a small size (150x150 px). Deprecated in 2026-07 and scheduled for removal in 2026-10. Use photo_url { small } instead. | |
| photo_thumb (DEPRECATED) | String | Returns the URL of the user's uploaded photo in thumbnail size (100x100 px). Deprecated in 2026-07 and scheduled for removal in 2026-10. Use photo_url { thumb } instead. | |
| photo_thumb_small (DEPRECATED) | String | Returns the URL of the user's uploaded photo in a small thumbnail size (50x50 px). Deprecated in 2026-07 and scheduled for removal in 2026-10. Use photo_url { thumb_small } instead. | |
| photo_tiny (DEPRECATED) | String | Returns the URL of the user's uploaded photo in tiny size (30x30 px). Deprecated in 2026-07 and scheduled for removal in 2026-10. Use photo_url { tiny } instead. | |
| photo_url | PhotoUrl | The URLs for the user's profile photo in all available sizes. Replaces the flat photo_* fields. Only available in versions 2026-07 and later. | original Stringsmall Stringthumb Stringthumb_small Stringtiny String |
| serial_number | Int | The user's registration sequence number within the account. Only available in versions 2026-07 and later. | |
| sign_up_product_kind (DEPRECATED) | String | The product the user first signed up to. Deprecated in 2026-07 and scheduled for removal in 2026-10. No replacement. | |
| status | UserStatus! | The activation status of the user. Replaces the enabled and is_pending booleans. Only available in versions 2026-07 and later. | ACTIVEINACTIVEPENDING |
| teams | [Team] | The user's teams. | |
| time_zone_identifier | String | The user's timezone identifier. | |
| title | String | The user's title. | |
| url | String! | The user's profile URL. | |
| user_config | UserConfig! | The user's configuration based on their kind (role id, visibility). Requires the users:read scope. Only available in versions 2026-07 and later. | kind String!role_id ID!visibility [String!]! |
| utc_hours_diff | Int (2026-04)Float (2026-07+) | The user's UTC hours difference. Starting in 2026-07, this field is typed as Float to support fractional timezone offsets (for example, 5.5). |
Get user configs
Only available in API versions
2026-07and later
- Required scope:
users:read - Returns
[UserConfig!]! - Can be queried directly at the root
- Returns every user config defined for the account, sorted by
role_idascending
query {
user_configs {
kind
role_id
visibility
}
}Arguments
| Argument | Type | Description |
|---|---|---|
| kinds | [String] | Filter to configs that match these kinds. |
| visibility | String | Filter by visibility. |
Migration: user entity in 2026-07 and 2026-10
2026-07 and 2026-10Starting with API version 2026-07, the User type and Query.users follow the updated schema described in the User entity migration guide. Several legacy fields are deprecated and are scheduled for removal in 2026-10.
| Deprecated field | Replacement |
|---|---|
photo_original, photo_small, photo_thumb, photo_thumb_small, photo_tiny | photo_url { original / small / thumb / thumb_small / tiny } |
is_admin | kind == "admin" |
is_guest | kind == "guest" |
is_view_only | kind == "view_only" |
is_pending | status == PENDING |
enabled | status == ACTIVE |
is_verified | is_email_confirmed |
join_date | became_active_at |
encrypt_api_token, sign_up_product_kind | Removed without replacement |
Query.users(kind:) | Query.users(user_kind:) |
Query.users(newest_first:) | Query.users(sort:) |
Query.users(non_active:) | Query.users(status:) |
Mutations
Add users to board
Required scope: boards:write
Adds users to a board. Returns [User].
mutation {
add_users_to_board(
board_id: 1234567890
user_ids: [
123456
234567
345678
]
kind: owner
) {
id
}
}Arguments
| Argument | Type | Description | Enum Values |
|---|---|---|---|
| board_id | ID! | The board's unique identifier. | |
| kind | BoardSubscriberKind | The user's role. | ownersubscriber |
| user_ids | [ID!]! | The users' unique identifiers. |
Add users to team
Adds users to a team. Returns ChangeTeamMembershipResult.
mutation {
add_users_to_team(
team_id: 7654321
user_ids: [
123456
654321
12345
]
) {
successful_users {
name
email
}
failed_users {
name
email
}
}
}Arguments
| Argument | Type | Description |
|---|---|---|
| team_id | ID! | The team's unique identifier. |
| user_ids | [ID!]! | The users' unique identifiers. |
Add users to workspace
Required scope: workspaces:write
Adds users to a workspace. Returns [User].
mutation {
add_users_to_workspace(
workspace_id: 1234567
user_ids: [
123456
654321
987654
]
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
| Arguments | Type | Description | Enum Values |
|---|---|---|---|
| kind | WorkspaceSubscriberKind | The user's role. | ownersubscriber |
| user_ids | [ID!]! | The users' unique identifiers. | |
| workspace_id | ID! | The workspace's unique identifier. |
Activate users
Activates or reactivates users in a monday.com account. Returns ActivateUsersResult.
mutation {
activate_users(
user_ids: [
54321
12345
]
) {
activated_users {
id
name
email
}
errors {
user_id
code
message
}
}
}let query = 'mutation { activate_users (user_ids: [54321, 12345]) { activated_users { id name email } errors { user_id code message }}}';
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
| Argument | Type | Description |
|---|---|---|
| user_ids | [ID!]! | The users' unique identifiers. The maximum is 200. |
Invite users
Invites users to join a monday.com account. They will remain in a pending status until the invitation is accepted. Returns InviteUsersResult.
mutation {
invite_users(
emails: [
"[email protected]"
"[email protected]"
]
product: crm
user_role: VIEW_ONLY
) {
errors {
message
code
email
}
invited_users {
name
id
}
}
}let query = 'mutation { invite_users (input: ) { deactivated_users { id name }}';
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
| Argument | Type | Description | Enum Values |
|---|---|---|---|
| emails | [String!]! | The users' emails. | |
| product | Product | The product to invite the user to. | crmdevformsknowledgeservicewhiteboardworkflowswork_management |
| user_role | UserRole | The invited user's new role. | GUESTMEMBERVIEW_ONLY |
Update multiple users
Updates one or multiple users' attributes. Returns UpdateUserAttributesResult.
mutation {
update_multiple_users(
user_updates: [
{
user_id: 12345678
user_attribute_updates: {
birthday: "1985-06-01"
email: "[email protected]"
}
}
{
user_id: 87654321
user_attribute_updates: {
birthday: "1975-01-20"
email: "[email protected]"
}
}
]
) {
updated_users {
name
birthday
email
id
}
errors {
message
code
user_id
}
}
}Arguments
| Argument | Type | Description |
|---|---|---|
| user_updates | [UserUpdateInput!]! | The unique identifiers and attributes to update. Updates users' birthdays, departments, emails, join dates, locations, mobile phone numbers, names, and titles. |
Update email domain
Updates a user's email domain. Returns UpdateEmailDomainResult.
mutation {
update_email_domain(
input: {
new_domain: "[email protected]"
user_ids: [
123456
654321
]
}
) {
updated_users {
name
is_admin
}
errors {
user_id
code
message
}
}
} Arguments
| Argument | Type | Description |
|---|---|---|
| input | UpdateEmailDomainAttributesInput! | The attributes to update. |
Update user's role
Updates a user's role (accepts both custom or default roles). Returns UpdateUsersRoleResult.
Please keep the following in mind:
- You can't update yourself
- Maximum of 200 user IDs per mutation
- Only admins can use this mutation
mutation {
update_users_role(
user_ids: [
12345
54321
]
new_role: ADMIN
) {
updated_users {
name
is_admin
}
errors {
user_id
code
message
}
}
} mutation {
update_users_role(
user_ids: [
12345
54321
]
role_id: "5"
) {
updated_users {
name
}
errors {
user_id
code
message
}
}
} Arguments
| Argument | Type | Description | Enum Values |
|---|---|---|---|
| new_role | BaseRoleName | The user's updated role. Only used to update default roles, not custom ones (read more here). | ADMINGUESTMEMBERVIEW_ONLY |
| role_id | ID | The custom role's unique identifier (found by querying account_roles). Available only for enterprise customers. | |
| user_ids | [ID!]! | The users' unique identifiers. The maximum is 200. |
Delete subscribers from a board
Deletes subscribers from a board. Returns [User].
mutation {
delete_subscribers_from_board(
board_id: 1234567890
user_ids: [
12345678
87654321
56789012
]
) {
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
| Argument | Type | Description |
|---|---|---|
| board_id | ID! | The board's unique identifier. |
| user_ids | [ID!]! | The users' unique identifiers. |
Clear users department
Only available in API versions
2026-04and later
Clears a user's department. Returns ClearUsersDepartmentResult.
mutation {
clear_users_department(user_ids: [12345, 54321]) {
cleared_users {
name
id
department
}
}
}Arguments
| Argument | Type | Description |
|---|---|---|
| user_ids | [ID!]! | The IDs of the users to clear the department of. |
Remove users from team
Removes users from a team. Returns ChangeTeamMembershipResult.
mutation {
remove_users_from_team(
team_id: 7654321
user_ids: [
123456
654321
987654
]
) {
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
| Argument | Type | Description |
|---|---|---|
| team_id | ID! | The team's unique identifier. |
| user_ids | [ID!]! | The users' unique identifiers. |
Delete users from workspace
Required scope: workspaces:write
Deletes users from a workspace. Returns [User].
mutation {
delete_users_from_workspace(
workspace_id: 1234567
user_ids: [
123456
654321
987654
]
) {
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
| Arguments | Type | Description |
|---|---|---|
| user_ids | [ID!]! | The users' unique identifiers. |
| workspace_id | ID!! | The workspace's unique identifier. |
Deactivate users
Deactivates users from a monday.com account. Returns DeactivateUsersResult.
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!
mutation {
deactivate_users(
user_ids: [
54321
12345
]
) {
deactivated_users {
id
name
}
errors {
message
code
user_id
}
}
}Arguments
| Arguments | Type | Description |
|---|---|---|
| user_ids | [ID!]! | The unique identifiers of the users to deactivate. The maximum is 200. |
