Skip to main content
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.
bash
curl -X POST 'https://api.cadanapay.com/v1/files/upload-url' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Response:
JSON
{
  "fileId": "517075a2-17db-469f-9481-eb8347cb920c",
  "putUrl": "https://cadana-kyc.s3.amazonaws.com/tmp/file_9c52fa2e?X-Amz-Algorithm=...",
  "expiresIn": 900
}
FieldDescription
fileIdUnique identifier to reference this file in other API calls
putUrlPre-signed URL for uploading the file bytes (single-use)
expiresInSeconds 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:
PurposeDescription
kyc-id-frontFront of a government-issued identity document
kyc-id-backBack of a government-issued identity document
kyc-selfieSelfie photo for identity verification
kyc-id-selfiePhoto of user holding their identity document
kyc-address-proofProof of address (utility bill, bank statement, etc.)
kyb-incorporation-documentCertificate of incorporation for business verification
kyb-tax-certificateTax registration certificate for business verification
kyb-address-proofProof of business address
business-onboarding-documentGeneral business onboarding document
reimbursements-proofReceipt or proof for expense reimbursement
contractEmployment or service contract PDF

​
Download a File

Retrieve file details and a pre-signed download URL by file ID.
bash
curl -X GET 'https://api.cadanapay.com/v1/files/1d3f870c-bc91-4636-a0d4-8e54bccf7d64' \
  -H 'Authorization: Bearer YOUR_API_KEY'
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 CaseAPI FieldsGuide
KYC identity verificationidDetails.frontFileId, idDetails.backFileId, idDetails.selfieFileIdKYC Verification
KYC address proofaddressProofFileIdKYC Verification
Contract uploadfileId on contract creationManage Contracts
Business onboarding (KYB)Incorporation documents, tax certificatesKYB Requirements
Beneficiary KYCfileId on beneficiary creationMaking a Payment

​
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)