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

# File Field

> File upload and storage for documents, images, and attachments

The File field enables file uploads and storage within cases. Users can upload documents, images, PDFs, contracts, and other files directly into the case. File fields integrate with Document Intelligence for automatic data extraction from uploaded documents.

Use File fields whenever you need to collect documents as part of the case workflow — identity documents, contracts, invoices, receipts, images, or any file-based information.

## When to Use

**Use File fields for:**

* Identity documents (ID cards, passports, driver's licenses)
* Contracts and agreements
* Invoices and receipts
* Proof documents (address, income, employment)
* Images and photos (damage, products, signatures)
* Medical documents
* Tax documents
* Certificates and licenses
* Supporting documentation
* Signed documents

**Consider alternatives:**

* Use **Text** for URLs to external documents
* Use **API Call** to fetch documents from external systems
* Use document generation for creating documents (not collecting them)

## Configuration Options

| Option                | Description                     | Type    | Default          | Example                          |
| --------------------- | ------------------------------- | ------- | ---------------- | -------------------------------- |
| `key`                 | Unique identifier               | String  | Required         | `identity_document`              |
| `name`                | Display label                   | String  | Required         | "Identity Document"              |
| `description`         | Help text for users             | String  | Optional         | "Upload ID card or passport"     |
| `accept`              | Allowed file types (MIME types) | Array   | All files        | `["application/pdf", "image/*"]` |
| `max_size`            | Maximum file size (bytes)       | Number  | `10485760`       | `5242880` (5MB)                  |
| `max_files`           | Maximum number of files         | Number  | `1`              | `5`                              |
| `required`            | Must upload at least one file   | Boolean | `false`          | `true`                           |
| `enable_intelligence` | Enable Document Intelligence    | Boolean | `false`          | `true`                           |
| `visibility`          | Display setting                 | String  | `always-visible` | `hide-when-empty`                |
| `section`             | Section this field belongs to   | String  | None             | Section UUID                     |

## Examples

### Identity Document

Collect government ID:

```json theme={null}
{
  "key": "identity_document",
  "type": "file",
  "name": "Identity Document",
  "description": "Upload your ID card, passport, or driver's license",
  "required": true,
  "accept": ["image/*", "application/pdf"],
  "max_size": 5242880,
  "max_files": 2,
  "enable_intelligence": true
}
```

### Invoice Upload

Collect invoices:

```json theme={null}
{
  "key": "invoices",
  "type": "file",
  "name": "Invoices",
  "description": "Upload relevant invoices (PDF format preferred)",
  "accept": ["application/pdf", "image/*"],
  "max_files": 10,
  "enable_intelligence": true
}
```

### Damage Photos

Collect images of damage:

```json theme={null}
{
  "key": "damage_photos",
  "type": "file",
  "name": "Damage Photos",
  "description": "Upload clear photos showing the damage",
  "required": true,
  "accept": ["image/jpeg", "image/png", "image/heic"],
  "max_size": 10485760,
  "max_files": 20
}
```

### Contract Document

Collect signed contract:

```json theme={null}
{
  "key": "signed_contract",
  "type": "file",
  "name": "Signed Contract",
  "description": "Upload the signed contract document",
  "required": true,
  "accept": ["application/pdf"],
  "max_files": 1,
  "enable_intelligence": true
}
```

## File Type Restrictions

Use the `accept` option to restrict file types:

### Common MIME Types

| Type         | MIME Type                                                                 | Example               |
| ------------ | ------------------------------------------------------------------------- | --------------------- |
| PDF          | `application/pdf`                                                         | Contracts, forms      |
| Images (all) | `image/*`                                                                 | Photos, scans         |
| JPEG         | `image/jpeg`                                                              | Photos                |
| PNG          | `image/png`                                                               | Screenshots, graphics |
| Word         | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | .docx files           |
| Excel        | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`       | .xlsx files           |
| All files    | `*/*`                                                                     | No restriction        |

**Examples:**

Only PDFs:

```json theme={null}
{ "accept": ["application/pdf"] }
```

PDFs and images:

```json theme={null}
{ "accept": ["application/pdf", "image/*"] }
```

Images only:

```json theme={null}
{ "accept": ["image/*"] }
```

<Warning>
  File type restrictions are enforced client-side for user experience but should
  not be relied upon for security. Always validate file types server-side.
</Warning>

## File Size Limits

Control maximum file size with `max_size` (in bytes):

| Limit | Bytes      | Configuration          |
| ----- | ---------- | ---------------------- |
| 1 MB  | 1,048,576  | `"max_size": 1048576`  |
| 5 MB  | 5,242,880  | `"max_size": 5242880`  |
| 10 MB | 10,485,760 | `"max_size": 10485760` |
| 20 MB | 20,971,520 | `"max_size": 20971520` |

**Default:** 10 MB (10,485,760 bytes)

<Info>
  Set appropriate file size limits based on expected document types. ID scans:
  5MB is sufficient. High-res photos: 10-20MB may be needed.
</Info>

## Multiple Files

Allow multiple file uploads with `max_files`:

**Single file only:**

```json theme={null}
{ "max_files": 1 }
```

**Up to 5 files:**

```json theme={null}
{ "max_files": 5 }
```

**Unlimited files:**

```json theme={null}
{ "max_files": null }
```

Use multiple files for:

* Multiple pages of same document
* Several related documents
* Multiple photos of damage
* Various supporting documents

## Document Intelligence Integration

Enable automatic data extraction with `enable_intelligence: true`:

When enabled, Document Intelligence:

* Automatically extracts data from uploaded documents
* Populates other fields in the case based on extracted data
* Validates extracted data against case schema
* Flags inconsistencies or missing information

**What Intelligence extracts:**

* Text content from PDFs
* Structured data (names, dates, amounts, addresses)
* Information from scanned documents and images
* Data from forms and tables
* Key-value pairs from documents

[Learn more about Document Intelligence →](/intelligence/document-intelligence)

## File Storage

Uploaded files are:

* Stored securely within the case
* Accessible to case members
* Included in case exports
* Retained according to workspace retention policies
* Visible in the case timeline when uploaded

**File metadata stored:**

* Original filename
* File size
* Upload timestamp
* Uploaded by (member)
* File type (MIME)

## Validation

File fields enforce upload validation:

### Required Validation

* If `required: true`, at least one file must be uploaded
* User cannot proceed without uploading

### File Type Validation

* Only specified MIME types accepted
* Rejected files show error message

### Size Validation

* Files exceeding `max_size` rejected
* Clear error message shown

### Count Validation

* Cannot exceed `max_files`
* Disable upload when limit reached

## Best Practices

**Set appropriate file types:**

* Be specific when possible (PDFs only for contracts)
* Allow both PDF and images for flexibility (scans, photos)
* Don't be overly restrictive (users may have various formats)

**Configure realistic size limits:**

* Consider document type (ID scans: 5MB, photos: 10-20MB)
* Too restrictive: frustrates users with valid files
* Too generous: allows unnecessarily large uploads

**Use clear descriptions:**

* Specify accepted formats in description
* Mention size limits if restrictive
* Explain what to upload ("front and back of ID")

**Enable Intelligence strategically:**

* Enable for documents with extractable data
* Not necessary for photos without text
* Reduces manual data entry significantly

**Multiple files configuration:**

* Single file: official documents, contracts
* Multiple files: supporting docs, damage photos
* Consider workflow: easier to upload multiple at once

**Organize with sections:**

* Group related file fields in sections
* "Identity Documents", "Financial Documents", "Photos"
* Makes case data easier to navigate

**Name fields descriptively:**

* "Identity Document" not just "Document"
* "Damage Photos" not just "Photos"
* Helps users and case managers understand purpose

***

## Related Field Types

<CardGroup cols={2}>
  <Card title="Text" icon="text" href="/cases/data_schema/text">
    Use for URLs to external documents
  </Card>

  <Card title="API Call" icon="globe" href="/cases/data_schema/api_call">
    Use to fetch documents from external systems
  </Card>

  <Card title="Document Intelligence" icon="sparkles" href="/intelligence/document-intelligence">
    Learn about automatic data extraction
  </Card>

  <Card title="Data Schema Overview" icon="sitemap" href="/cases/data_schema">
    Back to Data Schema overview
  </Card>
</CardGroup>