Sign in

v1

latestOpenAPI 3.0.32026-08-061874701.5 MB
users

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 <a href="https://help.smartsheet.com/articles/1392225-customizing-a-welcome-message-upgrade-screen-enterprise-only" target="_blank" rel="noopener noreferrer">Custom Welcome Screen</a> 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 <a href="https://help.smartsheet.com/articles/1392225-customizing-a-welcome-message-upgrade-screen-enterprise-only" target="_blank" rel="noopener noreferrer">Custom Welcome Screen</a>)

Note: For pagination guidance, refer to Pagination.

get/users

Query parameters

emailstring

Comma-separated list of email addresses on which to filter the results.

include'lastLogin'

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
includeAllboolean

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

numericDatesboolean

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.

planIdinteger
Example:4843937635559300

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

displayContributorSeatTypeboolean
Example:true

When true and there's no seatType filter, it displays seatType as CONTRIBUTOR for all free-tier plans users.

seatType'MEMBER' | 'PROVISIONAL_MEMBER' | 'GUEST' | 'CONTRIBUTOR' | 'VIEWER'
Example:MEMBER

Seat type based on which to filter the results.

This query parameter is only available to system administrators

DEPRECATED - As early as the sunset date specified in this changelog entry, VIEWER will be removed and replaced by CONTRIBUTOR for all free-tier plans users. Commenting and attachments are free to the CONTRIBUTOR seat type.

pagenumber

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.

pageSizenumber

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

IndexResult object containing an array of User objects.

Note: For pagination guidance, refer to Pagination.

pageNumbernumber

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.

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

totalPagesnumber

The total number of pages in the full result set.

totalCountnumber

The total number of items in the full result set.

Example response

{
  "pageNumber": 1,
  "pageSize": 50,
  "totalPages": 25,
  "totalCount": 136,
  "data": [
    {
      "id": 48569348493401200,
      "admin": true,
      "customWelcomeScreenViewed": "2020-08-25T12:15:47Z",
      "email": "jane.doe@smartsheet.com",
      "firstName": "Jane",
      "groupAdmin": true,
      "isInternal": true,
      "lastLogin": "2020-10-04T18:32:47Z",
      "lastName": "Doe",
      "licensedSheetCreator": true,
      "name": "Jane Doe",
      "profileImage": {
        "imageId": "u!1!nAtdn5RJB_o!k6_e_3h2R3w!wmYXPek-yVD",
        "height": 1050,
        "width": 1050
      },
      "provisionalExpirationDate": "2025-06-14T09:55:30Z",
      "resourceViewer": true,
      "seatType": "PROVISIONAL_MEMBER",
      "seatTypeLastChangedAt": "2025-06-14T09:55:30Z",
      "sheetCount": -1,
      "status": "ACTIVE"
    }
  ]
}