REST API: Payroll by Jobcode Report

Last Updated: May 30, 2017

Description

Retrieves a payroll report, broken down by jobcode, with filters to narrow down the results.

Overtime (and double time) are allocated based on the jobcode they are working on at the time the thresholds are crossed. In other words, by order of occurrence.

As an example, assume that an employee works 60 hours against 3 different job codes, following this schedule: 25 hours against jobcode A, then 25 hours against jobcode B, then 10 hours against jobcode C. The report would allocate the time as follows:

JobcodeHoursRegularOvertime
A25250
B251510
C10010

Resource Information

HTTP Method POST
Endpoint https://rest.tsheets.com/api/v1/reports/payroll_by_jobcode
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.

The date range defined by start_date and end_date must not exceed 31 days.
end_date:
required
String. YYYY-MM-DD formatted date. Any time with a date falling on or before this date will be included.

The date range defined by start_date and end_date must not exceed 31 days.
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-separated list of group ids. Only time for users from these groups will be included.

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": {
    "filters": {                                    ## The query parameters (passed in to
                                                    ## the API)
      "start_date": "2017-03-12",                   ## Start date for the report
      "end_date": "2017-03-18",                     ## End date for the report
      "user_ids": [                                 ## Array of user IDs to include in the
        "15790",                                    ## report. If not present, all users
        "76108",                                    ## will be included.
        "76124"
      ]
    },
    "payroll_by_jobcode_report": {                  ## The report section of the output
      "totals": {                                   ## Overall totals for each jobcode
                                                    ## contained in the report
        "82026": {                                  ## Jobcode
          "jobcode_id": 82026,                      ## Jobcode ID
          "total_re_seconds": 0,                    ## Total regular seconds for this
                                                    ## jobcode
          "total_ot_seconds": 0,                    ## Total overtime seconds for this
                                                    ## jobcode
          "total_dt_seconds": 0,                    ## Total double time seconds for this
                                                    ## jobcode
          "total_pto_seconds": 28800,               ## Total PTO seconds for this jobcode
          "total_work_seconds": 28800               ## Total number of seconds for this
        },                                          ## jobcode
        "733512": {
          "jobcode_id": 733512,
          "total_re_seconds": 57600,
          "total_ot_seconds": 18300,
          "total_dt_seconds": 0,
          "total_pto_seconds": 0,
          "total_work_seconds": 75900
        }
      },
      "by_user": {                                  ## Totals, by user, section
        "15790": {                                  ## User
          "user_id": 15790,                         ## User ID
          "totals": {                               ## Totals for each jobcode, for this
                                                    ## user
            "82026": {                              ## Jobcode
              "jobcode_id": 82026,                  ## Jobcode ID
              "total_re_seconds": 0,
              "total_ot_seconds": 0,
              "total_dt_seconds": 0,
              "total_pto_seconds": 28800,
              "total_work_seconds": 28800
            },
            "733512": {
              "jobcode_id": 733512,
              "total_re_seconds": 57600,
              "total_ot_seconds": 18300,
              "total_dt_seconds": 0,
              "total_pto_seconds": 0,
              "total_work_seconds": 75900
            }
          },
          "dates": {                                ## Totals, by date for this user
            "2017-03-15": {                         ## Date
              "82026": {                            ## Jobcode
                "jobcode_id": 82026,                ## Jobcode ID
                "total_re_seconds": 0,
                "total_ot_seconds": 0,
                "total_dt_seconds": 0,
                "total_pto_seconds": 28800,
                "total_unpaid_seconds": 0,
                "total_work_seconds": 28800
              },
              "733512": {
                "jobcode_id": 733512,
                "total_re_seconds": 28800,
                "total_ot_seconds": 8340,
                "total_dt_seconds": 0,
                "total_pto_seconds": 0,
                "total_unpaid_seconds": 0,
                "total_work_seconds": 37140
              }
            }
          }
        }
      }
    }
  }
}
        

Examples

Retrieve a payroll report, broken down by jobcode, for the given time period within an account.

                
## REQUEST
curl -H "Authorization: Bearer " -H "Content-Type: application/json" -X POST -i "https://rest.tsheets.com/api/v1/reports/payroll_by_jobcode" -d @tspayrollbyjobcode.json

## contents of the @tspayrollbyjobcode.json file are:
{
    "data": {
        "user_ids": "15790,76108,76124",
        "start_date": "2017-03-12",
        "end_date": "2017-03-18"
    }
}

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


{
  "results": {
    "filters": {
      "start_date": "2017-03-12",
      "end_date": "2017-03-18",
      "user_ids": [
        "15790",
        "76108",
        "76124"
      ]
    },
    "payroll_by_jobcode_report": {
      "totals": {
        "82024": {
          "jobcode_id": 82024,
          "total_re_seconds": 0,
          "total_ot_seconds": 0,
          "total_dt_seconds": 0,
          "total_pto_seconds": 14400,
          "total_work_seconds": 14400
        },
        "82026": {
          "jobcode_id": 82026,
          "total_re_seconds": 0,
          "total_ot_seconds": 0,
          "total_dt_seconds": 0,
          "total_pto_seconds": 28800,
          "total_work_seconds": 28800
        },
        "762436": {
          "jobcode_id": 762436,
          "total_re_seconds": 0,
          "total_ot_seconds": 0,
          "total_dt_seconds": 0,
          "total_pto_seconds": 28800,
          "total_work_seconds": 28800
        }
      },
      "by_user": {
        "15790": {
          "user_id": 15790,
          "totals": {
            "82026": {
              "jobcode_id": 82026,
              "total_re_seconds": 0,
              "total_ot_seconds": 0,
              "total_dt_seconds": 0,
              "total_pto_seconds": 28800,
              "total_work_seconds": 28800
            },
            "733512": {
              "jobcode_id": 733512,
              "total_re_seconds": 57600,
              "total_ot_seconds": 18300,
              "total_dt_seconds": 0,
              "total_pto_seconds": 0,
              "total_work_seconds": 75900
            },
            "733514": {
              "jobcode_id": 733514,
              "total_re_seconds": 28800,
              "total_ot_seconds": 12480,
              "total_dt_seconds": 0,
              "total_pto_seconds": 0,
              "total_work_seconds": 41280
            },
            "733516": {
              "jobcode_id": 733516,
              "total_re_seconds": 28800,
              "total_ot_seconds": 3360,
              "total_dt_seconds": 0,
              "total_pto_seconds": 0,
              "total_work_seconds": 32160
            },
            "733528": {
              "jobcode_id": 733528,
              "total_re_seconds": 28800,
              "total_ot_seconds": 14400,
              "total_dt_seconds": 0,
              "total_pto_seconds": 0,
              "total_work_seconds": 43200
            }
          },
          "dates": {
            "2017-03-13": {
              "733528": {
                "jobcode_id": 733528,
                "total_re_seconds": 28800,
                "total_ot_seconds": 14400,
                "total_dt_seconds": 0,
                "total_pto_seconds": 0,
                "total_unpaid_seconds": 0,
                "total_work_seconds": 43200
              }
            },
            "2017-03-14": {
              "733516": {
                "jobcode_id": 733516,
                "total_re_seconds": 28800,
                "total_ot_seconds": 3360,
                "total_dt_seconds": 0,
                "total_pto_seconds": 0,
                "total_unpaid_seconds": 0,
                "total_work_seconds": 32160
              }
            },
            "2017-03-15": {
              "82026": {
                "jobcode_id": 82026,
                "total_re_seconds": 0,
                "total_ot_seconds": 0,
                "total_dt_seconds": 0,
                "total_pto_seconds": 28800,
                "total_unpaid_seconds": 0,
                "total_work_seconds": 28800
              },
              "733512": {
                "jobcode_id": 733512,
                "total_re_seconds": 28800,
                "total_ot_seconds": 8340,
                "total_dt_seconds": 0,
                "total_pto_seconds": 0,
                "total_unpaid_seconds": 0,
                "total_work_seconds": 37140
              }
            },
            "2017-03-16": {
              "733514": {
                "jobcode_id": 733514,
                "total_re_seconds": 28800,
                "total_ot_seconds": 12480,
                "total_dt_seconds": 0,
                "total_pto_seconds": 0,
                "total_unpaid_seconds": 0,
                "total_work_seconds": 41280
              }
            },
            "2017-03-17": {
              "733512": {
                "jobcode_id": 733512,
                "total_re_seconds": 28800,
                "total_ot_seconds": 9960,
                "total_dt_seconds": 0,
                "total_pto_seconds": 0,
                "total_unpaid_seconds": 0,
                "total_work_seconds": 38760
              }
            }
          }
        },
        "76108": {
          "user_id": 76108,
          "totals": {
            "733512": {
              "jobcode_id": 733512,
              "total_re_seconds": 18960,
              "total_ot_seconds": 0,
              "total_dt_seconds": 0,
              "total_pto_seconds": 0,
              "total_work_seconds": 18960
            },
            "733516": {
              "jobcode_id": 733516,
              "total_re_seconds": 8700,
              "total_ot_seconds": 0,
              "total_dt_seconds": 0,
              "total_pto_seconds": 0,
              "total_work_seconds": 8700
            },
            "762436": {
              "jobcode_id": 762436,
              "total_re_seconds": 0,
              "total_ot_seconds": 0,
              "total_dt_seconds": 0,
              "total_pto_seconds": 28800,
              "total_work_seconds": 28800
            }
          },
          "dates": {
            "2017-03-13": {
              "733512": {
                "jobcode_id": 733512,
                "total_re_seconds": 18960,
                "total_ot_seconds": 0,
                "total_dt_seconds": 0,
                "total_pto_seconds": 0,
                "total_unpaid_seconds": 0,
                "total_work_seconds": 18960
              }
            },
            "2017-03-14": {
              "733516": {
                "jobcode_id": 733516,
                "total_re_seconds": 8700,
                "total_ot_seconds": 0,
                "total_dt_seconds": 0,
                "total_pto_seconds": 0,
                "total_unpaid_seconds": 0,
                "total_work_seconds": 8700
              }
            },
            "2017-03-15": {
              "762436": {
                "jobcode_id": 762436,
                "total_re_seconds": 0,
                "total_ot_seconds": 0,
                "total_dt_seconds": 0,
                "total_pto_seconds": 28800,
                "total_unpaid_seconds": 0,
                "total_work_seconds": 28800
              }
            }
          }
        },
        "76124": {
          "user_id": 76124,
          "totals": {
            "82024": {
              "jobcode_id": 82024,
              "total_re_seconds": 0,
              "total_ot_seconds": 0,
              "total_dt_seconds": 0,
              "total_pto_seconds": 14400,
              "total_work_seconds": 14400
            },
            "733516": {
              "jobcode_id": 733516,
              "total_re_seconds": 144000,
              "total_ot_seconds": 28800,
              "total_dt_seconds": 3600,
              "total_pto_seconds": 0,
              "total_work_seconds": 176400
            }
          },
          "dates": {
            "2017-03-13": {
              "733516": {
                "jobcode_id": 733516,
                "total_re_seconds": 28800,
                "total_ot_seconds": 0,
                "total_dt_seconds": 0,
                "total_pto_seconds": 0,
                "total_unpaid_seconds": 0,
                "total_work_seconds": 28800
              }
            },
            "2017-03-14": {
              "733516": {
                "jobcode_id": 733516,
                "total_re_seconds": 28800,
                "total_ot_seconds": 14400,
                "total_dt_seconds": 3600,
                "total_pto_seconds": 0,
                "total_unpaid_seconds": 0,
                "total_work_seconds": 46800
              }
            },
            "2017-03-15": {
              "82024": {
                "jobcode_id": 82024,
                "total_re_seconds": 0,
                "total_ot_seconds": 0,
                "total_dt_seconds": 0,
                "total_pto_seconds": 14400,
                "total_unpaid_seconds": 0,
                "total_work_seconds": 14400
              },
              "733516": {
                "jobcode_id": 733516,
                "total_re_seconds": 28800,
                "total_ot_seconds": 0,
                "total_dt_seconds": 0,
                "total_pto_seconds": 0,
                "total_unpaid_seconds": 0,
                "total_work_seconds": 28800
              }
            },
            "2017-03-16": {
              "733516": {
                "jobcode_id": 733516,
                "total_re_seconds": 28800,
                "total_ot_seconds": 14400,
                "total_dt_seconds": 0,
                "total_pto_seconds": 0,
                "total_unpaid_seconds": 0,
                "total_work_seconds": 43200
              }
            },
            "2017-03-17": {
              "733516": {
                "jobcode_id": 733516,
                "total_re_seconds": 28800,
                "total_ot_seconds": 0,
                "total_dt_seconds": 0,
                "total_pto_seconds": 0,
                "total_unpaid_seconds": 0,
                "total_work_seconds": 28800
              }
            }
          }
        }
      }
    }
  },
  "supplemental_data": {
    "users": {
      "15790": {
        "id": 15790,
        "first_name": "Adam",
        "last_name": "Ashton",
        "group_id": 1648,
        "active": true,
        "employee_number": 3748,
        "salaried": true,
        "exempt": false,
        "username": "aashton",
        "email": "d@ds6.us",
        "payroll_id": "",
        "hire_date": "0000-00-00",
        "term_date": "0000-00-00",
        "last_modified": "2017-04-24T17:26:44+00:00",
        "last_active": "2017-04-18T12:35:26+00:00",
        "created": "2016-03-11T00:00:16+00:00",
        "client_url": "dstokes",
        "company_name": "dstokes",
        "mobile_number": "",
        "pto_balances": {
          "82024": 151920,
          "82026": 0,
          "762436": 3960
        },
        "submitted_to": "2017-03-12",
        "approved_to": "2017-03-12",
        "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": true,
          "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": ""
      },
      "76108": {
        "id": 76108,
        "first_name": "Alison",
        "last_name": "Canseco",
        "group_id": 0,
        "active": true,
        "employee_number": 0,
        "salaried": true,
        "exempt": false,
        "username": "acanseco",
        "email": "",
        "payroll_id": "",
        "hire_date": "0000-00-00",
        "term_date": "0000-00-00",
        "last_modified": "2017-04-24T17:25:55+00:00",
        "last_active": "2017-04-05T16:33:55+00:00",
        "created": "2016-10-20T22:40:10+00:00",
        "client_url": "dstokes",
        "company_name": "dstokes",
        "mobile_number": "",
        "pto_balances": {
          "82024": 414000,
          "82026": 0,
          "762436": 115200
        },
        "submitted_to": "2017-03-12",
        "approved_to": "2017-03-12",
        "manager_of_group_ids": [
          1648
        ],
        "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": true,
          "manage_jobcodes": false,
          "pin_login": false,
          "approve_timesheets": false,
          "manage_schedules": false,
          "external_access": false,
          "manage_my_schedule": false,
          "manage_company_schedules": true,
          "view_company_schedules": false,
          "view_group_schedules": false,
          "manage_no_schedules": false,
          "view_my_schedules": false
        },
        "customfields": ""
      },
      "76124": {
        "id": 76124,
        "first_name": "Erica",
        "last_name": "West",
        "group_id": 0,
        "active": true,
        "employee_number": 0,
        "salaried": false,
        "exempt": false,
        "username": "ewest",
        "email": "",
        "payroll_id": "",
        "hire_date": "0000-00-00",
        "term_date": "0000-00-00",
        "last_modified": "2017-04-20T13:50:28+00:00",
        "last_active": "2017-04-20T13:50:29+00:00",
        "created": "2016-10-20T22:47:22+00:00",
        "client_url": "dstokes",
        "company_name": "dstokes",
        "mobile_number": "",
        "pto_balances": {
          "82024": 129600,
          "82026": 0,
          "762436": 144000
        },
        "submitted_to": "2015-03-12",
        "approved_to": "2015-01-08",
        "manager_of_group_ids": [],
        "require_password_change": false,
        "pay_rate": 0,
        "pay_interval": "hour",
        "permissions": {
          "admin": false,
          "mobile": false,
          "status_box": false,
          "reports": false,
          "manage_timesheets": false,
          "manage_authorization": false,
          "manage_users": false,
          "manage_my_timesheets": true,
          "manage_jobcodes": false,
          "pin_login": true,
          "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": ""
      }
    },
    "jobcodes": {
      "82024": {
        "id": 82024,
        "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": "2015-11-18T21:34:19+00:00",
        "created": "2015-11-18T21:34:19+00:00",
        "filtered_customfielditems": "",
        "required_customfields": []
      },
      "82026": {
        "id": 82026,
        "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": "2015-11-18T21:34:19+00:00",
        "created": "2015-11-18T21:34:19+00:00",
        "filtered_customfielditems": "",
        "required_customfields": []
      },
      "733512": {
        "id": 733512,
        "parent_id": 0,
        "assigned_to_all": true,
        "billable": false,
        "active": true,
        "type": "regular",
        "has_children": false,
        "billable_rate": 0,
        "short_code": "",
        "name": "Amy's Bird Sanctuary",
        "last_modified": "2017-04-13T15:19:05+00:00",
        "created": "2016-10-20T22:31:42+00:00",
        "filtered_customfielditems": "",
        "required_customfields": []
      },
      "733514": {
        "id": 733514,
        "parent_id": 0,
        "assigned_to_all": true,
        "billable": false,
        "active": true,
        "type": "regular",
        "has_children": false,
        "billable_rate": 0,
        "short_code": "",
        "name": "Bill's Windsurf Shop",
        "last_modified": "2017-04-13T15:19:05+00:00",
        "created": "2016-10-20T22:31:42+00:00",
        "filtered_customfielditems": "",
        "required_customfields": []
      },
      "733516": {
        "id": 733516,
        "parent_id": 0,
        "assigned_to_all": true,
        "billable": false,
        "active": true,
        "type": "regular",
        "has_children": false,
        "billable_rate": 0,
        "short_code": "",
        "name": "Cool Cars",
        "last_modified": "2017-04-13T15:19:05+00:00",
        "created": "2016-10-20T22:31:42+00:00",
        "filtered_customfielditems": "",
        "required_customfields": []
      },
      "733528": {
        "id": 733528,
        "parent_id": 0,
        "assigned_to_all": true,
        "billable": false,
        "active": true,
        "type": "regular",
        "has_children": false,
        "billable_rate": 0,
        "short_code": "",
        "name": "Gevelber Photography",
        "last_modified": "2017-04-13T15:19:05+00:00",
        "created": "2016-10-20T22:31:42+00:00",
        "filtered_customfielditems": "",
        "required_customfields": []
      },
      "762436": {
        "id": 762436,
        "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": "2016-10-31T15:31:47+00:00",
        "created": "2016-10-31T15:31:13+00:00",
        "filtered_customfielditems": "",
        "required_customfields": []
      }
    }
  }
}