REST API: List Groups

Last Updated: May 16, 2017

Description

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

Resource Information

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

Available Filters

ids:
optional
Integer. Comma separated list of one or more group ids you'd like to filter on.
active:
optional
String. 'yes', 'no', or 'both'. Default is 'yes'.
manager_ids:
optional
Integer. Comma separated list of one or more manager ids you'd like to filter on.
name:
optional
String. Comma separated list of one or more group names you'd like to filter on.
modified_before:
optional
String (ISO8601 format). Only groups modified before this date/time will be returned (i.e. 2004-02-12T15:19:21+00:00).
modified_since:
optional
String (ISO8601 format). Only groups 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.

Examples

Retrieve a list of all active groups.

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

## RESPONSE
HTTP/1.1 200 OK
Content-Type: application/json

{
  "results": {
    "groups": {
      "6": {
        "id": 6,
        "name": "Group 1",
        "last_modified": "2015-08-19T16:29:28+00:00",
        "created": "2015-08-19T16:29:28+00:00",
        "manager_ids": [
          "300",
          "316"
        ]
      },
      "8": {
        "id": 8,
        "name": "Group 2",
        "last_modified": "2015-08-19T16:29:35+00:00",
        "created": "2015-08-19T16:29:35+00:00",
        "manager_ids": [
          "316"
        ]
      },
      "16": {
        "id": 16,
        "name": "Group 3",
        "last_modified": "2015-08-20T23:22:13+00:00",
        "created": "2015-08-20T23:22:13+00:00",
        "manager_ids": []
      }
    }
  },
  "more": false,
  "supplemental_data": {
    "users": {
      "300": {
        "id": 300,
        "first_name": "Joseph",
        "last_name": "",
        "group_id": 0,
        "active": true,
        "employee_number": 0,
        "salaried": false,
        "exempt": false,
        "username": "joseph@example.com",
        "email": "joseph@example.com",
        "payroll_id": "",
        "hire_date": "0000-00-00",
        "term_date": "0000-00-00",
        "last_modified": "2015-08-20T15:55:26+00:00",
        "last_active": "2015-08-24T15:43:46+00:00",
        "created": "2015-08-17T17:31:12+00:00",
        "client_url": "joseph",
        "company_name": "joseph",
        "mobile_number": "",
        "pto_balances": {
          "8606": 0,
          "8608": 0,
          "8610": 0,
          "8770": 0
        },
        "approved_to": "",
        "submitted_to": "",
        "manager_of_group_ids": [
          6
        ],
        "require_password_change": false,
        "permissions": {
          "admin": true,
          "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
        }
      },
      "316": {
        "id": 316,
        "first_name": "Bill",
        "last_name": "Franklin",
        "group_id": 0,
        "active": true,
        "employee_number": 0,
        "salaried": false,
        "exempt": false,
        "username": "bill",
        "email": "",
        "payroll_id": "",
        "hire_date": "0000-00-00",
        "term_date": "0000-00-00",
        "last_modified": "2015-08-20T15:57:14+00:00",
        "last_active": "",
        "created": "2015-08-20T15:56:48+00:00",
        "client_url": "bfrank",
        "company_name": "bfrank",
        "mobile_number": "",
        "pto_balances": {
          "8606": 0,
          "8608": 0,
          "8610": 0,
          "8770": 0
        },
        "approved_to": "",
        "submitted_to": "",
        "manager_of_group_ids": [
          6,
          8
        ],
        "require_password_change": false,
        "permissions": {
          "admin": false,
          "mobile": true,
          "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
        }
      }
    }
  }
}
    

Retrieve a list of groups with an id of 6 or 16. Set pagination to 30 results/page.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/groups?ids=6,16&per_page=30"

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