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” |
ai_description | Hint for Intelligence | String | Optional | ”Government-issued ID document” |
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:
{
"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,
"ai_description": "Government-issued identity document such as ID card, passport, or driver's license. Intelligence should extract name, date of birth, document number, and expiration date."
}
Invoice Upload
Collect invoices:
{
"key": "invoices",
"type": "file",
"name": "Invoices",
"description": "Upload relevant invoices (PDF format preferred)",
"accept": ["application/pdf", "image/*"],
"max_files": 10,
"enable_intelligence": true,
"ai_description": "Invoices related to this claim. Intelligence should extract invoice number, date, amount, and vendor information from each invoice."
}
Damage Photos
Collect images of damage:
{
"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,
"ai_description": "Photos showing damage to property or vehicle. Used for visual assessment of claim."
}
Contract Document
Collect signed contract:
{
"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,
"ai_description": "The signed contract document. Intelligence should verify signatures are present and extract contract date and parties."
}
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 |
{"accept": ["application/pdf"]}
{"accept": ["application/pdf", "image/*"]}
File type restrictions are enforced client-side for user experience but should not be relied upon for security. Always validate file types server-side.
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 |
Set appropriate file size limits based on expected document types. ID scans: 5MB is sufficient. High-res photos: 10-20MB may be needed.
Multiple Files
Allow multiple file uploads with max_files:
Single file only:
Up to 5 files:
Unlimited files:
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
AI Description for Intelligence:
The ai_description guides what Intelligence should extract:
{
"ai_description": "Government-issued identity document. Extract: full name, date of birth, document number, issue date, expiration date, nationality."
}
- List the exact fields to extract
- Mention document types Intelligence should expect
- Specify format of extracted data
- Indicate required vs optional extractions
The more specific your AI description, the better Intelligence performs. Explicitly list which data points to extract from uploaded documents.
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
