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.