REST API: Add Files

Last Updated: July 27, 2018

Description

Add one or more files that can be attached to objects (Example: timesheet). Currently we only allow .png, .jpeg, .jpg file formats. We will handle batches of up to 50 files at a time. More than 50 files will result in a 413 - Request entity too large error.

The entire request size may not exceed 2 MB. Also, any individual file size may not exceed 2 MB (go figure). For example you could submit a request with 10 files that are each 200 KB in size. Or you could submit a request with 2 files where one is 1.9 MB in size, and the other is 0.1 MB in size.

Your request will be denied if you do not include the Content-Length header when submitting a request with an accurate value for the data being submitted.

Resource Information

HTTP Method POST
Endpoint https://rest.tsheets.com/api/v1/files
Authentication Token header required. See authentication section
Request format json object. Pass an array of file objects as the value to a 'data' property (see example below).

NOTE: You must specify Content-Length when utilizing this endpoint (see notes above).

Response format json
Response object File

Required File Properties

file_name:
String. Name of the file.
file_data:
String. Base64 encoded string of the file.

Optional File Properties

For a full list of the properties that may be set on a file, see the File object.

Status Codes

Each file that is uploaded will come back with a _status_code and _status_message that will indicate whether the file was uploaded successfully. If there was a problem uploading a file, there may also be an additional field, _status_extra, which will contain more details about the failure.

_status_code Meaning
200 OK. File was uploaded successfully.
417 Expectation Failed. Something was wrong or missing with the properties supplied for this file. See the _status_extra value for more detail.

Examples

Upload a file.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -H "Content-Type: application/json" -X POST -i "https://rest.tsheets.com/api/v1/files" -d @tsfile_create.json 

## contents of the tsfile_create.json file are:
{
 "data":
  [
    {
     "file_data":"data:image/png;base64,iVBORw0KGgoAAA...< actual data here >...ANI=",
     "file_name":"invisible_minion.png",   
     "meta_data": {
           "file_description":"Ba-ba-ba-ba-ba-nana",
           "image_rotation": 0
     }
    }
  ]
}

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

{
 "results": {
  "files": {
   "1": {
    "_status_code": 200,
    "_status_message": "Uploaded",
    "id": 123828,
    "uploaded_by_user_id": 19128,
    "file_name": "invisible_minion.png",
    "active": true,
    "size": 95,
    "last_modified": "2017-08-24T00:09:32+00:00",
    "created": "2017-08-24T00:09:32+00:00",
    "linked_objects": [],
    "meta_data": {
     "file_description": "Ba-ba-ba-ba-ba-nana",
     "image_rotation": 0
    }
   }
  }
 },
 "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": ""
   }
  }
 }
}