REST API: List Users

Last Updated: September 08, 2017

Description

Retrieves a list of all users associated with your company, with optional filters to narrow down the results.

Resource Information

HTTP Method GET
Endpoint https://rest.tsheets.com/api/v1/users
Authentication Token header required. See authentication section
Request format Everything is handled through the request uri on a GET.
Response format json
Response object User

Available Filters

ids:
optional
Integer. Comma separated list of one or more user ids you'd like to filter on.
not_ids:
optional
Integer. Comma separated list of one or more user ids you'd like to filter on. Specifically, the user ids you'd like to exclude.
employee_numbers:
optional
Integer. Comma separated list of one or more employee numbers you'd like to filter on.
usernames:
optional
String. Comma separated list of one or more usernames you'd like to filter on.
group_ids:
optional
Integer. Comma separated list of one or more group ids you'd like to filter on.
not_group_ids:
optional
Integer. Comma separated list of one or more group ids you'd like to filter on. Specifically, the group ids you'd like to exclude.
active:
optional
String. 'yes', 'no', or 'both'. Default is 'yes'.
first_name:
optional
String. * will be interpreted as a wild card. Starts matching from the beginning of the string.
last_name:
optional
String. * will be interpreted as a wild card. Starts matching from the beginning of the string.
modified_before:
optional
String (ISO8601 format). Only users modified before this date/time will be returned (i.e. 2004-02-12T15:19:21+00:00).
modified_since:
optional
String (ISO8601 format). Only users modified since this date/time will be returned (i.e. 2004-02-12T15:19:21+00:00).
supplemental_data:
optional
String. 'yes' or 'no'. Default is 'yes'. Indicates whether supplemental data should be returned.
per_page:
optional
Integer. Represents how many results you'd like to retrieve per request (page). Default is 50. Max is 50.
page:
optional
Integer. Represents the page of results you'd like to retrieve. Default is 1.

Examples

Retrieve a list of all active users.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/users"

## RESPONSE (shortened for readability)
HTTP/1.1 200 OK
Content-Type: application/json

{
 "results": {
  "users": {
   "1283037": {
    "id": 1283037,
    "first_name": "Joni",
    "last_name": "Smith",
    "group_id": 0,
    "active": true,
    "employee_number": 0,
    "salaried": false,
    "exempt": false,
    "username": "joni",
    "email": "",
    "payroll_id": "",
    "hire_date": "0000-00-00",
    "term_date": "0000-00-00",
    "job_title": "",
    "gender": "",
    "last_modified": "2013-07-12T17:24:33+00:00",
    "last_active": "",
    "created": "2013-07-12T17:24:33+00:00",
    "client_url": "tsheetstest",
    "mobile_number": "",
    "pto_balances": {
        "8234": 0,
        "424242": 144000,
        "123": 3600
    },
    "require_password_change": false,
    "pay_rate": 20,
    "pay_interval": "hour",
    "permissions": {
     "admin": false,
     "mobile": false,
     "status_box": false,
     "reports": false,
     "manage_timesheets": false,
     "manage_authorization": false,
     "manage_users": false,
     "manage_my_timesheets": false,
     "manage_jobcodes": false,
     "approve_timesheets": false,
     "manage_no_schedules": false,
     "manage_my_schedule": false,
     "manage_schedules": true,
     "manage_company_schedules": false,
     "view_my_schedules": false,
     "view_group_schedules": false,
     "view_company_schedules": false
    }
   },
   "1283039": {
    "id": 1283039,
    "first_name": "Frank",
    "last_name": "Church",
    ...
   }
  }
 },
 "more": false,
 "supplemental_data": {
  "groups": {
   "144959": {
    "id": 144959,
    "name": "test3",
    "last_modified": "2013-07-12T15:32:25+00:00",
    "created": "2013-07-12T15:32:25+00:00"
   }
  }
 }
}
    

Retrieve a list of all users (active or deleted) whose last name starts with 'sm'. Set pagination to 30 results/page.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/users?per_page=30&last_name=sm*"

## RESPONSE
## (response would have the same layout as the above example)