# 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 - 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 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)
    Set include=lastLogin to include the lastLogin property in the response, which contains the timestamp of each user's most recent login to Smartsheet.

The lastLogin property appears in the response only when all of the following conditions are met:

- The user has logged in to Smartsheet at least once
- The caller has System Admin permissions
- The response contains 100 or fewer users

The 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
    Enum: "lastLogin"

  - `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.

_This query parameter is only available to system administrators_
    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)
    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
    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 only present when either or both the planId and seatType query parameters are supplied (available to system admins only).
    Enum: "MEMBER", "PROVISIONAL_MEMBER", "GUEST", "VIEWER"

  - `data.seatTypeLastChangedAt` (string)
    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).
    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.