Skip to main content

Attaching Documents and Images

Due to the nature of how the Fleetio web app is configured, document and image uploads work a bit differently than our other resources. Files are not uploaded to our API, but directly to our third-party storage provider.

Step 1: Obtain a temporary policy and a signature​

To keep our customers' documents secure, we require that all uploads be handled using a temporary policy and signature. A policy is valid for only 1 hour, can only be used to create files, and only has access to a single sub-directory exclusive to your Fleetio account.

The process for obtaining a policy and signature is similar to the process used to create a record (Vehicle, Contact, etc.) via the API. You'll need to post to https://secure.fleetio.com/api/v1/uploads/policies using your API key and Account Token. You'll obtain three values back: a policy, a signature, and a path.

Let's look at an example:

$ curl -X POST "https://secure.fleetio.com/api/v1/uploads/policies" -H 'Authorization: Token token="YOUR_API_KEY"' -H "Account-Token: YOUR_ACCOUNT_TOKEN"

{"policy":"XXXXXXX","signature":"YYYYYYY","path":"/api/ABC123/"}

You'll need all three values for the next step, so make sure to keep track of those.

Step 2: Upload the file to our third party storage service​

Using the policy, signature, and path from above, we'll post the file to our storage service. The target URL is https://lmuavc3zg4.execute-api.us-east-1.amazonaws.com/prod/uploads and you'll append these three values as URL parameters. Here's an example:

$ curl -i -X POST -H "Content-Type: image/png" --data-binary '@testdocument.png' 'https://lmuavc3zg4.execute-api.us-east-1.amazonaws.com/prod/uploads?signature=XXXXXXX&policy=YYYYYYY&path=/api/ABC123/'

{"container": "fleetio-production", "url": "https://cdn.filestackcontent.com/C9Az8KlQdKUYgA6uVg5Q", "filename": "temp.png", "key": "api/ABC123/FGoaMFnnS1yLekC3DuaI_temp.png", "type": "image/png", "size": 46031}

You'll get back a response with a handful of values, but the only one we need to carry forward to step 3 is the url.

Step 3: Attach a Document or Image to a record in Fleetio​

Now that the file has been successfully uploaded, you'll need to tell Fleetio about it. Fleetio stores files in two association records called Document and Image. The choice of which one to use is up to you. Both are nearly identical, but images include a few UI enhancements, such as thumbnails, for better user experience.

Documents and Images both share the following fields: name, description, file_url. You simply need to pass these fields as nested attributes on the parent record. Here's an example:

curl -i -X POST "https://secure.fleetio.com/api/v1/work_orders" -H 'Authorization: Token token="YOUR_API_KEY"' -H "Account-Token: YOUR_ACCOUNT_TOKEN" --data "vehicle_id=123&issued_at=2017-11-13&work_order_status_id=456&images_attributes[0][name]=test_image&images_attributes[0][file_url]=https://cdn.filestackcontent.com/ABC123"

Notice we're creating a work order by POSTing to https://secure.fleetio.com/api/v1/work_orders. We're including three basic fields: vehicle_id, issued_at, and work_order_status_id. Additionally, we're sending along two other fields, both scoped under images_attributes, images_attributes[0][name] and images_attributes[0][file_url]. name can be any value, but we recommend that you use the original filename for this. file_url is the location of the file. Use the url you received from step 2 as this value.

You can attach as many images or documents as you would like, just be sure to name and index them properly. Here's an example where we attach two documents and two images to a new work order:

curl -i -X POST "https://secure.fleetio.com/api/v1/work_orders" -H 'Authorization: Token token="YOUR_API_KEY"' -H "Account-Token: YOUR_ACCOUNT_TOKEN" --data "vehicle_id=123&issued_at=2017-11-13&work_order_status_id=456&images_attributes[0][name]=test_image&images_attributes[0][file_url]=https://cdn.filestackcontent.com/ABC12345&images_attributes[1][name]=test_image2&images_attributes[1][file_url]=https://cdn.filestackcontent.com/ABC67890&documents_attributes[0][name]=test_pdf&documents_attributes[0][file_url]=https://cdn.filestackcontent.com/DEF12345&documents_attributes[1][name]=test_pdf2&documents_attributes[1][file_url]=https://cdn.filestackcontent.com/DEF67890"

You can also attach files to a record after it has been created:

curl -i -X PATCH "https://secure.fleetio.com/api/v1/work_orders/235952" -H 'Authorization: Token token="YOUR_API_KEY"' -H "Account-Token: YOUR_ACCOUNT_TOKEN" --data "images_attributes[0][name]=test_image&images_attributes[0][file_url]=https://cdn.filestackcontent.com/ABC123"

Full Example​

# Request a policy and signature. Valid for 1 hour.
$ curl -X POST "https://secure.fleetio.com/api/v1/uploads/policies" -H 'Authorization: Token token="YOUR_API_KEY"' -H "Account-Token: YOUR_ACCOUNT_TOKEN"

{"policy":"XXXXXXX","signature":"YYYYYYY","path":"/api/ABC123/"}



# Use policy, signature, and path from previous request to upload an image and a pdf to our third party storage.
$ curl -X POST  -F fileUpload=@testdocument.png 'https://lmuavc3zg4.execute-api.us-east-1.amazonaws.com/prod/uploads?signature=XXXXXXX&policy=YYYYYYY&path=/api/ABC123/'

{"container": "fleetio-production", "url": "https://cdn.filestackcontent.com/FFF123", "filename": "testdocument.png", "key": "api/ABC123/XXXXXXX_testdocument.png", "type": "image/png", "size": 25485}$ 

$ curl -X POST  -F fileUpload=@attachments.pdf 'https://lmuavc3zg4.execute-api.us-east-1.amazonaws.com/prod/uploads?signature=XXXXXXX&policy=YYYYYYY&path=/api/ABC123/'

{"container": "fleetio-production", "url": "https://cdn.filestackcontent.com/FFF456", "filename": "attachments.pdf", "key": "api/ABC123/XXXXXXX_attachments.pdf", "type": "application/pdf", "size": 507114}



# Create a new work order and pass along both file_urls obtained from the previous step. 
$ curl -i -X POST "https://secure.fleetio.com/api/v1/work_orders" -H 'Authorization: Token token="YOUR_API_KEY"' -H "Account-Token: YOUR_ACCOUNT_TOKEN" --data "vehicle_id=123&issued_at=2017-11-13&work_order_status_id=456&images_attributes[0][name]=test_image&images_attributes[0][file_url]=https://cdn.filestackcontent.com/FFF123&documents_attributes[0][name]=test_pdf&documents_attributes[0][file_url]=https://cdn.filestackcontent.com/FFF456"