---
title: "List users"
method: GET
path: "/users"
tags: ["users"]
---
# List users
`GET /users`
Gets a list of users in the organization account. To filter by email, use the optional email query string parameter to specify a list of users' email addresses.
For **System admins**, the following User object attributes are included in the response (else, they are omitted from the response):
* **admin**
* **groupAdmin**
* **isInternal**
* **licensedSheetCreator**
* **resourceViewer**
* **seatType** - Shows when you specify either or both the `planId` and `seatType` query parameters.
* **seatTypeLastChangedAt**
* **sheetCount** (SUNSET) - The `sheetCount` attribute now holds the value `-1` and is included only if the retrieved user's `status` is `ACTIVE`.
* **status**
> **Note:** If the API request is submitted by a **System Admin** of an **Enterprise account**, and Custom Welcome Screen is enabled, the following [User object](/api/smartsheet/openapi/users/user) attributes are included in the response (else, they are omitted from the response):
>
> **customWelcomeScreenViewed** (omitted if the user has never viewed the Custom Welcome Screen)
> **Note:** For pagination guidance, refer to [Pagination](/api/smartsheet/guides/basics/pagination).
## Query parameters
- `email` string
- `include` 'lastLogin'
- `includeAll` boolean
- `numericDates` boolean
- `planId` integer
- `displayContributorSeatType` boolean
- `seatType` 'MEMBER' | 'PROVISIONAL_MEMBER' | 'GUEST' | 'CONTRIBUTOR' | 'VIEWER'
- `page` number
- `pageSize` number
## Response `200`
IndexResult object containing an array of [User objects](/api/smartsheet/openapi/users/user).
**Note:** For pagination guidance, refer to [Pagination](/api/smartsheet/guides/basics/pagination).
- object
- `pageNumber` number — The current page in the full result set that the data array represents. NOTE when a page number greater than totalPages is requested, the last page is instead returned.
- `pageSize` number, nullable — The number of items in a page. Omitted if there is no limit to page size (and hence, all results are included). Unless otherwise specified, this defaults to 100 for most endpoints.
- `totalPages` number — The total number of pages in the full result set.
- `totalCount` number — The total number of items in the full result set.
- `data` User[] — List of User Objects
- `id` number — User ID.
- `admin` boolean — Indicates whether the user is a system admin (can manage user accounts and organization account).
- `customWelcomeScreenViewed` string, date-time — Timestamp of viewing an Enterprise Custom Welcome Screen by the current user.
- `email` string, email — User's primary email address.
- `firstName` string — User's first name.
- `groupAdmin` boolean — Indicates whether the user is a group admin (can create and edit groups).
- `isInternal` boolean — Indicates whether the user is internal to the plan's domain. **Note:** It's present only when a `planId` query parameter is supplied.
- `lastLogin` string, date-time — The timestamp of the user's last login to Smartsheet. This property is only included in the response when **all** of the following conditions are met: - The `include=lastLogin` query parameter is present - The user has logged in to Smartsheet at least once - The caller has System Admin permissions - The total number of users in the response is 100 or fewer This property is **excluded from the response** if **any** of the following conditions apply: - The `includeAll=true` query parameter is present - The `planId` query parameter is present - The `seatType` query parameter is present - The `pageSize` query parameter is set to a value greater than 100
- `lastName` string — User's last name.
- `licensedSheetCreator` boolean — Indicates whether the user is a licensed user (can create and own sheets). **Note:** On user model plans, the [`POST /users`](/api/smartsheet/openapi/users/add-user) operation sets `licensedSheetCreator` to `true`, regardless of the value provided in the request body.
- `name` string — User's full name (read-only).
- `profileImage` ProfileImage
- `imageId` string — Unique image ID.
- `height` integer — Image height.
- `width` integer — Image width.
- `provisionalExpirationDate` string, date-time, nullable — The expiration timestamp of the user's provisional seat type. It's null if the user doesn't have a `PROVISIONAL_MEMBER` seat type. **Note:** It's present only when a `planId` query parameter is supplied.
- `resourceViewer` boolean — Indicates whether the user is a resource viewer (can access resource views).
- `seatType` 'MEMBER' | 'PROVISIONAL_MEMBER' | 'CONTRIBUTOR' | 'GUEST' | 'VIEWER' — User's seat type. **Note:** It's only present when **either or both** the `planId` and `seatType` query parameters are supplied (available to system admins only). **DEPRECATED - As early as the sunset date specified in this [changelog entry](/api/smartsheet/changelog#deprecated-viewer-seat-type-in-favor-of-contributor-new), `VIEWER` will be removed and replaced by `CONTRIBUTOR` for all free-tier plans users.** Commenting and attachments are free to the `CONTRIBUTOR` seat type.
- `seatTypeLastChangedAt` string, date-time — Timestamp of the user's last seat type change. **Note:** It's only present when **either or both** the `planId` and `seatType` query parameters are supplied (available to system admins only).
- `sheetCount` number — **SUNSET** - The `sheetCount` attribute now holds the value `-1` and is included only if the retrieved user's `status` is `ACTIVE`.
- `status` 'ACTIVE' | 'DECLINED' | 'PENDING' | 'DEACTIVATED' — User status, set to one of the listed enum values.
## Other responses
- `default` — Generic Error Payload
---
[API](https://skmtc.net/smartsheet/apis/smartsheet-openapi-reference.md) · [All operations](https://skmtc.net/smartsheet/apis/smartsheet-openapi-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smartsheet/smartsheet-openapi-reference/versions/b4afda95fb51/schema)