Skip to main content

Attaching Documents and Images

It's possible to attach documents and images to records in Fleetio via the API. This is done by uploading the file to our third party storage provider and then attaching it to a record.

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 1 hour, can only be used to create files, and has access to a single subdirectory exclusive to your Fleetio account.

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: policy, signature, and path.

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

response:
{"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. You may also append filename to set a custom file name. Here's an example:

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

response:
{"container": "fleetio-production", "url": "https://cdn.filestackcontent.com/C9Az8KlQdKUYgA6uVg5Q", "filename": "custom_name.png", "key": "api/ABC123/FGoaMFnnS1yLekC3DuaI_custom_name.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​

Documents and images both share the following fields: name, description, file_url. These fields will be passed as nested attributes on the parent record. file_url is the only required field, but we recommend including name and description for clarity, and for visibility in the web and mobile UIs.

There are two example types below. One is a complete cURL request, the other is a JSON request body.

We will attach documents and images to a Work Order. You can use the same approach for other record types that support attachments.

Here's an example where we are creating a new Work Order and including an image:

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

Here's an example where we are creating a new Work Order and attaching two documents and two images to a new Work Order:

curl -i -X POST "https://secure.fleetio.com/api/v2/work_orders" -H 'Authorization: Token token="YOUR_API_KEY"' -H "Account-Token: YOUR_ACCOUNT_TOKEN" --data "vehicle_id=123&issued_at=2023-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"
{
  "vehicle_id": 123,
  "issued_at": "2023-11-13",
  "work_order_status_id": 456,
  "images_attributes": [
    {
      "name": "test_image",
      "file_url": "https://cdn.filestackcontent.com/ABC12345"
    },
    {
      "name": "test_image2",
      "file_url": "https://cdn.filestackcontent.com/ABC67890"
    }
  ],
  "documents_attributes": [
    {
      "name": "test_pdf",
      "file_url": "https://cdn.filestackcontent.com/DEF12345"
    },
    {
      "name": "test_pdf2",
      "file_url": "https://cdn.filestackcontent.com/DEF67890"
    }
  ]
}

You can also attach files to an existing record via PATCH request. Here's an example where are are updating an existing Work Order:

curl -i -X PATCH "https://secure.fleetio.com/api/v2/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"
{
  "images_attributes": [
    {
      "name": "test_image",
      "file_url": "https://cdn.filestackcontent.com/ABC123"
    }
  ]
}

Any record types that support documents and images attachments are shown in our API Reference. documents_attributes and images_attributes will be listed under the request body parameters in create or update docs for the respective record type.