# List 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
* 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 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.

Endpoint: GET /users
Version: 2.0.0
Security: APIToken, OAuth2

## Header parameters:

  - `Authorization` (string)
    API Access Token used to authenticate requests to Smartsheet APIs.

  - `smartsheet-integration-source` (string)
    Uses the following metadata to distinguish between human-initiated API requests and third-party service-initiated calls by AI Connectors or ITSM:

- Integration source type
- Organization name
- Integration source name 

Format:


TYPE,OrgName,SourceName


Examples: 

AI,SampleOrg,My-AI-Connector-v2

SCRIPT,SampleOrg2,Accounting-updater-script

APPLICATION,SampleOrg3,SheetUpdater
    Example: "AI,SampleOrg,My-AI-Connector-v2"

## Query parameters:

  - `email` (string)
    Comma-separated list of email addresses on which to filter the results.

  - `include` (string)
    If the API request is submitted by a system administrator and when specified with a value of 'lastLogin', response includes a lastLogin attribute for each user that indicates the Last login date/time of the user.

Note If the number of users included in the response is > 100, you must paginate your query to see the lastLogin attribute. For large responses, the lastLogin attribute is never included.

  - `includeAll` (boolean)
    If true, include all results, that is, do not paginate. Mutually exclusive with page and pageSize (they are ignored if includeAll=true is specified).

  - `numericDates` (boolean)
    You can optionally choose to receive and send dates/times in numeric format, as milliseconds since the UNIX epoch (midnight on January 1, 1970 in UTC time), using the query string parameter numericDates with a value of true. This query parameter works for any API request.

  - `planId` (integer)
    Plan ID for which seat types are returned. Adding this query parameter returns users with their seat types associated to the selected planId. As a result the query can include users external to the organization.

* _This query parameter is only available to system administrators_
    Example: 4843937635559300

  - `seatType` (string)
    Seat type based on which to filter the results.
    Enum: "MEMBER", "PROVISIONAL_MEMBER", "GUEST", "VIEWER"

  - `page` (number)
    Which page to return. Defaults to 1 if not specified. If you specify a value greater than the total number of pages, the last page of results is returned.

  - `pageSize` (number)
    The maximum number of items to return per page. Unless otherwise stated for a specific endpoint, defaults to 100. If only page is specified, defaults to a page size of 100. For reports, the default is 100 rows. If you need larger sets of data from your report, returns a maximum of 10,000 rows per request.

## Response 200 fields (application/json):

  - `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.
    Example: 1

  - `pageSize` (number,null)
    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.
    Example: 50

  - `totalPages` (number)
    The total number of pages in the full result set.
    Example: 25

  - `totalCount` (number)
    The total number of items in the full result set.
    Example: 136

  - `data` (array)
    List of User Objects

  - `data.id` (number)
    User ID.
    Example: 48569348493401200

  - `data.admin` (boolean)
    Indicates whether the user is a system admin (can manage user accounts and organization account).
    Example: true

  - `data.customWelcomeScreenViewed` (string)
    Timestamp of viewing an Enterprise Custom Welcome Screen by the current user.
    Example: "2020-08-25T12:15:47Z"

  - `data.email` (string)
    User's primary email address.
    Example: "jane.doe@smartsheet.com"

  - `data.firstName` (string)
    User's first name.
    Example: "Jane"

  - `data.groupAdmin` (boolean)
    Indicates whether the user is a group admin (can create and edit groups).
    Example: true

  - `data.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.
    Example: true

  - `data.lastLogin` (string)
    Last login time of the current user.
    Example: "2020-10-04T18:32:47Z"

  - `data.lastName` (string)
    User's last name.
    Example: "Doe"

  - `data.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.
    Example: true

  - `data.name` (string)
    User's full name (read-only).
    Example: "Jane Doe"

  - `data.profileImage` (object)

  - `data.profileImage.imageId` (string)
    Unique image ID.
    Example: "u!1!nAtdn5RJB_o!k6_e_3h2R3w!wmYXPek-yVD"

  - `data.profileImage.height` (integer)
    Image height.
    Example: 1050

  - `data.profileImage.width` (integer)
    Image width.
    Example: 1050

  - `data.provisionalExpirationDate` (string,null)
    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.
    Example: "2025-06-14T09:55:30Z"

  - `data.resourceViewer` (boolean)
    Indicates whether the user is a resource viewer (can access resource views).
    Example: true

  - `data.seatType` (string)
    User's seat type. 

Note: It's present only when a planId query parameter is supplied.
    Enum: "MEMBER", "PROVISIONAL_MEMBER", "GUEST", "VIEWER"

  - `data.seatTypeLastChangedAt` (string)
    Timestamp of the user's last seat type change. 

Note: It's present only when a planId query parameter is supplied.
    Example: "2025-06-14T09:55:30Z"

  - `data.status` (string)
    User status, set to one of the listed enum values.
    Enum: "ACTIVE", "DECLINED", "PENDING", "DEACTIVATED"

  - `data.sheetCount` (number)
    SUNSET - The sheetCount attribute now holds the value -1 and is included only if the retrieved user's status is ACTIVE.
    Example: -1

## Response default fields (application/json):

  - `refId` (string)
    The ID of the specific error occurrence. Please include this information when contacting Smartsheet support.

  - `errorCode` (number)
    Custom error code from Smartsheet. See the complete [Error Code List](/api/smartsheet/error-codes).

  - `message` (string)
    Descriptive error message.