> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cadanapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with Files

> Upload and download files for KYC documents, contracts, address proofs, and more

export const ApiExample = ({method = "GET", path, params, body, reference, tenantKey}) => {
  const baseUrl = "https://api.cadanapay.com";
  const query = params ? "?" + Object.entries(params).map(([k, v]) => `${k}=${v}`).join("&") : "";
  const url = `${baseUrl}${path}${query}`;
  const isPlatformPath = (/^\/(v1\/)?platform(\/|$)/).test(path || "");
  const includeTenantKey = tenantKey === undefined ? !isPlatformPath : tenantKey;
  let curl = `curl -X ${method} '${url}' \\\n  -H 'Authorization: Bearer YOUR_API_KEY'`;
  if (includeTenantKey) {
    curl += ` \\\n  -H 'X-MultiTenantKey: YOUR_BUSINESS_TENANT_KEY'`;
  }
  if (body) {
    const formatted = JSON.stringify(body, null, 2);
    curl += ` \\\n  -H 'Content-Type: application/json' \\\n  -d '${formatted}'`;
  }
  return <div>
      <CodeBlock language="bash" filename="bash" wrap>
        {curl}
      </CodeBlock>
      {reference && <div style={{
    marginTop: "-0.5rem",
    marginBottom: "1rem"
  }}>
          <a href={reference} style={{
    fontSize: "0.875rem"
  }}>
            Try it in the playground →
          </a>
        </div>}
    </div>;
};

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.

<ApiExample method="POST" path="/v1/files/upload-url" body={{ purpose: "kyc-id-front", contentType: "image/jpeg" }} reference="/api-reference/workforce/files/create-upload-url" />

**Response:**

```json JSON theme={null}
{
  "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 Bash theme={null}
curl -X PUT '{putUrl}' \
  -H 'Content-Type: image/jpeg' \
  --data-binary @/path/to/document.jpg
```

<Warning>
  The `putUrl` expires after **15 minutes** and can only be used once. If it expires, request a new upload URL.
</Warning>

Once the upload completes, the `fileId` is ready to use in API calls like [KYC submission](/platform/kyc-verification), [contract upload](/workforce/manage-contracts), 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.

<ApiExample method="GET" path="/v1/files/1d3f870c-bc91-4636-a0d4-8e54bccf7d64" reference="/api-reference/workforce/files/get-file-details" />

**Response:**

```json JSON theme={null}
{
  "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](/platform/kyc-verification)                        |
| KYC address proof          | `addressProofFileId`                                                      | [KYC Verification](/platform/kyc-verification#address-proof-document) |
| Contract upload            | `fileId` on contract creation                                             | [Manage Contracts](/workforce/manage-contracts)                       |
| Business onboarding (KYB)  | Incorporation documents, tax certificates                                 | [KYB Requirements](/platform/kyb-requirements)                        |
| Beneficiary KYC            | `fileId` on beneficiary creation                                          | [Making a Payment](/payments/making-a-payment)                        |
| Statutory filing documents | `document`-typed fields in the statutory fields endpoints                 | [Statutory: Getting Started](/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)