File Upload

Some of the activities on Cybrid platform will require you provide supporting documentation and this guide will walk you through the steps to upload files.

❗️

Important: File upload feature is available to you depending on the Cybrid platform features enabled on your partner. Contact Cybrid if you think you should have access

Uploading a file

To upload a file you use the POST /api/files endpoint. An example request body is below

{
  "type": "utility_bil",
  "filename": "bill.png",
  "customer_guid": "your-customer-guid",
  "content_type": "image/png",
  "data": "base64-encoded-document"
}

type

It is important to choose the file type correctly as it will determine what it can be used for. For example utility_bill can be used as proof of address. Cybrid features relying on files provided by you will have specific requirements on the file types required to support the activity.

data

This API will allow files to be provided inline with the file content encoded using Base64. There is a limit of 10MB on the size of data for files that require more than 10MB. The Base64-encoded string adds approximately 30% to the original file size. For example, a 7MB file will become approximately 9.1MB when encoded. If you need to upload file larger than 10MB see Uploading large files section below.

state

After creation the file will be in storing state, you will not be able to reference the file until the file has been marked with a state completed.

Uploading large files

By default, file uploads are limited to 10MB. If you need to upload larger files, do not include the data attribute in the request payload when making a POST /api/files request.

Example request:

{
  "type": "utility_bil",
  "filename": "bill.png",
  "customer_guid": "your-customer-guid",
  "content_type": "image/png"
}

The server will respond with a pre-signed upload URL in the upload_url attribute. You can use this URL to upload the file directly to our storage provider. The URL is valid until the expiration time specified in the upload_expires_at attribute.

{
  ...
  "state": "storing",
  "upload_url": "https://api-internal-files-prod.s3.amazonaws.com/...",
  "upload_expires_at": "2025-02-27T14:38:04.000Z"
}

Use curl or any HTTP client to upload the file to the provided upload_url. Below is an example using curl:

curl --location --request PUT 'https://api-internal-files-prod.s3.amazonaws.com/...' --header 'Accept: application/json' --header 'Content-Type: image/png' --data-binary '/tmp/picture.png'

Once the file is successfully uploaded, you must wait until its state is marked as completed before referencing it in other API calls.