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:

How to create the medium in our API.
How to upload the file to our AWS S3 bucket.
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.

ℹ️

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

📦

Note: The maximum allowed file size is 20MB.

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 for more details of each document type)

Appendices:

Document Types

Certified Financial Statements

📄

Allowed formats: PDF

Two certified financial statements are required to create a request. However, based on the date the request was created, we will either ask year minus 1, 2 or 3.

Here is what is required based on the creation date of the request:

Between 1st of January and 31st of March of year Y (e.g: 2023):

Y-2 and Y-3 (e.g: 2021 and 2020)

Between 1st of April and 30th of September of year Y (e.g: 2023), two options are available to you:

Either Y-1 and Y-2 (e.g: 2022 and 2021)
Or Y-2 and Y-3 (e.g: 2021 and 2020)

Between 1st of October and 31st of December of year Y (e.g: 2023):

Y-1 and Y-2 (e.g: 2022 and 2021)

Medium example:

POST /media
{
  "name": "certified_financial_statement",
	"type": "document",
	"meta": {
		"name": "internal_financial_statement_2022.pdf",
		"size": 4911,
		"type": "application/pdf",
  },
	"request": "[requestId]"
}

---
(Upload to AWS S3)
---

POST /media/[id]
{
  "status": "online",
	"meta": {
		"period": "year",
		"date": "2022-12-10", // It is important to set the date to the 10th of December
  }
}

❗

You must use the 10th of December as the date of this yearly document.

Bank Statements

📄

Allowed formats: PDF

Bank statements can have one of those periods: month, quarter, semester.

We require Bank statements to cover the last 6 months. What this means differ based on when the request was created and the period you will use:

If you want to upload monthly statements:

For a request created between the 1st and 9th of each month (e.g: 1st of September)

We ask for the 6 months prior to the past month (e.g: Feb, Mar, Apr, May, Jun, Jul)

For a request create on or after the 10th of each month (e.g: 10th of September)

We ask for the actual last 6 months (e.g: Mar, Apr, May, Jun, Jul, Aug)

If you want to upload quarterly statements:

We ask for the last two complete quarters (Jan-Mar, Apr-Jun, Jul-Sep, Oct-Dec)

If you want to upload semesterly statements:

We ask for the last complete semester (Jan-Jun, Jul-Dec)

Medium example:

POST /media
{
  "name": "bank_statement",
	"type": "document",
	"meta": {
		"name": "hsbc_aug_2022.pdf",
		"size": 4911,
		"type": "application/pdf",
  },
	"request": "[requestId]"
}

---
(Upload to AWS S3)
---

POST /media/[id]
{
  "status": "online",
	"meta": {
		"period": "month",
		"date": "2022-08-10", // It is important to set the date to the 10th of first month of the period
  }
}

❗

For monthly, quarterly, and semesterly documents, you must use the 10th of the first month of the period. (E.g: For an Apr-Jun quarter, use the 10th of April.)

Business plan (🇫🇷 only)

📄

Allowed formats: PDF, Word, Excel, Powerpoint (and Open equivalent)

The Business plan is required only for request with an acquisition reason and using the Standard process (amount > €250k).

Medium example:

POST /media
{
  "name": "business_plan",
	"type": "document",
	"meta": {
		"name": "TheBusinessPlan.doc",
		"size": 4911,
		"type": "application/msword",
  },
	"request": "[requestId]"
}

---
(Upload to AWS S3)
---

POST /media/[id]
{
  "status": "online"
}

Sale agreement (🇫🇷 only)

📄

Allowed formats: PDF, Word (and Open equivalent)

The Sale agreement is required only for request with an acquisition reason and using the Standard process (amount > €250k).

Medium example:

POST /media
{
  "name": "sale_agreement",
	"type": "document",
	"meta": {
		"name": "sale_contract.odt",
		"size": 4911,
		"type": "application/vnd.oasis.opendocument.text",
  },
	"request": "[requestId]"
}

---
(Upload to AWS S3)
---

POST /media/[id]
{
  "status": "online"
}

Interim financial statement

📄

Allowed formats: PDF, Word, Excel (and Open equivalent)

The Interim financial statement is required only if the request uses the Standard process and the most recent certified financial statement is more than 12 months old.

Medium example:

POST /media
{
  "name": "interim_financial_statement",
	"type": "document",
	"meta": {
		"name": "FS_2023.xsl",
		"size": 4911,
		"type": "application/vnd.ms-excel",
  },
	"request": "[requestId]"
}

---
(Upload to AWS S3)
---

POST /media/[id]
{
  "status": "online"
}

Centrale Rischi (🇮🇹 only)

📄

Allowed formats: PDF

The Sale agreement is required for all Italian requests.

Medium example:

POST /media
{
  "name": "centrale_rischi",
	"type": "document",
	"meta": {
		"name": "original.pdf",
		"size": 4911,
		"type": "application/pdf",
  },
	"request": "[requestId]"
}

---
(Upload to AWS S3)
---

POST /media/[id]
{
  "status": "online"
}

← Previous

Resource: Webhooks

Resource: Testing environment

On this page

Uploading a media
Create a medium
Upload File to AWS S3 Bucket
Update Medium
Appendices:
Document Types