REST API: List Files

Last Updated: July 27, 2018

Description

Retrieves a list of all uploaded files, with optional filters to narrow down the results.

Resource Information

HTTP Method GET
Endpoint https://rest.tsheets.com/api/v1/files
Authentication Token header required. See authentication section
Request format Everything is handled through the request uri on a GET.
Response format json
Response object File

Available Filters

ids:
optional
Integer. Comma separated list of one or more file ids you'd like to filter on.
uploaded_by_user_ids:
optional
Integer. Comma separated list of one or more user ids you'd like to filter on. Only files uploaded by these users will be returned.

If uploaded_by_user_ids is not set, it will default to return files uploaded by the current user making the api request.
linked_object_type:
optional - unless object_ids are set
String. Only files linked to this object type are returned. Allowed values: 'timesheet'
object_ids:
optional - You must also specify a linked_object_type when using this filter
Integer. Comma separated list of one or more linked object ids you'd like to filter on.
active:
optional
String. 'yes', 'no', or 'both'. Default is 'yes'.
modified_before:
optional
String (ISO8601 format). Only files modified before this date/time will be returned (i.e. 2004-02-12T15:19:21+00:00).
modified_since:
optional
String (ISO8601 format). Only files modified since this date/time will be returned (i.e. 2004-02-12T15:19:21+00:00).
supplemental_data:
optional
String. 'yes' or 'no'. Default is 'yes'. Indicates whether supplemental data should be returned.
per_page:
optional
Integer. Represents how many results you'd like to retrieve per request (page). Default is 50. Max is 50.
page:
optional
Integer. Represents the page of results you'd like to retrieve. Default is 1.

Examples

Retrieve a list of all files.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/files"

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

{
 "results": {
  "files": {
   "44878": {
    "id": 44878,
    "uploaded_by_user_id": 19128,
    "file_name": "tsheets.jpeg",
    "active": true,
    "size": 7890,
    "last_modified": "2017-07-03T17:46:58+00:00",
    "created": "2017-07-03T17:46:58+00:00",
    "linked_objects": {
     "timesheets": [
      "135288482",
      "135288514",
      "135288460"     
     ]
    },
    "meta_data": {
     "file_description": "Excellent app to track time"
    }
   },
   "44174": {
    "id": 44174,
    "uploaded_by_user_id": 19128,
    "file_name": "relentless.jpeg",
    "active": true,
    "size": 34900,
    "last_modified": "2017-07-03T17:47:53+00:00",
    "created": "2017-07-03T17:47:53+00:00",
    "linked_objects": [],
    "meta_data": {
     "file_description": "Passionate about our clients success!"
    }
   },
   "50692": {
    "id": 50692,
    "uploaded_by_user_id": 19128,
    "file_name": "healthy.jpg",
    "active": true,
    "size": 4560,
    "last_modified": "2017-08-24T00:09:32+00:00",
    "created": "2017-08-24T00:09:32+00:00",
    "linked_objects": {
     "timesheets": [
      "135288482",
      "135288514",
      "135288460"     
     ]
    },
    "meta_data": {
     "file_description": "Work hard period play hard period!"
    }
   }
  }
 },
 "supplemental_data": {
  "users": {
   "19128": {
    "id": 19128,
    "first_name": "Shree",
    "last_name": "Yalamanchili",
    "group_id": 0,
    "active": true,
    "employee_number": 0,
    "salaried": false,
    "exempt": false,
    "username": "shree",
    "email": "shree_dev@tsheets.com",
    "email_verified": true,
    "payroll_id": "",
    "hire_date": "0000-00-00",
    "term_date": "0000-00-00",
    "last_modified": "2017-08-16T18:32:46+00:00",
    "last_active": "2017-08-16T15:16:22+00:00",
    "created": "2016-04-05T15:41:30+00:00",
    "client_url": "devrocks",
    "company_name": "DevRocks",
    "profile_image_url": "",
    "mobile_number": "",
    "pto_balances": "",
    "submitted_to": "2017-01-22",
    "approved_to": "2016-04-06",
    "manager_of_group_ids": [
     27520
    ],
    "require_password_change": false,
    "pay_rate": 0,
    "pay_interval": "hour",
    "permissions": {
     "admin": true,
     "mobile": true,
     "status_box": true,
     "reports": true,
     "manage_timesheets": true,
     "manage_authorization": true,
     "manage_users": true,
     "manage_my_timesheets": true,
     "manage_jobcodes": true,
     "pin_login": true,
     "approve_timesheets": true,
     "manage_schedules": true,
     "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": ""
   }
  },
  "timesheets": {
   "135288482": {
    "id": 135288482,
    "user_id": 1242515,
    "jobcode_id": 17288283,
    "start": "2013-07-16T09:04:00-06:00",
    "end": "2013-07-16T15:57:00-06:00",
    "duration": 24780,
    "date": "2013-07-16",
    "tz": -6,
    "tz_str": "tsMT",
    "type": "regular",
    "location": "(Eagle, ID?)",
    "on_the_clock": false,
    "locked": 0,
    "notes": "",
    "customfields": {
     "19142": "Item 1",
     "19144": "Item 2"
    },
    "attached_files": [
      50692,
      44878       
    ],
    "last_modified": "1970-01-01T00:00:00+00:00",
    "created": "1970-01-01T00:00:00+00:00"
   },
   "135288514": {
    "id": 135288514,
    "user_id": 1242509,
    "jobcode_id": 18080900,
    "start": "2013-07-16T13:07:00-06:00",
    "end": "2013-07-16T17:29:00-06:00",
    "duration": 15720,
    "date": "2013-07-16",
    "tz": -6,
    "tz_str": "tsMT",
    "type": "regular",
    "location": "(Eagle, ID?)",
    "on_the_clock", false,
    "locked": 0,
    "notes": "",
    "customfields": {
     "19142": "Item 1",
     "19144": "Item 2"
    },
    "attached_files": [
      50692,
      44878       
    ],
    "last_modified": "1970-01-01T00:00:00+00:00",
    "created": "1970-01-01T00:00:00+00:00"
   },
   "135288460": {
    "id": 135288460,
    "user_id": 1242509,
    "jobcode_id": 18080900,
    "start": "2013-07-18T08:09:00-06:00",
    "end": "2013-07-18T14:58:00-06:00",
    "duration": 24540,
    "date": "2013-07-18",
    "tz": -6,
    "tz_str": "tsMT",
    "type": "regular",
    "location": "(Eagle, ID?)",
    "on_the_clock", false,
    "locked": 0,
    "notes": "",
    "customfields": {
     "19142": "Item 1",
     "19144": "Item 2"
    },
    "attached_files": [
      50692,
      44878       
    ],
    "last_modified": "1970-01-01T00:00:00+00:00",
    "created": "1970-01-01T00:00:00+00:00"
   }
  }
 }
}
    

Retrieve a list of all files (active or deleted) linked to timesheet with id '21718670'.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/files?linked_object_type=timesheet&object_ids=21718670"

## RESPONSE
## (response would have the same layout as the above example)