File Custom Field

File custom fields allow you to attach multiple files to records. Files are stored securely in AWS S3 with comprehensive metadata tracking, file type validation, and proper access controls.

Basic Example

Create a simple file field:

mutation CreateFileField {
  createCustomField(input: {
    name: "Attachments"
    type: FILE
  }) {
    id
    name
    type
  }
}

Advanced Example

Create a file field with description:

mutation CreateDetailedFileField {
  createCustomField(input: {
    name: "Project Documents"
    type: FILE
    description: "Upload project-related documents, images, and files"
  }) {
    id
    name
    type
    description
  }
}

Input Parameters

CreateCustomFieldInput

Note: Custom fields are automatically associated with the project based on the user’s current project context. No projectId parameter is required.

File Upload Process

Step 1: Upload File

First, upload the file to get a file UID:

mutation UploadFile {
  uploadFile(input: {
    file: $file  # File upload variable
    companyId: "company_123"
    projectId: "proj_123"
  }) {
    id
    uid
    name
    size
    type
    extension
    status
  }
}

Step 2: Attach File to Record

Then attach the uploaded file to a record:

mutation AttachFileToRecord {
  createTodoCustomFieldFile(input: {
    todoId: "todo_123"
    customFieldId: "file_field_456"
    fileUid: "file_uid_from_upload"
  }) {
    id
    file {
      uid
      name
      size
      type
    }
  }
}

Managing File Attachments

Adding Single Files

mutation AddFileToField {
  createTodoCustomFieldFile(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    fileUid: "file_uid_789"
  }) {
    id
    position
    file {
      uid
      name
      size
      type
      extension
    }
  }
}

Removing Files

mutation RemoveFileFromField {
  deleteTodoCustomFieldFile(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    fileUid: "file_uid_789"
  })
}

Bulk File Operations

Update multiple files at once using customFieldOptionIds:

mutation SetMultipleFiles {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    customFieldOptionIds: ["file_uid_1", "file_uid_2", "file_uid_3"]
  })
}

File Upload Input Parameters

UploadFileInput

File Management Input Parameters

File Storage and Limits

File Size Limits

Supported File Types

Images

• jpg, jpeg, png, gif, bmp, webp, svg, ico, tiff, tif

Videos

• mp4, avi, mov, wmv, flv, webm, mkv, 3gp

Audio

• mp3, wav, flac, aac, ogg, wma

Documents

• pdf, doc, docx, xls, xlsx, ppt, pptx, txt, rtf

Archives

• zip, rar, 7z, tar, gz

Code/Text

• json, xml, csv, md, yaml, yml

Storage Architecture

• Storage: AWS S3 with organized folder structure
• Path Format: companies/{companySlug}/projects/{projectSlug}/uploads/{year}/{month}/{username}/{fileUid}_{filename}
• Security: Signed URLs for secure access
• Backup: Automatic S3 redundancy

Response Fields

File Response

TodoCustomFieldFile Response

Creating Records with Files

When creating records, you can attach files using their UIDs:

mutation CreateRecordWithFiles {
  createTodo(input: {
    title: "Project deliverables"
    todoListId: "list_123"
    customFields: [{
      customFieldId: "file_field_id"
      customFieldOptionIds: ["file_uid_1", "file_uid_2"]
    }]
  }) {
    id
    title
    customFields {
      id
      customField {
        name
        type
      }
      todoCustomFieldFiles {
        id
        position
        file {
          uid
          name
          size
          type
        }
      }
    }
  }
}

File Validation and Security

Upload Validation

• MIME Type Checking: Validates against allowed types
• File Extension Validation: Fallback for application/octet-stream
• Size Limits: Enforced at upload time
• Filename Sanitization: Removes special characters

Access Control

• Upload Permissions: Project/company membership required
• File Association: ADMIN, OWNER, MEMBER, CLIENT roles
• File Access: Inherited from project/company permissions
• Secure URLs: Time-limited signed URLs for file access

Required Permissions

Error Responses

File Too Large

{
  "errors": [{
    "message": "File \"filename.pdf\": Size exceeds maximum limit of 256MB",
    "extensions": {
      "code": "BAD_USER_INPUT"
    }
  }]
}

File Not Found

{
  "errors": [{
    "message": "File not found",
    "extensions": {
      "code": "FILE_NOT_FOUND"
    }
  }]
}

Field Not Found

{
  "errors": [{
    "message": "Custom field not found",
    "extensions": {
      "code": "CUSTOM_FIELD_NOT_FOUND"
    }
  }]
}

Best Practices

File Management

• Upload files before attaching to records
• Use descriptive filenames
• Organize files by project/purpose
• Clean up unused files periodically

Performance

• Upload files in batches when possible
• Use appropriate file formats for content type
• Compress large files before upload
• Consider file preview requirements

Security

• Validate file contents, not just extensions
• Use virus scanning for uploaded files
• Implement proper access controls
• Monitor file upload patterns

Common Use Cases

1. Document Management

   • Project specifications
   • Contracts and agreements
   • Meeting notes and presentations
   • Technical documentation

2. Asset Management

   • Design files and mockups
   • Brand assets and logos
   • Marketing materials
   • Product images

3. Compliance and Records

   • Legal documents
   • Audit trails
   • Certificates and licenses
   • Financial records

4. Collaboration

   • Shared resources
   • Version-controlled documents
   • Feedback and annotations
   • Reference materials

Integration Features

With Automations

• Trigger actions when files are added/removed
• Process files based on type or metadata
• Send notifications for file changes
• Archive files based on conditions

With Cover Images

• Use file fields as cover image sources
• Automatic image processing and thumbnails
• Dynamic cover updates when files change

With Lookups

• Reference files from other records
• Aggregate file counts and sizes
• Find records by file metadata
• Cross-reference file attachments

Limitations

• Maximum 256MB per file
• Dependent on S3 availability
• No built-in file versioning
• No automatic file conversion
• Limited file preview capabilities
• No real-time collaborative editing

Related Resources

• Upload Files API - File upload endpoints
• Custom Fields Overview - General concepts
• Automations API - File-based automations
• AWS S3 Documentation - Storage backend