REST API: Edit Users

Last Updated: July 27, 2018

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:
[
  {
    "id": "933849",
    "first_name": "Mary",
    "last_name": "Samsonite"
  },
  {
    "username": "nancysmith",
    "permissions": {
      "mobile": true
    }
  }
]

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

{
 "results": {
  "users": {
   "1": {
    "_status_code": 200,
    "_status_message": "Updated",
    "id": 933849,
    "first_name": "Mary",
    "last_name": "Samsonite",
    "group_id": 0,
    "active": true,
    "employee_number": 0,
    "salaried": false,
    "exempt": false,
    "username": "admin",
    "email": "admin@example.com",
    "email_verified": false,
    "payroll_id": "",
    "hire_date": "0000-00-00",
    "term_date": "0000-00-00",
    "last_modified": "2018-03-28T17:24:20+00:00",
    "last_active": "",
    "created": "2018-03-27T16:13:34+00:00",
    "client_url": "api_sample_output",
    "company_name": "API Sample Output Company",
    "profile_image_url": "https:\/\/www.gravatar.com\/avatar\/e64c7d89f26bd1972efa854d13d7dd61",
    "mobile_number": "2087231456",
    "pto_balances": {
     "2624351": 0,
     "2624353": 0,
     "2624355": 0
    },
    "submitted_to": "2000-01-01",
    "approved_to": "2000-01-01",
    "manager_of_group_ids": [
     
    ],
    "require_password_change": false,
    "pay_rate": 0,
    "pay_interval": "hour",
    "permissions": {
     "admin": true,
     "mobile": true,
     "status_box": false,
     "reports": false,
     "manage_timesheets": false,
     "manage_authorization": false,
     "manage_users": false,
     "manage_my_timesheets": false,
     "manage_jobcodes": false,
     "pin_login": false,
     "approve_timesheets": false,
     "manage_schedules": false,
     "external_access": false,
     "manage_my_schedule": false,
     "manage_company_schedules": false,
     "view_company_schedules": false,
     "view_group_schedules": false,
     "manage_no_schedules": false,
     "view_my_schedules": false
    },
    "customfields": ""
   },
   "2": {
    "_status_code": 200,
    "_status_message": "Updated",
    "id": 933837,
    "first_name": "Nancy",
    "last_name": "Smith",
    "group_id": 64965,
    "active": true,
    "employee_number": 0,
    "salaried": false,
    "exempt": false,
    "username": "nancysmith",
    "email": "",
    "email_verified": false,
    "payroll_id": "",
    "hire_date": "0000-00-00",
    "term_date": "0000-00-00",
    "last_modified": "2018-03-28T20:16:46+00:00",
    "last_active": "2018-03-28T20:16:39+00:00",
    "created": "2018-03-27T16:13:30+00:00",
    "client_url": "api_sample_output",
    "company_name": "API Sample Output Company",
    "profile_image_url": "",
    "mobile_number": "",
    "pto_balances": {
     "2624351": 0,
     "2624353": 0,
     "2624355": 0
    },
    "submitted_to": "2000-01-01",
    "approved_to": "2000-01-01",
    "manager_of_group_ids": [
     
    ],
    "require_password_change": false,
    "pay_rate": 0,
    "pay_interval": "hour",
    "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,
     "pin_login": false,
     "approve_timesheets": false,
     "manage_schedules": false,
     "external_access": false,
     "manage_my_schedule": false,
     "manage_company_schedules": false,
     "view_company_schedules": false,
     "view_group_schedules": false,
     "manage_no_schedules": false,
     "view_my_schedules": false
    },
    "customfields": ""
   }
  }
 },
 "supplemental_data": {
  "jobcodes": {
   "2624351": {
    "id": 2624351,
    "parent_id": 0,
    "assigned_to_all": true,
    "billable": false,
    "active": true,
    "type": "pto",
    "has_children": false,
    "billable_rate": 0,
    "short_code": "",
    "name": "Sick",
    "last_modified": "2018-03-27T16:13:28+00:00",
    "created": "2018-03-27T16:13:28+00:00",
    "filtered_customfielditems": "",
    "required_customfields": [
     
    ],
    "locations": [
     
    ]
   },
   "2624353": {
    "id": 2624353,
    "parent_id": 0,
    "assigned_to_all": true,
    "billable": false,
    "active": true,
    "type": "pto",
    "has_children": false,
    "billable_rate": 0,
    "short_code": "",
    "name": "Vacation",
    "last_modified": "2018-03-27T16:13:28+00:00",
    "created": "2018-03-27T16:13:28+00:00",
    "filtered_customfielditems": "",
    "required_customfields": [
     
    ],
    "locations": [
     
    ]
   },
   "2624355": {
    "id": 2624355,
    "parent_id": 0,
    "assigned_to_all": true,
    "billable": false,
    "active": true,
    "type": "pto",
    "has_children": false,
    "billable_rate": 0,
    "short_code": "",
    "name": "Holiday",
    "last_modified": "2018-03-27T16:13:28+00:00",
    "created": "2018-03-27T16:13:28+00:00",
    "filtered_customfielditems": "",
    "required_customfields": [
     
    ],
    "locations": [
     
    ]
   }
  },
  "groups": {
   "64965": {
    "id": 64965,
    "active": true,
    "name": "Construction",
    "last_modified": "2018-03-27T16:13:30+00:00",
    "created": "2018-03-27T16:13:29+00:00",
    "manager_ids": [
     "933833"
    ]
   }
  }
 }
}