REST API: Add Users

Last Updated: May 16, 2017

Description

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

Required User Properties

username:
String. Username that will be used by the employee to log on to TSheets.
password:
String. Password that will be used by the employee to log on to TSheets. Passwords must be a minimum of 7 characters, and must have 2 of the following: (upper, lower, numbers, symbols).
first_name:
String. First name of the employee.
last_name:
String. Last name of the employee.

Optional User Properties

For a full list of the properties that may be set on an employee, see the User object.

Status Codes

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

Create two new users.

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

## contents of the tsuser_create.json file are:
{
 "data":
  [
    {
     "username":"joni",
     "first_name":"Joni",
     "last_name":"Smith",
     "require_password_change": true,
     "password":"r@nd0m"
    },
    {
     "username":"frank",
     "first_name":"Frank",
     "last_name":"Church",
     "require_password_change": true,
     "password":"s0m4th1ng"
    }
  ]
}



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

{
 "results": {
  "users": {
   "1": {
    "_status_code": 200,
    "_status_message": "Created",
    "id": 1283037,
    "first_name": "Joni",
    "last_name": "Smith",
    "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-12T17:24:33+00:00",
    "last_active": "",
    "created": "2013-07-12T17:24:33+00:00",
    "mobile_number": "",
    "require_password_change": true,
    "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": "Created",
    "id": 1283039,
    "first_name": "Frank",
    "last_name": "Church",
    "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-12T17:24:33+00:00",
    "last_active": "",
    "created": "2013-07-12T17:24:33+00:00",
    "mobile_number": "",
    "require_password_change": true,
    "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
    }
   }
  }
 }
}