REST API: Current Totals Report

Last Updated: May 16, 2017

Description

Retrieves a snapshot report for the current totals (shift and day) along with additional information provided for those who are currently on the clock.

Resource Information

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

user_ids:
optional
Integer. A comma-separated list of user ids. Only totals for these users will be included.
group_ids:
optional
Integer. A comma-seperated list of group ids. Only totals for users from these groups will be included.
on_the_clock:
optional
String. 'yes', 'no', or 'both'. Default is 'no'. If a user is on_the_clock, it means the user is currently working (has not clocked out yet).
page:
optional
Integer. Represents the page of results you'd like to retrieve. Default is 1.
per_page:
optional
Integer. Represents how many results you'd like to retrieve per request (page). Default is 50. Max is 50. Using this filter requires a page to be defined.
order_by:
optional
String. Attribute name by which to order the result data.
Available attribute filters: username, first_name, last_name, group_name, group_id, shift_seconds, day_seconds
order_desc:
optional
Boolean. Either 'true' or 'false'. If true result data will be ordered descending by the attribute specified in the order_by filter.

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.

Note: When a user is off the clock, both the timesheet_id and jobcode_id attributes will return as null and shift seconds will be 0.

{
    "results": {
        "current_totals": {
            "1751136": {                                ## Totals are indexed by unique 
                                                        ##  user_id
                "user_id": 1751136,
                "on_the_clock": true,                   ## Whether this user is currently
                                                        ##  on the clock
                
                "timesheet_id": 173523290,              ## Timesheet id for the current 
                                                        ##  timesheet
                "jobcode_id": 26730062,                 ## Jobcode id for the current 
                                                        ##  timesheet
                "group_id": 180010,                     ## Unique group id for this user,
                                                        ##  value of zero represents those
                                                        ##  without a group
                "shift_geolocations_available": true,   ## If geolocations are available 
                                                        ##  for the current timesheet
                "shift_seconds": 25275,                 ## Total time for the current
                                                        ##  shift, in seconds
                                             
                "day_seconds": 25275                    ## Total time for the day, 
                                                        ##  in seconds
            },
            "1738864": {
                "user_id": 1738864,
                "on_the_clock": false,
                "timesheet_id": null,
                "jobcode_id": null,
                "group_id": 180010,
                "shift_geolocations_available": false,
                "shift_seconds": 0,
                "day_seconds": 25719
            },
            
            ...
            
        }
    }
}
        

Examples

Retrieve a current_totals report 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/current_totals" -d @ts_current_totals_report.json

## contents of the ts_current_totals_report.json file are:
{
    "data": {
        "on_the_clock": "both"
    }
}


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

{
    "results": {
        "current_totals": {
            "1751136": {
                "user_id": 1751136,
                "on_the_clock": true,
                "timesheet_id": 173523290,
                "jobcode_id": 26730062,
                "group_id": 180010,
                "shift_geolocations_available": true,
                "shift_seconds": 25275,
                "day_seconds": 25275
            },
            "1738864": {
                "user_id": 1738864,
                "on_the_clock": false,
                "timesheet_id": null,
                "jobcode_id": null,
                "group_id": 180010,
                "shift_geolocations_available": false,
                "shift_seconds": 0,
                "day_seconds": 25719
            },
            
            ...
            
        }
    },
    "supplemental_data": {
        "users": {
            "1751136": {
                "id": 1751136,
                "first_name": "Leeroy",
                "last_name": "Jenkins",
                "group_id": 180010,
                "active": true,
                "employee_number": 0,
                "salaried": false,
                "exempt": false,
                "username": "ljenkins",
                "email": "",
                "payroll_id": "",
                "hire_date": "0000-00-00",
                "term_date": "0000-00-00",
                "last_modified": "2014-10-30T16:09:00+00:00",
                "last_active": "2014-11-03T16:07:27+00:00",
                "created": "2014-10-30T16:09:00+00:00",
                "client_url": "nate",
                "mobile_number": "",
                "approved_to": "",
                "submitted_to": "",
                "manager_of_group_ids": [],
                "require_password_change": false,
                "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,
                    "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
                }
            },
            
            ...
            
        },
        "groups": {
            "0": {
                "id": 0,
                "name": "-",
                "last_modified": "2009-02-11T17:48:39+00:00",
                "created": "2009-02-11T17:47:04+00:00"
            },
            
            ...
            
        },
        "timesheets": {
            "173523280": {
                "id": 173523280,
                "user_id": 1751140,
                "jobcode_id": 26730062,
                "start": "2014-11-03T09:07:21-07:00",
                "end": "",
                "duration": 0,
                "date": "2014-11-03",
                "tz": -7,
                "tz_str": "tsMT",
                "type": "regular",
                "location": "TSheets iPhone App",
                "on_the_clock": true,
                "locked": 0,
                "notes": "",
                "customfields": {
                    "8184": "",
                    "19476": "",
                    "19478": "",
                    "19618": "",
                    "21360": "",
                    "37382": "",
                    "40028": "",
                    "40030": ""
                },
                "last_modified": "2014-11-03T16:07:26+00:00"
            },
            
            ...
            
        },
        "jobcodes": {
            "26730062": {
                "id": 26730062,
                "parent_id": 26730016,
                "assigned_to_all": false,
                "billable": false,
                "active": true,
                "type": "regular",
                "has_children": false,
                "billable_rate": 0,
                "short_code": "a",
                "name": "Android",
                "last_modified": "2014-10-21T17:06:02+00:00",
                "created": "2014-10-21T17:06:02+00:00",
                "required_customfields": [],
                "filtered_customfielditems": ""
            }
        }
    }
}