REST API: Edit Users

Last Updated: May 16, 2017

Description

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

Resource Information

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

User properties

When editing a user, you must uniquely identify the user by passing in either the user's id or username property. All other properties defined on a user 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 user that is edited will come back with a _status_code and _status_message that will indicate whether the user was edited successfully. If there was a problem editing a user, there may also be an additional field, _status_extra, which will contain more details about the failure.

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

Examples

Change the last name for each of these employees, and add the mobile permission to the second one.
Note: For the example below you would need to substitute the sample user_id to match a user 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/users" -d @tsuser_edit.json 

## contents of the tsuser_edit.json file are:
{
 "data":
  [
    {
     "id":"1283037",
     "last_name":"Allen"
    },
    {
     "username":"frank",
     "last_name":"Smith",
     "permissions": {
      "mobile": true
     }
    }
  ]
}



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

{
 "results": {
  "users": {
   "1": {
    "_status_code": 200,
    "_status_message": "Updated",
    "id": 1283037,
    "first_name": "Joni",
    "last_name": "Allen",
    "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-12T18:56:39+00:00",
    "last_active": "",
    "created": "2013-07-12T17:24:33+00:00",
    "mobile_number": "",
    "require_password_change": false,
    "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
    }
   },
   "2": {
    "_status_code": 200,
    "_status_message": "Updated",
    "id": 1283039,
    "first_name": "Frank",
    "last_name": "Smith",
    "group_id": 0,
    "active": true,
    "employee_number": 0,
    "salaried": false,
    "exempt": false,
    "username": "frank",
    "email": "",
    "payroll_id": "",
    "hire_date": "0000-00-00",
    "term_date": "0000-00-00",
    "job_title": "",
    "gender": "",
    "last_modified": "2013-07-12T18:50:08+00:00",
    "last_active": "",
    "created": "2013-07-12T17:24:33+00:00",
    "mobile_number": "",
    "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
    }
   }
  }
 }
}