# List users

Lists the accessible account users.

Endpoint: GET /users
Version: v1
Security: AuthToken

## Header parameters:

  - `Content-Type` (string, required)
    Enum: "application/json"

  - `Accept` (string, required)
    Enum: "application/json"

## Query parameters:

  - `fields` (string)
    A comma-separated list (no spaces) of additional fields to include for each user in the response. Here are the optional values: "tags", "assignments", "availabilities", "custom_field_values", "approvers"
    Example: "tags,assignments"

  - `sort_field` (string)
    A user field on which to sort the users in the response.
    Enum: "created", "updated", "first_name", "last_name", "hire_date", "termination_date"

  - `sort_order` (string)
    The order for sorting the results based on the sort_field.
    Enum: "ascending", "descending"

  - `with_archived` (boolean)
    If set to true, includes archived users.
    Example: true

  - `include_placeholders` (boolean)
    If set to true, includes placeholder users.
    Example: true

  - `include_count` (boolean)
    If set to true, includes the item count in the paging metadata.
    Example: true

  - `per_page` (integer)
    The maximum number of items to show per response page.
    Example: 100

  - `page` (integer)
    The response page to return.
    Example: 2

## Response 200 fields (application/json):

  - `paging` (object, required)

  - `paging.per_page` (integer)
    The maximum number of items to show per response page.
    Example: 100

  - `paging.page` (integer)
    The current response page number.
    Example: 1

  - `paging.previous` (string,null)
    If you're on the first page, this value is null; otherwise the value is the path and query parameters to get the previous page of items.
    Example: "/api/v1/users?per_page=1000&page=1"

  - `paging.self` (string)
    The path and query parameters to get the current page of items.
    Example: "/api/v1/users?per_page=1000&page=2"

  - `paging.next` (string,null)
    If there are more items, this value is the path and query parameters to get the next page of items; otherwise, it's null.
    Example: "/api/v1/users?per_page=1000&page=3"

  - `paging.count` (integer,null)
    The total number of items in all the pages.

  - `data` (array, required)

  - `data.id` (integer)
    Unique identifier for the resource instance.
    Example: 1234567

  - `data.first_name` (string)
    First name.
    Example: "Jane"

  - `data.last_name` (string)
    Surname.
    Example: "Doe"

  - `data.display_name` (string)
    Display name.
    Example: "Jane Doe"

  - `data.email` (string)
    Email address.
    Example: "jane.doe@smartsheet.com"

  - `data.user_type_id` (integer)
    A numeric code that specifies the user's permission level.

Permission Level Codes:

| Code | Permission level |
| ---------------- | -------------------- |
| 0                | None                 |
| 1                | Resourcing Administrator |
| 2                | Portfolio Editor     |
| 3                | Portfolio Reporter   |
| 4                | Portfolio Viewer     |
| 5                | Contractor           |
| 7                | People Scheduler     |
| 8                | Project Editor       |

> Note: Unlisted values you may encounter are for internal purposes or future use.

You may set the user_type_id to any value except 1 (Resourcing Administrator). To make a user a Resourcing Administrator, use the app.
    Enum: 0, 1, 2, 3, 4, 5, 7, 8

  - `data.billable` (boolean)
    true if the user is billable; false otherwise.
    Example: true

  - `data.hire_date` (string)
    Date (in UTC) the user was hired.
    Example: "2021-07-09T00:00:00Z"

  - `data.termination_date` (string,null)
    Date (in UTC) the user's employment was terminated.

  - `data.mobile_phone` (string)
    Cell phone number.

  - `data.office_phone` (string)
    Office phone number.

  - `data.archived` (boolean)
    true if the user has been archived; false otherwise.

> Note:
> - An account owner cannot be archived.
> - An archived user can be unarchived.

  - `data.archived_at` (string,null)
    Date the user was archived.

  - `data.account_owner` (boolean)
    true if the user is the account owner; false otherwise.

  - `data.invitation_pending` (boolean)
    true if an invitation is pending for the user; false otherwise.

  - `data.guid` (string)
    Globally Unique Identifier for the user.
    Example: "96d769c7-1b4e-4b07-8baf-5ed6f2b915aa"

  - `data.employee_number` (string)
    The user's employee number.

  - `data.role` (string)
    The user's role.
    Example: "Senior"

  - `data.discipline` (string)
    The user's field.
    Example: "Program Management"

  - `data.location` (string)
    The user's geographic location.
    Example: "Seattle"

  - `data.type` (string)
    The object type.
    Example: "User"

  - `data.license_type` (string)
    The user's license type.
    Enum: "licensed", "managed_resource"

  - `data.billability_target` (number)
    The percentage of the resource's available time (based on working days/hours settings and part-time availability) that the resource is expected to have work assigned. It's on utilization reports to compare with the actual percentage.
    Example: 100

  - `data.billrate` (integer)
    The currency amount that a resource is "billed out" to clients on an hourly basis. Bill rates are inherited from the bill rate matrix in Account Settings, but can be overridden in specific resource profiles. Bill rates are considered in Time & Fees and Budget reports.
    Example: -1

  - `data.has_login` (boolean)
    true if the user has a setup login; false otherwise.
    Example: true

  - `data.login_type` (string)
    The user's authentication method.

Possible values:

- smar - Sign in with Smartsheet
- saml - Security Assertion Markup Language
- default - Username/password authentication
    Enum: "smar", "saml", "default"

  - `data.thumbnail` (string)
    A URL to the user's profile image.

  - `data.approver_user_ids` (array)
    IDs of other users who approve this user's timesheets.
    Example: [123,456,789]

  - `data.approvee_user_ids` (array)
    IDs of other users whose timesheets this user approves.
    Example: [222,333,444]

  - `data.last_login_time` (string)
    Date
    Example: "2025-02-17T19:12:36Z"

  - `data.created_at` (string)
    Date
    Example: "2024-11-13T20:38:10Z"

  - `data.updated_at` (string)
    Date
    Example: "2024-11-13T20:38:10Z"

## Response default fields (application/json):

  - `message` (string)
    Error description.