File Upload

Overview

Some Cybrid platform activities require supporting documentation. This guide covers how to upload files.

ℹ️

Feature availability

File upload availability depends on the features enabled for your partner. Contact Cybrid if you need access.

Upload a file

Use POST /api/files to upload a file. Example request:

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

File type

Choose the correct type as it determines what the file can be used for. For example, utility_bill serves as proof of address. Features relying on uploaded files have specific type requirements.

Inline data

The data field accepts Base64-encoded file content with a 10 MB limit. Base64 encoding adds approximately 30% to file size (e.g., a 7 MB file becomes ~9.1 MB encoded). For larger files, see Uploading large files below.

File state

After creation, the file is in state: "storing". You cannot reference the file until it reaches state: "completed".

Uploading large files

For files exceeding 10 MB, omit the data field in the request:

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

The response includes an upload_url (pre-signed URL) and upload_expires_at timestamp:

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

Upload the file to the upload_url using any HTTP client:

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'

Wait until the file state reaches completed before referencing it in other API calls.