File Field

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

Examples: Only PDFs:

{"accept": ["application/pdf"]}

PDFs and images:

{"accept": ["application/pdf", "image/*"]}

Images only:

{"accept": ["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`

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

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:

{"max_files": 1}

Up to 5 files:

{"max_files": 5}

Unlimited files:

{"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

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."
}

Be specific:

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.

Learn more about 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

Text

Use for URLs to external documents

API Call

Use to fetch documents from external systems

Document Intelligence

Learn about automatic data extraction

Data Schema Overview

Back to Data Schema overview

Get Started

Workspace

Cases

Forms

Penscript

When to Use

Configuration Options

Examples

Identity Document

Invoice Upload

Damage Photos

Contract Document

File Type Restrictions

Common MIME Types

File Size Limits

Multiple Files

Document Intelligence Integration

File Storage

Validation

Required Validation

File Type Validation

Size Validation

Count Validation

Best Practices

Text

API Call

Document Intelligence

Data Schema Overview

Get Started

Workspace

Cases

Forms

Penscript

​When to Use

​Configuration Options

​Examples

​Identity Document

​Invoice Upload

​Damage Photos

​Contract Document

​File Type Restrictions

​Common MIME Types

​File Size Limits

​Multiple Files

​Document Intelligence Integration

​File Storage

​Validation

​Required Validation

​File Type Validation

​Size Validation

​Count Validation

​Best Practices

​Related Field Types

Text

API Call

Document Intelligence

Data Schema Overview

When to Use

Configuration Options

Examples

Identity Document

Invoice Upload

Damage Photos

Contract Document

File Type Restrictions

Common MIME Types

File Size Limits

Multiple Files

Document Intelligence Integration

File Storage

Validation

Required Validation

File Type Validation

Size Validation

Count Validation

Best Practices

Related Field Types