REST API: Payroll Report

Last Updated: February 24, 2016

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.

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": {}
        }
       }
    }
}
        

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"
  }
}


## 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": ""
   }
  }
 }
}