How to upload files via CSV in DAM?

This article explains how CSV upload in DAM works, what you need before you start, how to structure your CSV file, and what to do if an upload doesn't go as planned.

What You'll Need Before You Start

To upload files via CSV, your account's user level or Security Template must have the following permissions:

• FILE_UPLOAD 

• FILE_SET_VISIBILITY 

• FILE_META_CHANGE

• DIR_CREATE 

If any of these permissions are missing, the CSV will fail validation, even if everything else is set up correctly. If you're not sure which permissions your account has, contact your account administrator or reach out to support.

Step 1: Create Your CSV with the Required Columns

Every CSV upload needs three columns:

Column	Description
file_url	The direct URL where the file is currently hosted
file_name	The name the file should have once it's uploaded in Filerobot DAM
target_folder	The folder where the file should be uploaded

Example:

file_url	file_name	target_folder
https://samples.scaleflex.com/bIRDs.jpg	birds.jpg	sfxtest

This is the minimum you need to upload files successfully. If you'd also like your files to be uploaded with metadata already filled in, continue to the next step.

Step 2: Add Metadata Columns 

Adding metadata columns to your CSV means your files come in fully described and tagged, saving you from editing each file individually after upload.

Your metadata columns must match the metadata fields already set up for your account. Each field has its own API key, which you can find in your account's metadata configuration section. Use these API keys as your column headers.

Important Note:

• If a metadata field is AI-enabled or AI-generated (for example, AI Tags or AI Description), leave that column empty. These values are generated automatically once assets are uploaded successfully, and shouldn't be filled in manually.
• Include a column for every metadata field configured on your account, even ones you don't plan to fill in. If you don't want to provide a value for a field, leave the column blank, but the column itself must still be present in the CSV.

Language Variants

If your account has multiple languages configured, for example:

English, Dutch, German (Germany), French (France), Spanish (Spain), Italian

Then any metadata field set up as a language variant needs a separate column for each language. Example: For a field like "Short Description," this means:

• short_desc_es – Short Description (Spanish, Spain)

• short_desc_fr – Short Description (French, France)

• short_desc_it – Short Description (Italian)

• short_desc_nl – Short Description (Dutch)

• short_desc_de – Short Description (German, Germany)

• short_desc_en – Short Description (English)

The same rule applies to Custom tags or any other metadata field if they are set up as a regional/language variant field, you'll need a separate column per language, following the same naming pattern. If there is no language variant/regional variant then you are free to use the exact API key for the metadata.

Once your columns are ready, fill in the data for each file, then save your CSV.

Step 3: Upload the CSV

Once your CSV is ready, upload it through the Uploader Widget. Filerobot DAM will process each row and import your files with the details you've provided.

How Validation Works

Before any file is imported, every row in your CSV is checked. A row can fail validation for any of these reasons:

• Invalid filename – the filename is empty or contains unsupported characters, such as ', ./, or %

• Invalid file URL – the URL is incorrectly formatted, or the file can't be reached (a HEAD request to the URL returns an HTTP status of 400 or higher)

• Invalid metadata – the metadata values don't match the expected format or type

• Invalid permissions – the uploading account is missing one of the required permissions

Depending on the results:

• If every row fails validation, the entire upload is rejected, and no files are imported.

• If some rows pass and others don't, the valid rows are imported, and the invalid ones are skipped.

What to Do If an Upload Fails or Partially Succeeds

If some or all of your files don't upload successfully, here's how to find out why:

1. Locate the output CSV. This file is generated after the import runs and lists the result for each row.

2. Find the download link in the API response. Open your browser's Developer Tools, go to the Network tab, and look at the upload request. The link to the output file will be included in the response.

3. Open the output CSV to see which rows failed and why, correct those rows, and re-upload if needed.

Bonus Tip :  Faster Way to Build Your CSV

If you'd rather not build your metadata columns from scratch, there's a quicker method that reuses a structure Filerobot DAM already knows about:

1. Upload a few sample files into a folder in the DAM. 

2. Fill in their metadata

3. Select those files and export them as a CSV.

4. This export will already include all the correct metadata column headers and language variants for your account, so you won't need to look up API keys or build column names manually.

5. Remove any metadata columns you don't need, keeping only the ones relevant to your upload.

6. Add the three required columns (file_url, file_name, target_folder) to the front of the sheet.

7. Fill in the metadata values for your actual files.

8. Save the file and upload it through the uploader widget, just like before.

This shortcut skips the manual setup step and gets you to a working CSV faster.

If you have any questions or issues, please feel free to contact our Software Support team and mention the following details:

• Token
• Short description of the issue (including URLs, screenshot, short video if available)
• Steps to reproduce the issue.