Overview

This article aims to help developers, already familiar with interacting with API's, to upload files to Traffio using the third party API.

Getting Started

Before you begin, you'll need an active access token and have already confirmed that you can successfully communicate with the API. If you don't have an access token, you'll want to read this article.

Basic Concepts

There are a few steps to follow in order to upload a file to Traffio. The reason for this is that you don't upload a file to Traffio but rather directly to AWS S3 object storage. The general idea can be seen in the image below.

Example

The following describes the file upload process in detail using a file liked to a person in Traffio as an example.

Ask Permission to Upload

To get permissions and upload details for the file, you must first make a POST request to the third party API end-point https://app.traff.io/api_third_party/v1_upload/s3_upload_person_file including the the payload parameters of:

file_type: The mime type of the file. Eg: image/jpeg, application/pdf, etc.
person_id: The unique ID of the person that the file will be linked to.

If your request is successful, you will receive a response with details of how to upload to S3.

Uploading the File to S3

The response you get from the previous step describes the attributes and input fields you need to include in a HTML form to upload a file to S3. For example, for the following response...

{
    "formAttributes": {
        "action": "https://s3.ap-southeast-2.amazonaws.com/example-bucket",
        "method": "POST",
        "enctype": "multipart/form-data",
        "key": "1/person/15/1670972404/"
    },
    "formInputs": {
        "acl": "private",
        "Content-Type": "image/jpeg",
        "key": "1/person/15/1670972404/",
        "X-Amz-Credential": "ALK6J45KJS33DF4/20221213/ap-southeast-2/s3/aws4_request",
        "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
        "X-Amz-Date": "20221213T230004Z",
        "Policy": "eyJleHBpcmF0aW9uIjoiMjAyMi0xMi0xYWwiOiJBS0lBWkxYR0UyWktSSUZVQ0xPNFwvMjAyMjEyMTNcL2FwLXNvdXRoZWFzdC0yXC9zM1wvYXdzNF9yZXF1ZXN0In0seyJYLUFtei1BbGdvcml0aG0iOiJBV1M0LUhNQUMtU0hBMjU2In1dfQ==",
        "X-Amz-Signature": "f98s7df987ss9df8798sdf79sd0fd34fj23l2ld"
    },
    "person_id": "15",
    "customer_id": "1"
}

... would require the following HTML form to perform the upload to S3...

<form action="https://s3.ap-southeast-2.amazonaws.com/example-bucket"
      method="POST"
      enctype="multipart/form-data"
>
      <input type="hidden" name="acl" value="private"/>
      <input type="hidden" name="Content-Type" value="image/jpeg"/> 
      <input type="hidden" name="key" value="1/person/15/1670972404/file-name.jpg"/>
      <input type="hidden" name="X-Amz-Credential" value="ALK6J45KJS33DF4/20221213/ap-southeast-2/s3/aws4_request"/>
      <input type="hidden" name="X-Amz-Algorithm" value="AWS4-HMAC-SHA256"/>
      <input type="hidden" name="X-Amz-Date" value="20221213T230004Z"/>
      <input type="hidden" name="Policy" value="eyJleHBpcmF0aW9uIjoiMjAyMi0xMi0xYWwiOiJBS0lBWkxYR0UyWktSSUZVQ0xPNFwvMjAyMjEyMTNcL2FwLXNvdXRoZWFzdC0yXC9zM1wvYXdzNF9yZXF1ZXN0In0seyJYLUFtei1BbGdvcml0aG0iOiJBV1M0LUhNQUMtU0hBMjU2In1dfQ=="/>
      <input type="hidden" name="X-Amz-Signature" value="f98s7df987ss9df8798sdf79sd0fd34fj23l2ld"/>

      <input type="file" name="file" />
      <input type="submit" name="submit" value="Upload to Amazon S3" />
</form>

The cURL request for the above form would look like this...

curl --location --request POST 'https://s3.ap-southeast-2.amazonaws.com/example-bucket' \
--form 'key="1/person/15/1670972404/file-name.jpg"' \
--form 'acl="private"' \
--form 'Content-Type="image/jpeg"' \
--form 'X-Amz-Credential="ALK6J45KJS33DF4/20221213/ap-southeast-2/s3/aws4_request"' \
--form 'X-Amz-Algorithm="AWS4-HMAC-SHA256"' \
--form 'X-Amz-Date="20221213T230004Z"' \
--form 'Policy="eyJleHBpcmF0aW9uIjoiMjAyMi0xMi0xYWwiOiJBS0lBWkxYR0UyWktSSUZVQ0xPNFwvMjAyMjEyMTNcL2FwLXNvdXRoZWFzdC0yXC9zM1wvYXdzNF9yZXF1ZXN0In0seyJYLUFtei1BbGdvcml0aG0iOiJBV1M0LUhNQUMtU0hBMjU2In1dfQ=="' \
--form 'X-Amz-Signature="f98s7df987ss9df8798sdf79sd0fd34fj23l2ld"' \
--form 'file=@"/home/user/file-name.jpg"'

One thing to note about this upload code (form or cURL) is that you can add your real filename to the end of the key. For example, 'file-name.jpg' has been added to the key above.

Record File in Traffio

With a successful response from S3, you can now register the file upload in Traffio's database by making a request to the end-point https://app.traff.io/api_third_party/v1_files/person_file with the following payload parameters:

document_type_id: For person-files, the document type ID should be 6 but if you are uploading a different kind of document, you should look up the end-point for document types: https://app.traff.io/api_third_party/v1_document_type/document_type
file_description: An optional description of the file.
file_name: This should be the same value of the key parameter you sent to S3 when uploading your file. In the example above, this value was '1/person/15/1670972404/file-name.jpg'.
file_title: An optional human-friendly title for your file.
person_id: The unique ID of the person that the file will be linked to.

The response you receive from this request will include of the relevant details about the file you have uploaded - in particular, the final storage location of the file in the file_url field.

With all of these steps completed successfully, you have completed the file upload process into Traffio.