Working with Files

Cadana uses files for identity verification (KYC), business onboarding (KYB), contracts, reimbursement proofs, and address verification. All files follow a two-step upload flow: first reserve a file ID and pre-signed URL, then upload the file bytes directly to cloud storage.

Upload a File

Step 1: Reserve a file ID

Call the upload URL endpoint with the file’s purpose and contentType. You’ll receive a fileId to reference in later API calls and a putUrl to upload the actual file. Response:

JSON

{
  "fileId": "517075a2-17db-469f-9481-eb8347cb920c",
  "putUrl": "https://cadana-kyc.s3.amazonaws.com/tmp/file_9c52fa2e?X-Amz-Algorithm=...",
  "expiresIn": 900
}

Field	Description
`fileId`	Unique identifier to reference this file in other API calls
`putUrl`	Pre-signed URL for uploading the file bytes (single-use)
`expiresIn`	Seconds until the `putUrl` expires (900 = 15 minutes)

Step 2: Upload the file

Use the putUrl from the response to upload the file bytes with an HTTP PUT request. Set the Content-Type header to match the contentType you specified in Step 1.

Bash

curl -X PUT '{putUrl}' \
  -H 'Content-Type: image/jpeg' \
  --data-binary @/path/to/document.jpg

The putUrl expires after 15 minutes and can only be used once. If it expires, request a new upload URL.

Once the upload completes, the fileId is ready to use in API calls like KYC submission, contract upload, or beneficiary creation.

File Purposes

Each file must be tagged with a purpose that describes how it will be used. The following values are supported:

Purpose	Description
`kyc-id-front`	Front of a government-issued identity document
`kyc-id-back`	Back of a government-issued identity document
`kyc-selfie`	Selfie photo for identity verification
`kyc-id-selfie`	Photo of user holding their identity document
`kyc-address-proof`	Proof of address (utility bill, bank statement, etc.)
`kyb-incorporation-document`	Certificate of incorporation for business verification
`kyb-tax-certificate`	Tax registration certificate for business verification
`kyb-address-proof`	Proof of business address
`business-onboarding-document`	General business onboarding document
`reimbursements-proof`	Receipt or proof for expense reimbursement
`contract`	Employment or service contract PDF
`statutory-document`	Supporting document for a statutory filing field (e.g. an identity card or signed offer letter)

Download a File

Retrieve file details and a pre-signed download URL by file ID. Response:

JSON

{
  "fileId": "1d3f870c-bc91-4636-a0d4-8e54bccf7d64",
  "purpose": "kyc-id-front",
  "getUrl": "https://cadana-kyc.s3.amazonaws.com/...",
  "expiresIn": 899,
  "createdAt": 1748478276,
  "tenantKey": "cad95193904"
}

The getUrl is a pre-signed, single-use download link. Request a new one each time you need to download the file.

Where Files Are Used

Use Case	API Fields	Guide
KYC identity verification	`idDetails.frontFileId`, `idDetails.backFileId`, `idDetails.selfieFileId`	KYC Verification
KYC address proof	`addressProofFileId`	KYC Verification
Contract upload	`fileId` on contract creation	Manage Contracts
Business onboarding (KYB)	Incorporation documents, tax certificates	KYB Requirements
Beneficiary KYC	`fileId` on beneficiary creation	Making a Payment
Statutory filing documents	`document`-typed fields in the statutory fields endpoints	Statutory: Getting Started

Image Requirements

Supported formats: JPEG, PNG
Images must be clear and readable
All text and photos on the document must be visible
File size should be reasonable for the document type (typically under 10 MB)

Overview

Payments API

Wallets API

Workforce API

Tax API

Statutory Compliance API

Upload a File

Step 1: Reserve a file ID

Step 2: Upload the file

File Purposes

Download a File

Where Files Are Used

Image Requirements

​Upload a File

​Step 1: Reserve a file ID

​Step 2: Upload the file

​File Purposes

​Download a File

​Where Files Are Used

​Image Requirements

Upload a File

Step 1: Reserve a file ID

Step 2: Upload the file

File Purposes

Download a File

Where Files Are Used

Image Requirements