REST API: Edit Groups

Last Updated: May 16, 2017

Description

Edit one or more groups in your company. We will handle batches of up to 50 groups at a time. More than 50 groups will result in a 413 - Request entity too large error.

Resource Information

HTTP Method PUT
Endpoint https://rest.tsheets.com/api/v1/groups
Authentication Token header required. See authentication section
Request format json object. Pass an array of group objects as the value to a 'data' property (see example below).
Response format json
Response object Group

Group properties

When editing a group, you must uniquely identify the group by passing in the group's ID. All other properties defined on a group object may be passed in to the request with a new value in order to change it. If the value passed in is the same as it was previously, or if a particular property is not passed in at all, it will be ignored.

Status Codes

Each group that is edited will come back with a _status_code and _status_message that will indicate whether the group was edited successfully. If there was a problem editing a group, there may also be an additional field, _status_extra, which will contain more details about the failure.

_status_code Meaning
200 OK. Group was edited successfully.
417 Expectation Failed. Something was wrong or missing with the properties supplied for this group. See the _status_extra value for more detail.

Examples

Change the name for each of these groups, and clear the managers of the first one.
Note: For the example below you would need to substitute the sample group_id to match a group id associated with your TSheets account.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -H "Content-Type: application/json" -X PUT -i "https://rest.tsheets.com/api/v1/groups" -d @tsgroup_edit.json 

## contents of the tsgroup_edit.json file are:
{
 "data":
  [
    {
     "id": 6,
     "name":"Group 1a",
     "manager_ids":""
    },
    {
     "id": 8,
     "name":"Group 2b"
    }
  ]
}



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

{
  "results": {
    "groups": {
      "1": {
        "id": 6,
        "name": "Group 1a",
        "last_modified": "2015-08-19T16:29:28+00:00",
        "created": "2015-08-19T16:29:28+00:00",
        "manager_ids": []
      },
      "2": {
        "id": 8,
        "name": "Group 2b",
        "last_modified": "2015-08-19T16:29:35+00:00",
        "created": "2015-08-19T16:29:35+00:00",
        "manager_ids": [
          "316"
        ]
      }
    }
  },
  "more": false,
  "supplemental_data": {
    "users": {
      "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
        }
      }
    }
  }
}