Getting started

Get Access to API

Authentication

Making your first request

Guides

Generate Doc X-Ray

Generate Bank X-Ray

Generate Financial X-Ray

Generate ESG X-Ray

Generate Manager X-Ray

Concepts

Overview

Request

Reports

Medium

Doc X-Ray

Bank X-Ray

Financial X-Ray

ESG X-Ray

Manager X-Ray

Resources

API versioning

Webhooks

Uploading a media

Uploading a media

In this guide, you will see a step-by-step explanation on how you can upload a media to our API.

This documentation with provide you the following information:

1. How to create the medium in our API.
2. How to upload the file to our AWS S3 bucket.
3. How to update the medium in our API.

Create a medium

Make a POST /media HTTP request with the name, type, request id, and meta fields.

POST /media
{
    "name": "bank_statement",
    "type": "document",
    "meta": {
        "name": "bank_statement_february_2022.pdf", // Original filename
        "size": 4911,                               // Size in bytes of the file
        "type": "application/pdf"                   // Mimetype of the file
    },
    "request": "[requestId]"
}

Use a name of the document from the following list:

• certified_financial_statement
• bank_statement
• interim_financial_statement
• other

The response of the API will contain an upload field.

// Example response
{
    "medium": {
        "id": "[mediumId]",
        "creation": "2023-03-16T10:31:56.000Z",
        "name": "bank_statement",
        "status": "draft",
        "type": "document",
        "url": "requests/6411e78b51ed4ef0d1756780/document-f460ddd33c65140cbc4cac480bdf2abd.pdf?Expires=1678966316&Key-Pair-Id=APKAISZ5D7DBUW5HTH7A&Signature=XhKBl9C5hRZT7TkyxxFn9TUVrZY5tKRuo0mILxMLGc9DLr3gg1REvqj0XZ46L5Fk6wsFUR6yPY-dLt3ZRBAHZYN3EJGgqLpATvNc4klwmcrlyTkD5bkjAMRgmh0QHH3x0SoFXbEN7zc7MTK583GR9uphQmAd6LWoXo72gKcsl3OiOSkCnKQ85X8Ro-mPRfvq2A4GRI2JbeYL3ZaxU0tnR9wSOPdSsjcRLpEQTPcsV6wmWAPXGpk9xmmk~Jv4tpSqkf-7sAJdDRAq9LM93~9a-uA-9Yhsp6LE5IRS81v5vasQvpdXg9e1YBF35a7L08w3QwWm5S-lMhvYEdWu5eelKg__",
        "user": "641193022bd7ecb1749136f1",
        "request": "6411e78b51ed4ef0d1756780",
        "upload": {
            "url": "<https://s3.eu-west-3.amazonaws.com/staging-cdn.october.eu>",
            "fields": {
                "key": "requests/6411e78b51ed4ef0d1756780/document-f460ddd33c65140cbc4cac480bdf2abd.pdf",
                "acl": "private",
                "bucket": "staging-cdn.october.eu",
                "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
                "X-Amz-Credential": "AKIA5Q5MBL2KWLZ4VNVP/20230316/eu-west-3/s3/aws4_request",
                "X-Amz-Date": "20230316T103156Z",
                "Policy": "eyJleHBpcmF0aW9uIjoiMjAyMy0wMy0xNlQxMDozMjo1NloiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsNDkxMSw0OTExXSxbImVxIiwiJENvbnRlbnQtVHlwZSIsImFwcGxpY2F0aW9uL3BkZiJdLHsia2V5IjoicmVxdWVzdHMvNjQxMWU3OGI1MWVkNGVmMGQxNzU2NzgwL2RvY3VtZW50LWY0NjBkZGQzM2M2NTE0MGNiYzRjYWM0ODBiZGYyYWJkLnBkZiJ9LHsiYWNsIjoicHJpdmF0ZSJ9LHsiYnVja2V0Ijoic3RhZ2luZy1jZG4ub2N0b2Jlci5ldSJ9LHsiWC1BbXotQWxnb3JpdGhtIjoiQVdTNC1ITUFDLVNIQTI1NiJ9LHsiWC1BbXotQ3JlZGVudGlhbCI6IkFLSUE1UTVNQkwyS1dMWjRWTlZQLzIwMjMwMzE2L2V1LXdlc3QtMy9zMy9hd3M0X3JlcXVlc3QifSx7IlgtQW16LURhdGUiOiIyMDIzMDMxNlQxMDMxNTZaIn1dfQ==",
                "X-Amz-Signature": "51742b9e493dce59415fd8b86affe3fd5fb6465e52e1d40d24ce785bda2851c6",
                "Content-Type": "application/pdf"
            }
        },
        "meta": {
            "name": "bank_statement_february_2022.pdf",
            "validation": "pending"
        }
    }
}

The upload contains everything needed to upload the file to our AWS S3 bucket.

Upload File to AWS S3 Bucket

To upload a file to AWS S3, you will need to make a POST HTTP request using the multipart/form-data content type header. (See FormData RFC)

The HTTP request must use the url given from the medium.upload.url field retrieved from the first step.

The HTTP request must also add all the form data from the medium.upload.fields field retrieved from the first step.

You are free to use any language or library you want to make this HTTP request.

Below, we provide you with an example using NodeJS.

<aside> ℹ️ Note: You can use Postman to autogenerate the code relative to an HTTP Request in the language of your choice.

</aside>

<aside> 📦 Note: The maximum allowed file size is 20MB.

</aside>

NodeJS example using FormData:

var fs = require('fs');

var medium = ...; // the data retrieved from step 1

// Create empty FormData object
var formData = new FormData();

// Add all key/value pairs from `medium.upload` object to the formData using FormData.append method
for (let [key, value] of Object.entries(medium.upload.fields) {
  formData.append(key, value);
}

// Add file to the formData
var fileBuffer = fs.readFileSync('./bank_statement_february_2022.pdf');
formData.append('file', fileBuffer, {
  filename: 'bank_statement_february_2022.pdf',
  contentType: 'application/pdf',
});

// Create an HTTP POST request to send the formData to aws
fetch(medium.upload.url, {
  body: formData,
  method: "POST"
})
	.then(resp => ... /* The upload is successful */)
	.catch(err => ... /* The upload failed */)

Update Medium

Once the upload to AWS was successful, you will need to update the medium to notify the API that the medium is available.

Make a POST /media/[mediumId] with the following data:

POST /media/[mediumId]

{
	"status": "online"
}

OR

{
  "status": "online",
  "meta": {
    "period": "year",
    "date": "2021-12-10"
  }
}

In the case of a periodic document (e.g: certified_financial_statement or bank_statement), you must also provide the period and date of the document during this update.

(See Upload File to AWS S3 Bucket for more details of each document type)