Custom Metadata
Custom Metadata lets you add your own key-value pairs to files and folders, capturing information that isn't part of the system-generated metadata like name, size, or modification date. Common uses include workflow status, compliance classifications, external identifiers, and free-form notes. Custom Metadata can be viewed or modified by any user or API client with the appropriate permissions.
When the same kinds of metadata recur across many folders, Metadata Categories are the recommended way to structure them. A category predefines a set of keys and, optionally, a fixed list of allowed values for each key that can be assigned to folders, replacing free-form entry with a consistent, validated schema.
Files uploaded through Share Links and Inboxes with a Custom Form automatically receive the registration's custom answers as metadata, with question labels as keys. This lets a receiving team or application associate files with the information supplied at submission. These values follow the same viewing and editing permissions as other Custom Metadata; access to the registration is not required to read the file's copy.
Uses of Custom Metadata
Custom Metadata records business context alongside a file. Use it to identify a delivery, classify its contents, or record the stage it has reached in your process.
File Processing and Task Management
An insurance company processing claims can use Custom Metadata to streamline document management. Files received from patients through inboxes can include fields like 'Insurance Type,' 'Patient ID,' 'Claim Officer,' and 'Status.'
As each claim progresses, a claim processor can update these fields to indicate the current status, such as 'Under Review,' 'Approved,' or 'Rejected.' This organized approach helps insurance companies manage claims more effectively, as team members can quickly locate and track documents based on specific claim information.
File Classification for Compliance
For organizations with compliance requirements, Custom Metadata can be used to associate files with key information needed to meet regulatory standards. For example, if you need to identify folders containing sensitive information, adding a 'compliance category' key with the value 'sensitive' can fulfill this requirement, ensuring that sensitive files are clearly marked and easily trackable.
File Lifecycle Management
Custom Metadata is also helpful in managing file lifecycle stages. A 'status' key can reflect the current phase of a file, with values such as 'draft,' 'rejected,' or 'approved.' This allows teams to quickly understand where a file is in its workflow, enabling smoother handoffs and reducing the risk of miscommunication.
Integrations with External Applications and Workflows
External applications can use Custom Metadata to tag files and folders with specific identifiers, such as customer numbers, order numbers, or invoice IDs by using Files.com APIs. This supports cross-referencing with other databases and systems, helping to maintain a unified data structure across platforms.
Custom Metadata with Notes and Priority Color
Custom metadata allows you to store important notes or instructions directly in a file’s metadata. By creating a 'notes' key, you can add up to 1024 characters of text, including warnings, guidelines, or other relevant information. This feature is especially useful for files that require specific handling or extra attention, keeping essential information accessible without needing separate documentation.
When combined with Priority Color, which provides a visual tagging option for files and folders, your users can easily identify files with specific colors and view notes in the custom metadata for added structure and organization in their file management.
Keys and Values
Custom Metadata supports up to 32 keys per file or folder. Each key name can be up to 256 characters, and each value up to 1024 characters. Values are always stored as text — for example, instead of a Boolean false, you would store the text string "false".
Who Can Add or Modify Custom Metadata
Uploaders with Write permission have a temporary allowance to add or modify custom metadata on files they created. This lets them attach information to a delivery without needing Full permission to manage existing files.
| Action | Required permission |
|---|---|
| View existing custom metadata | Any permission level that includes List access: List, List/Preview, Read, Read/Write, Full, or Admin. Write alone (without List or Read) also lets you see subfolders and their custom metadata, since Write includes the ability to list subfolders. Write alone does not allow listing files or viewing their custom metadata. |
| Add or modify custom metadata | Full or Admin permission on the parent folder of the file or folder being modified. Write permission on the parent folder also lets you add or modify custom metadata on a file you created, for 15 minutes after the file was last modified. This allowance belongs to the file and its creator, independently of the upload replacement allowance for the user and path. |
With Full or Admin permission, you can view, add, and edit custom metadata directly through the Files.com web app. External applications can also read, add, or modify custom metadata using the Files.com API for integration with other systems.
Archive Only Mode further restricts changes to a file's custom metadata: only the user who uploaded the file can add or modify it, and only within 15 minutes of the upload. Full or Admin folder permission does not override this limit.
After that window, nobody can change the file's custom metadata, including Site Administrators, through any connection method. Plan to attach the information needed for the archive as part of the upload workflow.
Searching Custom Metadata
Custom Metadata values can be searched within the current folder using the top search bar in the File Manager. When a search term is entered, a suggestion is shown that allows the search to be limited to metadata values in the current folder.
Custom Metadata values can also be searched by individual metadata keys by adding those keys as columns in the files table. When a Custom Metadata key is added as a column, the column includes its own search, letting you filter files and folders by values for that specific metadata key.
Custom Metadata value searches are case insensitive, whether you use the search bar, a metadata column, the API, or an SDK. Searching for abc-123 matches a value of ABC-123, so finding an identifier does not depend on remembering its capitalization. Metadata key names are matched exactly, including case: invoice_id and Invoice_ID select different keys.
Metadata search is useful when the same folder contains many items, or when file names and folder structure do not include the identifier you need. Common examples include looking up items by an external ID (customer ID, claim number, order number, invoice ID) or filtering a working folder by workflow fields like status or owner.
Custom Metadata search also supports searching across folders. The search scope selects whether to search one folder or across the folders you can access in the selected Workspace. This is useful when you know an identifier but do not know where the item was filed.