REST API: Add Users

Last Updated: July 27, 2018

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@nd420m"
    },
    {
      "username": "frank",
      "first_name": "Frank",
      "last_name": "Church",
      "require_password_change": true,
      "password": "s420m4th1ng"
    }
  ]
}



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

{
 "results": {
  "users": {
   "1": {
    "_status_code": 200,
    "_status_message": "Created",
    "id": 947725,
    "first_name": "Joni",
    "last_name": "Smith",
    "group_id": 0,
    "active": true,
    "employee_number": 0,
    "salaried": false,
    "exempt": false,
    "username": "joni",
    "email": "",
    "email_verified": false,
    "payroll_id": "",
    "hire_date": "0000-00-00",
    "term_date": "0000-00-00",
    "last_modified": "2018-03-28T20:16:44+00:00",
    "last_active": "",
    "created": "2018-03-28T20:16:44+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": true,
    "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": ""
   },
   "2": {
    "_status_code": 200,
    "_status_message": "Created",
    "id": 947727,
    "first_name": "Frank",
    "last_name": "Church",
    "group_id": 0,
    "active": true,
    "employee_number": 0,
    "salaried": false,
    "exempt": false,
    "username": "frank",
    "email": "",
    "email_verified": false,
    "payroll_id": "",
    "hire_date": "0000-00-00",
    "term_date": "0000-00-00",
    "last_modified": "2018-03-28T20:16:44+00:00",
    "last_active": "",
    "created": "2018-03-28T20:16:44+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": true,
    "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": [
     
    ]
   }
  }
 }
}