REST API: Add Groups

Last Updated: May 16, 2017

Description

Add one or more groups to 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 POST
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

Required Group Properties

name:
String. Name of the group.

Optional Group Properties

For a full list of the properties, see the Group object.

Status Codes

Each group that is created will come back with a _status_code and _status_message that will indicate whether the group was created successfully. If there was a problem creating 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 created 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

Create two new groups.

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

## contents of the tsgroup_create.json file are:
{
 "data":
  [
    {
     "name":"Group 1",
     "manager_ids":"300, 316"
    },
    {
     "name":"Group 2",
     "manager_ids":"316"
    }
  ]
}



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

{
  "results": {
    "groups": {
      "1": {
        "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"
        ]
      },
      "2": {
        "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"
        ]
      }
    }
  },
  "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": false,
          "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": false,
          "manage_company_schedules": false,
          "view_my_schedules": false,
          "view_group_schedules": false,
          "view_company_schedules": false
        }
      }
    }
  }
}