Uploading Files with Third Party API

This article is designed to help developers, who are already familiar with working with APIs, upload files to Traffio using the third-party API.

Before you begin, ensure you have an active access token and have confirmed successful communication with the API. If you don’t have an access token yet, please refer to this article.

Basic Concepts

There are several steps to follow when uploading a file to Traffio. This is because files are uploaded directly to AWS S3 object storage, rather than being uploaded to Traffio itself. The overall process is illustrated in the image below.

Example

The following provides a detailed description of the file upload process, using a file linked to a person in Traffio as an example.

Ask Permission to Upload

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

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 from the previous step will outline the attributes and input fields required in an HTML form to upload a file to S3. For example, with 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"
}

Which 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.

Roles, Access Levels and Permissions

Form Terminology

Third Party API Integrations