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

You can use the users query to retrieve user data via the API.

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

You can use the following arguments 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 fields to specify what information your users query will return. Some fields support their own subfields.

Field	Field description	Supported Subfields
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.
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`
email `String!`	The user's email.
enabled `Boolean!`	Whether the user is enabled.
greeting `String`	The user's greeting.
id `ID!`	The user's unique identifier.
is_admin `Boolean`	Whether the user is an admin.
is_guest `Boolean`	Whether the user is a guest.
is_pending `Boolean`	Whether the user hasn't confirmed their email yet.
is_view_only `Boolean`	Whether the user is a viewer.
is_verified `Boolean`	Whether 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.
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

The API allows you to update users using the following mutations.

Add users to board

Required scope: boards:write

The add_users_to_board mutation adds users to a board via the API. You can specify which fields to return in the mutation response.

mutation {
  add_users_to_board(
    board_id: 1234567890
    user_ids: [
      123456
      234567
      345678
    ] 
    kind: owner
  ) {
    id
  }
}

Arguments

You can use the following arguments to define 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 users' unique identifiers.

Add users to team

The add_users_to_team mutation adds users to a team via the API. It returns the ChangeTeamMembershipResult type which allows you to specify which fields to return in the mutation response.

mutation {
  add_users_to_team(
    team_id: 7654321
    user_ids: [
      123456
      654321
      12345
    ]
  ) {
    successful_users {
      name
      email
    }
    failed_users {
      name
      email
    }
  }
}

Arguments

You can use the following arguments to specify which users to add to the team.

Argument	Description
team_id `ID!`	The team's unique identifier.
user_ids `[ID!]!`	The users' unique identifiers.

Add users to workspace

Required scope: workspaces:write

The add_users_to_workspace mutation adds users to a workspace via the API. You can specify which fields to return in the mutation response.

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

You can use the following arguments to define 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 users' unique identifiers.
workspace_id `ID!`	The workspace's unique identifier.

Activate users

The activate_users mutation activates or reactivates users in a monday.com account via the API. It returns the ActivateUsersResult type which allows you to specify which fields to return in the mutation response.

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

You can use the following argument to specify which users to activate.

Argument	Description
user_ids `[ID!]!`	The users' unique identifiers. The maximum is 200.

Invite users

The invite_users mutation invites users to join a monday.com account via the API. They will remain in a pending status until the invitation is accepted.

It returns the InviteUsersResult type which allows you to specify which fields to return in the mutation response.

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

You can use the following arguments to specify which users to invite to the account.

Argument	Description	Enum Values
emails `[String!]!`	The users' emails.
product `Product`	The product to invite the user to.	`crm` `dev` `forms` `knowledge` `service` `whiteboard` `workflows` `work_management`
user_role `UserRole`	The invited user's new role.	`ADMIN` `GUEST` `MEMBER` `VIEW_ONLY`

Update multiple users

The update_multiple_users mutation updates one or multiple users' attributes via the API. It returns the UpdateUserAttributesResult type which allows you to specify which fields to return in the mutation response.

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

You can use the following argument to specify which users to update.

Argument	Description	Supported Fields
user_updates `[UserUpdateInput!]!`	The unique identifiers and attributes to update.	user_attribute_updates `UserAttributesInput!` user_id `ID!`

Update email domain

The update_email_domain mutation updates a user's email domain via the API. It returns the UpdateEmailDomainResult type which allows you to specify which fields to return in the mutation response.

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

Arguments

You can use the following argument to specify the users' emails to update.

Argument	Description	Supported Fields
input `UpdateEmailDomainAttributesInput!`	The attributes to update.	new_domain `String!` user_ids `[ID!]!`

Update user's role

The update_users_role mutation updates a user's role (accepts both custom or default roles) via the API. It returns the UpdateUsersRoleResult type which allows you to specify which fields to return in the mutation response.

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

You can use the following argument to specify the users' roles to update.

Argument	Description	Enum Values
new_role `BaseRoleName`	The user's updated role. Only used to update default roles, not custom ones (read more here).	`ADMIN` `GUEST` `MEMBER` `VIEW_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

The delete_subscribers_from_board mutation deletes subscribers from a board via the API. You can specify which fields to return in the mutation response.

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

You can use the following arguments to specify which subscribers to delete from the board.

Argument	Description
board_id `ID!`	The board's unique identifier.
user_ids `[ID!]!`	The users' unique identifiers.

Remove users from team

The remove_users_from_team mutation removes users from a team via the API. It returns the ChangeTeamMembershipResult type which allows you to specify which fields to return in the mutation response.

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

You can use the following arguments to specify which users to remove from the team.

Argument	Description
team_id `ID!`	The team's unique identifier.
user_ids `[ID!]!`	The users' unique identifiers.

Delete users from workspace

Required scope: workspaces:write

The delete_users_from_workspace mutation deletes users from a workspace via the API. You can specify which fields to return in the mutation response.

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

You can use the following arguments to specify which users to delete from the workspace.

Arguments	Description
user_ids `[ID!]!`	The users' unique identifiers.
workspace_id `ID!!`	The workspace's unique identifier.

Deactivate users

The deactivate_users mutation deactivates users from a monday.com account via the API. It returns the DeactivateUsersResult type which allows you to specify which fields to return in the mutation response.

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

You can use the following argument to specify which users to deactivate.

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