REST API: Payroll Report

Last Updated: October 25, 2017

Description

Retrieves a payroll report associated with a timeframe, with filters to narrow down the results.

Resource Information

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

Available Filters

start_date:
required
String. YYYY-MM-DD formatted date. Any time with a date falling on or after this date will be included.
end_date:
required
String. YYYY-MM-DD formatted date. Any time with a date falling on or before this date will be included.
user_ids:
optional
Integer. A comma-separated list of user ids. Only time for these users will be included.
group_ids:
optional
Integer. A comma-seperated list of group ids. Only time for users from these groups will be included.
include_zero_time:
optional
String. 'yes' or 'no'. Default is 'no'. If 'yes', all users will be included in the output, even if they had zero hours for the time period.
advanced_overtime:
optional / required (see below)
String. 'yes' or 'no'. If 'yes', overtime will be formatted such that it includes the time for individual multipliers and can support more than just 1.5x (ot) and 2x (dt) overtime.
The default for api keys created before Oct 25th 2017 is 'no', however, the default for api keys created after this date is 'yes' and attempting to pass this parameter with a value of 'no' will result in an exception.
NOTE: This setting is required to be passed as 'yes' if the Overtime add-on is installed and rates other than the standard 1.5x and 2x rates are defined. This is enforced so that incorrect overtime values that do not comply with the standard "total_ot_seconds" (1.5x) and "total_dt_seconds" (2x) rates are not missed.

Understanding the Output

The best way to understand how the output is laid out is to look at some sample output - with comments out to the side explaining things.

{
    "results": {
      "payroll_report": {
       "191544": {                           ## Indexed by user_id
        "user_id": 191544,
        "client_id": "183",
        "start_date": "2014-03-02",          ## start_date of the payroll reporting 
                                             ##   timeframe
        "end_date": "2014-03-15",            ## end_date of the payroll reporting 
                                             ##   timeframe
        "total_re_seconds": 1816,            ## Regular time, in seconds
        "total_ot_seconds": 0,               ## Overtime time, in seconds
        "total_dt_seconds": 0,               ## Doubletime time, in seconds
        "total_pto_seconds": 7200,           ## Total PTO time, in seconds
        "total_work_seconds": 1816,          ## Total overall time, in seconds
        "pto_seconds": {                     ## Break-down of PTO time by PTO code
           "123876": 7200                    ## Indexed by PTO code id, then value is 
                                             ##   the time, in seconds
        }
       },
       "31174": {
        "user_id": 31174,
        "client_id": "183",
        "start_date": "2014-03-02",
        "end_date": "2014-03-15",
        "total_re_seconds": 28800,
        "total_ot_seconds": 14400,
        "total_dt_seconds": 563645,
        "total_pto_seconds": 0,
        "total_work_seconds": 606845,
        "pto_seconds": {}
        }
       }
    }
}
        

The format with advanced overtime is as follows:

{
    "results": {
      "payroll_report": {
       "191549": {                           ## Indexed by user_id
        "user_id": 191549,
        "client_id": "188",
        "start_date": "2014-03-02",          ## start_date of the payroll reporting 
                                             ##   timeframe
        "end_date": "2014-03-15",            ## end_date of the payroll reporting 
                                             ##   timeframe
        "total_re_seconds": 1816,            ## Regular time, in seconds
        "total_pto_seconds": 7200,           ## Total PTO time, in seconds
        "total_work_seconds": 5416,          ## Total overall time, in seconds
        "pto_seconds": {                     ## Break-down of PTO time by PTO code
           "123876": 7200                    ## Indexed by PTO code id, then value is 
                                             ##   the time, in seconds
        }
        "overtime_seconds": {                ## This replaces "total_ot_seconds"
            "1.6": 3600,                     ## and "total_dt_seconds"
            "3"  : 0
        }        
       },
       "31174": {
        "user_id": 31174,
        "client_id": "188",
        "start_date": "2014-03-02",
        "end_date": "2014-03-15",
        "total_re_seconds": 28800,
        "total_pto_seconds": 0,
        "total_work_seconds": 606845,
        "pto_seconds": {}
        "overtime_seconds": {                ## With the Overtime add-on, different
            "1.5": 14400,                    ## rates can apply to different people 
            "2"  : 563645                    ## So 1.5x & 2x instead of 1.6x & 3x 
        }        
        }
       }
    }
}
        

Notice that the "total_ot_seconds" and "total_dt_seconds" has been replaced by a object called "overtime_seconds" where the key is the multiplier rate and the value is the number of seconds of overtime at that rate. (i.e 14400 seonds at 1.5x)

Examples

Retrieve a payroll report for a given time period for all users on an account.

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

## contents of the @tspayroll_report.json file are:
{
 "data":
  {
    "start_date": "2014-03-02",
    "end_date": "2014-03-15",
    "advanced_payroll": "no"
  }
}


## RESPONSE (shortened for readability)
HTTP/1.1 200 OK
Content-Type: application/json

{
 "results": {
  "payroll_report": {
   "191544": {
    "user_id": 191544,
    "client_id": "183",
    "start_date": "2014-03-02",
    "end_date": "2014-03-15",
    "total_re_seconds": 1816,
    "total_ot_seconds": 0,
    "total_dt_seconds": 0,
    "total_pto_seconds": 0,
    "total_work_seconds": 1816,
    "pto_seconds": {}
   },
   "31174": {
    "user_id": 31174,
    "client_id": "183",
    "start_date": "2014-03-02",
    "end_date": "2014-03-15",
    "total_re_seconds": 28800,
    "total_ot_seconds": 14400,
    "total_dt_seconds": 563645,
    "total_pto_seconds": 0,
    "total_work_seconds": 606845,
    "pto_seconds": {}
   },
   "15004": {
    "user_id": 15004,
    "client_id": "183",
    "start_date": "2014-03-02",
    "end_date": "2014-03-15",
    "total_re_seconds": 1819,
    "total_ot_seconds": 0,
    "total_dt_seconds": 0,
    "total_pto_seconds": 0,
    "total_work_seconds": 1819,
    "pto_seconds": {}
   },
   "29494": {
    "user_id": 29494,
    "client_id": "183",
    "start_date": "2014-03-02",
    "end_date": "2014-03-15",
    "total_re_seconds": 1806,
    "total_ot_seconds": 0,
    "total_dt_seconds": 0,
    "total_pto_seconds": 0,
    "total_work_seconds": 1806,
    "pto_seconds": {}
   },
   "29504": {
    "user_id": 29504,
    "client_id": "183",
    "start_date": "2014-03-02",
    "end_date": "2014-03-15",
    "total_re_seconds": 1815,
    "total_ot_seconds": 0,
    "total_dt_seconds": 0,
    "total_pto_seconds": 0,
    "total_work_seconds": 1815,
    "pto_seconds": {}
   },
   "29604": {
    "user_id": 29604,
    "client_id": "183",
    "start_date": "2014-03-02",
    "end_date": "2014-03-15",
    "total_re_seconds": 275,
    "total_ot_seconds": 0,
    "total_dt_seconds": 0,
    "total_pto_seconds": 28800,
    "total_work_seconds": 29075,
    "pto_seconds": {
     "12074": 28800
    }
   }
  }
 },
 "supplemental_data": {
  "users": {
   "191544": {
    "id": 191544,
    "first_name": "Harrison",
    "last_name": "Ford",
    "group_id": 4124,
    "active": true,
    "employee_number": 3333,
    "salaried": false,
    "exempt": false,
    
    ...
    
    }
   }
  },
  "jobcodes": {
   "12074": {
    "id": 12074,
    "parent_id": 0,
    "assigned_to_all": false,
    "billable": false,
    "active": true,
    "type": "pto",
    "has_children": false,
    "billable_rate": 0,
    "short_code": "",
    "name": "Holiday",
    "last_modified": "2013-03-18T17:58:52+00:00",
    "created": "2008-04-01T17:20:24+00:00",
    "required_customfields": [

    ],
    "filtered_customfielditems": ""
   }
  }
 }
}