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

# File Uploads & Attachments Guide

> Complete guide to working with files and attachments in Elementum

Learn successful strategies about working with files and attachments in Elementum, including size limits, upload methods, and best practices.

<Info>
  **File Size Limit**: Elementum supports file uploads up to **250MB** per file across all upload methods. Note that email attachments have a lower limit of 25MB due to email service provider restrictions.
</Info>

## Understanding Files in Elementum

Elementum provides multiple ways to work with files, each designed for specific use cases. Understanding the differences will help you choose the right approach for your needs.

### File Fields vs Attachments Component

<CardGroup cols={2}>
  <Card title="File Fields" icon="file">
    **Purpose**: Store a specific file in a designated field on a record

    **Use Cases**:

    * Invoice file field on invoice records
    * Contract document field on contract records
    * Photo field on product records

    **Characteristics**: Single file per field, structured storage
  </Card>

  <Card title="Attachments Component" icon="paperclip">
    **Purpose**: General-purpose file and link storage area for multiple items

    **Use Cases**:

    * Supporting documents for a record
    * Multiple files uploaded by email
    * User-added supplementary files
    * Links to external resources or related records

    **Characteristics**: Multiple files and links, flexible storage
  </Card>
</CardGroup>

<Note>
  Both File Fields and the Attachments component support files up to 250MB per file. They are complementary: use File Fields for structured, specific files and the Attachments component for general-purpose file storage.
</Note>

***

## Where attachments are stored

Attachment files are stored in Elementum-managed cloud storage — separate from any connected data warehouse. If you use a [Snowflake CloudLink](/administration/connect-snowflake-to-elementum) (or a [BigQuery](/guides/connect-bigquery-to-elementum) or [Databricks](/guides/connect-databricks-to-elementum) CloudLink), Elementum does not write attachment files, blob columns, or a dedicated attachments table into your warehouse.

| What                                                                                     | Where it lives                                                                                          |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **File contents** — the bytes of the PDF, image, spreadsheet, and so on                  | Elementum-managed cloud storage                                                                         |
| **Attachment metadata** — name, description, media type, size, URL, uploader, timestamps | Elementum's platform; available through automations and the [REST API](/api-reference/api-introduction) |
| **Other record fields** — text, numbers, references, and so on                           | The connected warehouse table for warehouse-backed apps, or Elementum's platform for platform apps      |

<Note>
  Attachments are tied to the lifecycle of their record. When a record is deleted, its attachment files are also removed from Elementum-managed storage. If you need to keep files after the record goes away, archive them out to your own storage first (see [Long-term archival](#accessing-attachments-for-analytics-or-external-systems) below).
</Note>

### Accessing attachments for analytics or external systems

Because attachment files aren't materialized in your warehouse, plan analytics and integrations around Elementum's API and automations instead of warehouse queries:

* **Attachment inventories and reporting** — List attachments on a record through the [REST API](/api-reference/api-introduction), or use the **Attachment is Added** [automation trigger](/workflows/automation-triggers-reference) to push metadata into your reporting system as new files arrive.
* **Downloading a file programmatically** — Use the attachment's `URL` returned by the API or trigger. That URL requires an authenticated Elementum session; for recipients who don't have an Elementum account, use [public attachment links](#public-attachment-links).
* **Long-term archival** — Copy files to your own storage from an automation (**Attachment is Added** → **Send API Request** to your archive endpoint) before the source record is deleted.

***

## Methods for Adding Files to Records

There are six primary ways to add files and links to records in Elementum. Each method serves different scenarios and integration needs.

### Manual Upload in Layouts

**How it works**: Users directly upload files in the record details.

**Best for**:

* User-initiated file uploads
* Interactive workflows requiring document submission
* Ad-hoc file additions to existing records

**Implementation**:

1. Add a File field to your [layout](/workflows/layouts) for specific files
2. Add the Attachments component for general file storage
3. Configure field visibility and permissions as needed

<AccordionGroup>
  <Accordion title="Example Use Cases">
    * Employee uploading resume during onboarding
    * Customer submitting proof of purchase
    * Team member attaching project deliverables
  </Accordion>
</AccordionGroup>

***

### Adding Links to Attachments

**How it works**: Users can add external links to a record's Attachments section, providing quick access to related web resources without uploading a file.

**Best for**:

* Referencing related records or external resources
* Linking to documents stored in third-party systems
* Providing quick access to relevant URLs from within a record

**Steps to add a link**:

1. Navigate to the record where you want to add the link and locate the **Attachments** section.
2. Click the **Add Link** button in the upper-right corner of the Attachments section.
3. In the dialog that appears, fill in the **Label** (a descriptive name for the link) and **URL** (the full URL to the external resource).
4. Click **Save** to add the link to the record's attachments. The link will appear in the Attachments section alongside any uploaded files.

<Tip>
  Links added to the Attachments section are a convenient way to cross-reference related records or external resources without duplicating files. For example, you can link to a customer record, a Confluence page, or a shared drive document.
</Tip>

***

### Email Received Trigger

**How it works**: When automations create records from emails, any email attachments are automatically added to the new record.

**Best for**:

* Email-to-record workflows
* Support ticket systems
* Document collection via email

**Configuration**:

```
Email Received Trigger → Create Record (Support Ticket)
  → Email attachments automatically saved to record
```

<Note>
  Multiple attachments are supported. Use "Repeat for Each" action to process multiple attachments. Access attachments via `trigger.attachments` variable.
</Note>

<AccordionGroup>
  <Accordion title="Example Use Cases">
    * Support tickets with customer-submitted screenshots
    * Invoice processing from emailed PDFs
    * Document collection via dedicated email addresses
  </Accordion>
</AccordionGroup>

***

### Send API Request Action

**How it works**: Download files from external APIs and save them as attachments using automation actions.

**Best for**:

* Integration with external systems
* Automated file collection from APIs
* Scheduled file downloads

**Configuration**:

```
Automation Trigger → Send API Request (download file)
  → Save Attachment (store to record)
```

**Setup Notes**:

* Set response type to FILE in Send API Request action
* Use Save Attachment action to store the downloaded file
* Supports various authentication methods (Bearer, OAuth, Basic Auth)

<AccordionGroup>
  <Accordion title="Example Use Cases">
    - Downloading reports from external reporting systems
    - Fetching documents from cloud storage APIs
    - Retrieving generated files from third-party services
  </Accordion>
</AccordionGroup>

***

### External API Integration

**How it works**: Third-party systems add attachments via Elementum's REST API endpoints.

**Best for**:

* System-to-system integrations
* Custom applications adding files to Elementum
* Automated workflows in external systems

**API Endpoint**:

```
POST https://api.elementum.io/v1/elements/testelement/TTE-11/attachments
Authorization: Bearer <access_token>
Content-Type: multipart/form-data
```

**Requirements and usage**:

* Requires OAuth 2.0 authentication
* Supports files up to 250MB
* Returns attachment metadata upon success
* Replace `elements`, `testelement`, and `TTE-11` with your specific values
* See [API Documentation](/api-reference/api-introduction) for details

<AccordionGroup>
  <Accordion title="Example Use Cases">
    - CRM system attaching contracts to customer records
    - Document management system syncing files
    - Custom applications uploading generated reports
  </Accordion>
</AccordionGroup>

***

### File Fields in Records

**How it works**: Users or automations populate specific File field types on records.

**Best for**:

* Structured file storage with specific meaning
* Required documents in workflows
* Single file per field requirements

**Configuration**:

1. Create a File field in your Element definition
2. Add the field to your layout
3. Set field as required or optional

**Characteristics**:

* One file per field (unlike Attachments component)
* Field-specific permissions and validations
* Can be referenced in automations and reports

<AccordionGroup>
  <Accordion title="Example Use Cases">
    - "Invoice PDF" field on invoice records
    - "Employee Photo" field on employee records
    - "Contract Document" field on contract records
  </Accordion>
</AccordionGroup>

***

## Public Attachment Links

By default, attachments on records are private and require users to be logged into Elementum to access them. However, you can make individual attachments publicly accessible so that recipients of notifications (such as email or Slack messages) can view or download the file without needing to log in.

This is especially useful when notifications are sent to external stakeholders, vendors, or collaborators who may not have an Elementum account.

### Making an Attachment Public

1. Navigate to the record and open the **Attachments** section.
2. Locate the attachment you want to make public.
3. Click the <img src="https://mintcdn.com/elementum/BqmC-XUyw4vSbmde/images/icons/eye.svg?fit=max&auto=format&n=BqmC-XUyw4vSbmde&q=85&s=ee0cf485fd9a737cd2c19cb780f106da" alt="Public visibility icon" className="inline-ui-icon" width="24" height="24" data-path="images/icons/eye.svg" /> **visibility icon** next to the attachment.
4. The attachment is now public. When this record's notifications include the attachment, recipients can access it without logging in.

To revert an attachment to private, click the visibility icon again. Private attachments require the recipient to log into Elementum before they can be accessed.

<Info>
  The public visibility setting applies per attachment. You can choose which specific files on a record are publicly accessible and which remain private. Each public attachment link included in a notification is valid for **30 days** from the time the notification is sent.
</Info>

### When to Use Public Links

* **External collaboration**: Share files with vendors, customers, or partners who receive Elementum notifications but do not have platform accounts
* **Streamlined access**: Allow notification recipients to open attachments directly from their email or Slack message without an extra login step
* **Selective sharing**: Keep sensitive attachments private while making general reference documents publicly accessible on the same record

<Warning>
  Public attachments can be accessed by anyone who has the link. Only make attachments public when the file content is appropriate for access without authentication. Sensitive or confidential documents should remain private.
</Warning>

***

## File Size Limits Summary

<Warning>
  Understanding file size limits is critical for designing reliable workflows and setting user expectations.
</Warning>

| Operation                              | Maximum Size | Notes                                      |
| -------------------------------------- | ------------ | ------------------------------------------ |
| **File Field Upload**                  | 250MB        | Per file                                   |
| **Attachments Component**              | 250MB        | Per file, multiple files supported         |
| **Email Attachments (Email Received)** | 250MB        | Per file (system limit)                    |
| **Email Attachments (Send Email)**     | 25MB         | Total size of all attachments in one email |
| **API Upload**                         | 250MB        | Per file                                   |
| **File Reader Processing**             | 250MB        | Per file                                   |
| **Survey File Upload**                 | 250MB        | Per file                                   |

<Note>
  The 25MB limit for **sending** email attachments is due to email service provider restrictions and is separate from the 250MB system-wide limit for file storage.
</Note>

***

## Working with Files in Automations

Automations provide powerful capabilities for processing and managing files automatically.

### Accessing File Information

**Email Received Trigger**:

```
trigger.attachments - Array of attachment objects
trigger.attachments[0].name - Filename
trigger.attachments[0].mediaType - File type
trigger.attachments[0].url - File URL
```

**Attachment is Added Trigger**:

```
trigger.Name - Filename
trigger.Description - Attachment description
trigger.Media Type - File extension/format
trigger.URL - File URL
trigger.Size - File size
```

### Processing Files

<AccordionGroup>
  <Accordion title="Read File Action">
    Extract text content from PDFs, DOC, DOCX, TXT, CSV, and Excel files.

    **Example**:

    ```
    Attachment Added → Read File → Extract text content
      → Use in AI Classification or Update Record Fields
    ```
  </Accordion>

  <Accordion title="AI File Analysis Action">
    Use AI to intelligently analyze documents and extract structured data.

    **Example**:

    ```
    Contract PDF → AI File Analysis
      → Extract: Parties, Dates, Terms, Obligations
      → Update Record Fields with structured data
    ```
  </Accordion>

  <Accordion title="Read Bulk File Action">
    Process multiple files simultaneously for batch operations.

    **Example**:

    ```
    Multiple Reports Uploaded → Read Bulk File
      → Process all files → Aggregate data
    ```
  </Accordion>

  <Accordion title="Save Attachment Action">
    Save files to specific records programmatically.

    **Example**:

    ```
    Email with PDFs → Repeat for Each (attachment)
      → Save Attachment to Customer Record
    ```
  </Accordion>
</AccordionGroup>

### Sending Files via Email

When sending emails with attachments in automations, you can attach files from multiple sources:

**Attachment Sources**:

* **Record File Fields**: Attach files from specific file fields on the trigger record
* **Attachments Block**: Attach all files from the record's attachments component
* **Workflow File Fields**: Attach files from file fields available in the workflow context

<Warning>
  Remember: Total email attachment size is limited to **25MB** when sending emails. If you exceed this limit, the email will fail to send.
</Warning>

***

## Best Practices

### File Size Management

<AccordionGroup>
  <Accordion title="Set Clear Expectations">
    * Display file size limits in your forms and interfaces
    * Include size limits in survey instructions
    * Provide clear error messages when limits are exceeded
  </Accordion>

  <Accordion title="Optimize File Processing">
    * Use File Readers for structured data extraction
    * Process large files asynchronously when possible
    * Consider file size when designing email workflows
  </Accordion>

  <Accordion title="Email Attachment Strategy">
    * Keep email attachments under 25MB total
    * For larger files, use File Fields or direct uploads
    * Consider providing download links instead of attaching large files
  </Accordion>
</AccordionGroup>

### File Organization

<AccordionGroup>
  <Accordion title="Use File Fields for Structure">
    * Create specific File fields for important documents (e.g., "Contract", "Invoice")
    * Use meaningful field names that indicate file purpose
    * Set File fields as required when documents are mandatory
  </Accordion>

  <Accordion title="Use Attachments for Flexibility">
    * Use the Attachments component for supplementary files
    * Allow users to add multiple supporting documents
    * Leverage attachments for email-based file collection
  </Accordion>

  <Accordion title="Naming Conventions">
    * Encourage meaningful file names from users
    * Use automation to rename files based on record data
    * Include dates or identifiers in file names for easier searching
  </Accordion>
</AccordionGroup>

### Security & Compliance

<AccordionGroup>
  <Accordion title="File Type Validation">
    * Use "Attachment is Added" trigger to validate file types
    * Block or flag unexpected file types
    * Implement virus scanning for sensitive environments
  </Accordion>

  <Accordion title="Access Control">
    * Configure field-level permissions for sensitive files
    * Use record-level permissions to control file access
    * Audit file access through activity logs
    * Review which attachments are set to [public visibility](#public-attachment-links) and ensure only non-sensitive files are shared publicly
  </Accordion>

  <Accordion title="Sensitive Data Handling">
    * Never commit files with credentials or secrets (.env, credentials.json)
    * Use AI File Analysis to scan for sensitive information
    * Implement approval workflows for sensitive document types
  </Accordion>
</AccordionGroup>

***

## Troubleshooting Common Issues

<AccordionGroup>
  <Accordion title="File Upload Failures">
    **Symptoms**: File upload fails or times out

    **Solutions**:

    * Verify file is under 250MB size limit
    * Check internet connection and upload speed
    * Try uploading a smaller file to isolate the issue
    * Review browser compatibility (test different browsers)
  </Accordion>

  <Accordion title="Email Attachment Errors">
    **Symptoms**: "Email failed to send" errors in automation logs

    **Solutions**:

    * Verify total attachment size is under 25MB
    * Check that all referenced file fields contain valid files
    * Ensure file URLs are accessible
    * Review email service provider status
  </Accordion>

  <Accordion title="File Processing Issues">
    **Symptoms**: File Readers fail to extract data correctly

    **Solutions**:

    * Verify file format is supported (PDF, DOC, DOCX, TXT, CSV, Excel)
    * Check file size is under 250MB
    * Test with a simpler file to rule out corruption
    * Review File Reader configuration and field mappings
  </Accordion>

  <Accordion title="API Upload Problems">
    **Symptoms**: API returns errors when uploading files

    **Solutions**:

    * Verify OAuth token is valid and not expired
    * Check Content-Type header is set to multipart/form-data
    * Ensure file size is under 250MB
    * Review API error message for specific issues
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Automation Actions" icon="bolt" href="/workflows/automation-actions-reference">
    Learn about file-related automation actions like Read File, AI File Analysis, and Save Attachment
  </Card>

  <Card title="Automation Triggers" icon="play" href="/workflows/automation-triggers-reference">
    Understand the Email Received and Attachment is Added triggers for file workflows
  </Card>

  <Card title="File Readers" icon="file-lines" href="/workflows/file-reader-overview">
    Explore File Reader types and how to extract data from documents
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/api-introduction">
    Review API endpoints for programmatic file uploads and management
  </Card>

  <Card title="Layouts & Fields" icon="window" href="/workflows/layouts">
    Configure File fields and Attachments component in your record layouts
  </Card>

  <Card title="Survey System" icon="clipboard-list" href="/workflows/survey-system">
    Use Upload File question type in surveys for collecting files from respondents
  </Card>
</CardGroup>

***

## Summary

* **File Size Limit**: 250MB per file (25MB for email sending)
* **Six Upload Methods**: Manual, Add Link, Email, API Action, External API, File Fields
* **Two Storage Types**: File Fields (structured) and Attachments Component (flexible)
* **Public Links**: Make individual attachments accessible to notification recipients without login
* **Automation Support**: Read, analyze, and process files in workflows
* **Best Practice**: Choose the right method for your use case and set clear expectations

<Tip>
  Start with manual uploads and the Attachments component for simple use cases, then expand to automated file processing as your workflows mature.
</Tip>