Thanks to visit codestin.com
Credit goes to developer.monday.com

Users

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 teams query (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

ArgumentTypeDescriptionEnum 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)UserKindThe 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.all
guests
non_guests
non_pending
limitIntThe 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.
nameStringA fuzzy search of users by name.
newest_first (DEPRECATED)BooleanLists 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)BooleanReturns 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.
pageIntThe 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.ACTIVE
INACTIVE
PENDING
user_kindUserKindFilterInputFilter 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.
visibilityStringFilter users by visibility. Only available in versions 2026-07 and later.

Fields

FieldTypeField descriptionSupported Subfields
accountAccount!The user's account.
account_idID!The unique identifier of the account the user belongs to. Only available in versions 2026-07 and later.
activity_logsUserActivityLogsPageThe 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_idID!Opaque platform identifier for the user within the account. Only available in versions 2026-07 and later.
became_active_atISO8601DateTimeThe date and time when the user became active. Replaces join_date. Only available in versions 2026-07 and later.
birthdayDate (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_codeStringThe user's country code.
created_atDate (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_languageStringThe user's language.
departmentDepartmentThe 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 String
editable Boolean
field_type String
flagged Boolean
icon String
id String
position String
title String
custom_field_values[CustomFieldValue]The user profile custom field values.custom_field_meta_id String
value String
departmentDepartmentThe department(s) the user is a member of. Only available in versions 2026-04 and later.
emailString!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.
greetingStringThe user's greeting.
idID!The user's unique identifier.
invitation_methodInvitationMethod!The method by which the user was added to the account. Only available in versions 2026-07 and later.USER
SCIM
SSO
AUTH_DOMAIN
FIRST_USER
CONSOLIDATION
INTERNAL_CREATION
UNKNOWN
SERVICE_PORTAL_AUTH_DOMAIN
SERVICE_PORTAL_USER_INVITATION
API_USER_CREATION
is_admin (DEPRECATED)BooleanWhether the user is an admin. Deprecated in 2026-07 and scheduled for removal in 2026-10. Compare kind == "admin" instead.
is_deletedBoolean!Whether the user has been soft-deleted. Only available in versions 2026-07 and later.
is_email_confirmedBoolean!Whether the user has confirmed their email address. Replaces is_verified. Only available in versions 2026-07 and later.
is_guest (DEPRECATED)BooleanWhether the user is a guest. Deprecated in 2026-07 and scheduled for removal in 2026-10. Compare kind == "guest" instead.
is_pending (DEPRECATED)BooleanWhether 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)BooleanWhether the user is a viewer. Deprecated in 2026-07 and scheduled for removal in 2026-10. Compare kind == "view_only" instead.
is_verified (DEPRECATED)BooleanWhether the user verified their email. Deprecated in 2026-07 and scheduled for removal in 2026-10. Use is_email_confirmed instead.
join_date (DEPRECATED)DateThe 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_activityDateThe last date and time the user was active. Returned as YYYY-MM-DDT00:00:00.
locationStringThe user's location.
mobile_phoneStringThe user's mobile phone number.
nameString!The user's name.
out_of_officeOutOfOfficeThe user's out-of-office status.active Boolean
disable_notifications Boolean
end_date Date
start_date Date
type String
phoneStringThe user's phone number.
photo_original (DEPRECATED)StringReturns 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)StringReturns 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)StringReturns 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)StringReturns 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)StringReturns 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_urlPhotoUrlThe 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 String
small String
thumb String
thumb_small String
tiny String
serial_numberIntThe user's registration sequence number within the account. Only available in versions 2026-07 and later.
sign_up_product_kind (DEPRECATED)StringThe product the user first signed up to. Deprecated in 2026-07 and scheduled for removal in 2026-10. No replacement.
statusUserStatus!The activation status of the user. Replaces the enabled and is_pending booleans. Only available in versions 2026-07 and later.ACTIVE
INACTIVE
PENDING
teams[Team]The user's teams.
time_zone_identifierStringThe user's timezone identifier.
titleStringThe user's title.
urlString!The user's profile URL.
user_configUserConfig!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_diffInt (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-07 and 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_id ascending
query {
  user_configs {
    kind
    role_id
    visibility
  }
}

Arguments

ArgumentTypeDescription
kinds[String]Filter to configs that match these kinds.
visibilityStringFilter by visibility.

Migration: user entity in 2026-07 and 2026-10

Starting 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 fieldReplacement
photo_original, photo_small, photo_thumb, photo_thumb_small, photo_tinyphoto_url { original / small / thumb / thumb_small / tiny }
is_adminkind == "admin"
is_guestkind == "guest"
is_view_onlykind == "view_only"
is_pendingstatus == PENDING
enabledstatus == ACTIVE
is_verifiedis_email_confirmed
join_datebecame_active_at
encrypt_api_token, sign_up_product_kindRemoved 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

ArgumentTypeDescriptionEnum Values
board_idID!The board's unique identifier.
kindBoardSubscriberKindThe user's role.owner
subscriber
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

ArgumentTypeDescription
team_idID!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

ArgumentsTypeDescriptionEnum Values
kindWorkspaceSubscriberKindThe user's role.owner
subscriber
user_ids[ID!]!The users' unique identifiers.
workspace_idID!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

ArgumentTypeDescription
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

ArgumentTypeDescriptionEnum Values
emails[String!]!The users' emails.
productProductThe product to invite the user to.crm
dev
forms
knowledge
service
whiteboard
workflows
work_management
user_roleUserRoleThe invited user's new role.GUEST
MEMBER
VIEW_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

ArgumentTypeDescription
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

ArgumentTypeDescription
inputUpdateEmailDomainAttributesInput!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

ArgumentTypeDescriptionEnum Values
new_roleBaseRoleNameThe user's updated role. Only used to update default roles, not custom ones (read more here).ADMIN
GUEST
MEMBER
VIEW_ONLY
role_idIDThe 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

ArgumentTypeDescription
board_idID!The board's unique identifier.
user_ids[ID!]!The users' unique identifiers.

Clear users department

🚧

Only available in API versions 2026-04 and later

Clears a user's department. Returns ClearUsersDepartmentResult.

mutation {
  clear_users_department(user_ids: [12345, 54321]) {
    cleared_users {	
      name
      id
      department
    }
  }
}

Arguments

ArgumentTypeDescription
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

ArgumentTypeDescription
team_idID!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

ArgumentsTypeDescription
user_ids[ID!]!The users' unique identifiers.
workspace_idID!!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

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