REST API: Project Report

Last Updated: June 04, 2015

Description

Retrieves a project report, with filters to narrow down the results.

Resource Information

HTTP Method POST
Endpoint https://rest.tsheets.com/api/v1/reports/project
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:
optional
String. YYYY-MM-DD formatted date. Any time with a date falling on or after this date will be included.
end_date:
optional
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.
jobcode_ids:
optional
Integer. A comma-seperated list of jobcode ids. Only time for these jobcodes will be included.
jobcode_type:
optional
String. The type of jobcodes to include. "regular", "pto", "unpaid_break", "paid_break", or "all". Default is "all"
customfielditems:
optional
Object. An object with customfield_id as the properties, and each value being an array of customfielditem values. I.e.
"customfielditems": {
    "12437": [
        "ProjectX",
        "Wolverine"
    ]
}

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": {
"project_report": {
    "start_date": "2014-03-02",
    "end_date": "2014-03-15",
    "totals": {
        "users": {                 ## This contains all users, indexed by user_id and
                                   ## the number of hours for each
         "29604": "0.08"
        },
        "groups": {                ## This contains the number of hours for each group.
                                   ## Time for which there is no group
         "0": 0.08                 ## is represented by an index of '0'
        },
        "jobcodes": {              ## This contains the number of hours for each jobcode.
                                   ## Time for which there is no jobcode
         "4647114": "0.08"         ## is represented by an index of '0'
        },
        "customfields": {          ## This contains the number of hours for each customfield.
                                   ## Indexes are each customfield id.
         "28840": {
          "0": "0.08"              ## Each of these sub-containers is a breakdown of the
                                   ## amount of hours for each item (indexed by id) in
                                   ## the customfield.  Time for which there is no item
                                   ## assigned from this customfield
                                   ## is represented by a customfielditem id of '0'
         },
         "2054": {
          "0": "0.08"
         },
         "64": {
          "664014": "0.08"
         },
         "34": {
          "0": "0.08"
         },
         "54": {
          "0": "0.08"
         },
         "44": {
          "3711483": "0.08"
         },
         "3184": {
          "0": "0.08"
         }
    }
  }
}
        

Examples

Retrieve a project report for time recorded within an account.

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

## contents of the @tsproject_report.json file are:
{
 "data":
  {
    "start_date": "2014-03-02",
    "end_date": "2014-03-15",
    "customfielditems": {
         "44": [
             "jeidh",
             "Customer2"
         ]
    },
    "jobcode_ids": [
        "4647114",
        "128934",
        "120981"
    ]
  }
}


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


{
 "results": {
   "filters": {
    "user_ids": [

    ],
    "group_ids": [

    ],
    "jobcode_type": "both",
    "customfielditems": {
     "44": [
      "jeidh",
      "Customer2"
     ]
    },
    "jobcode_ids": [
     "4647114",
     "128934",
     "120981"
    ]
   },
 "project_report": {
   "start_date": "2014-03-02",
   "end_date": "2014-03-15",
   "totals": {
    "users": {
     "29604": "0.08"
    },
    "groups": {
     "0": 0.08
    },
    "jobcodes": {
     "4647114": "0.08"
    },
    "customfields": {
     "28840": {
      "0": "0.08"
     },
     "2054": {
      "0": "0.08"
     },
     "64": {
      "664014": "0.08"
     },
     "34": {
      "0": "0.08"
     },
     "54": {
      "0": "0.08"
     },
     "44": {
      "3711483": "0.08"
     },
     "3184": {
      "0": "0.08"
     }
    }
   }
  }
 },
 "supplemental_data": {
  "users": {
   "29604": {
    "id": 29604,
    "first_name": "Rand",
    "last_name": "test15",
    "group_id": 0,
    "active": true,
    "employee_number": 0,
    "salaried": false,
    "exempt": false,
    "username": "test15",
    "email": "jared.cheney@gmail.com",
    "payroll_id": "",
    
    ...
    
   }
  },
  "jobcodes": {
   "4647114": {
    "id": 4647114,
    "parent_id": 235494,
    "assigned_to_all": true,
    "billable": false,
    "active": false,
    "type": "regular",
    "has_children": false,
    "billable_rate": 0,
    "short_code": "f",
    "name": "Finches",
    "last_modified": "2014-03-24T18:41:24+00:00",
    "created": "2011-10-14T04:20:16+00:00",
    
    ...
    
   }
  },
  "customfields": {
   "28840": {
    "id": 28840,
    "required": true,
    "applies_to": "timesheet",
    "type": "managed-list",
    "short_code": "",
    "regex_filter": "",
    "name": "Class",
    
    ...
    
   }
  },
  "customfielditems": {
   "664014": {
    "id": 664014,
    "customfield_id": 64,
    "active": true,
    "short_code": "m",
    "name": "Mercede's",
    "last_modified": "2013-09-12T09:34:43+00:00",
    "required_customfields": [

    ]
   },
   "3711483": {
    "id": 3711483,
    "customfield_id": 44,
    "active": true,
    "short_code": "",
    "name": "jeidh",
    "last_modified": "2014-03-04T15:05:33+00:00",
    "required_customfields": [

    ]
   }
  }
 }
}