---
updatedAt: 2026-06-03T20:52:05.000Z
agentTools:
  projectIndex: https://docs.voiceform.com/llms.txt
---

# File export path syntax

When you download files from Voiceform as a ZIP archive, you can choose how paths inside the archive are built. This guide explains the three layout options and how to write **custom path patterns** using Mustache-style variables.

This applies to:

* **Download all files** on a form (all recorded audio and file-upload answers)
* **Download all audio** on a question or a single result (submission)

***

## Layout options

### Structured (default)

Files are grouped by result, then by question:

```text
result - 1/question - 2/recording.mp3
result - 1/question - 3/photo.jpg
result - 2/question - 2/clip.webm
```

Default path pattern:

```text
result - {{result_index}}/question - {{question_order_number}}/{{default_file_name}}
```

### Simplified

All files sit in the root of the ZIP using each file’s CDN filename (no folders):

```text
recording.mp3
photo.jpg
clip.webm
```

### Custom

You define the folder and filename pattern. Use `/` to create folders. See [Variables](#variables) and [Syntax](#syntax) below.

**Default custom pattern** (same as Structured):

```text
result - {{result_index}}/question - {{question_order_number}}/{{default_file_name}}
```

**Example with pipe fallback** (use question variable name when set, otherwise `question-N`):

```text
result - {{result_index}}/{{question_variable_name|question-{{question_order_number}}}}/{{default_file_name}}
```

***

## Syntax

Custom paths use **double curly braces** for variables.

### Object-style fields (recommended)

Reference fields on the answer, question, or result (same names as the API `Result` resource):

| Prefix             | Example                      | Description                                          |
| ------------------ | ---------------------------- | ---------------------------------------------------- |
| `answer.`          | `{{answer.sentiment}}`       | Fields on the current answer / file                  |
| `question.`        | `{{question.variable_name}}` | Fields on the question                               |
| `result.`          | `{{result.created_at}}`      | Fields on the result (API v1 Results resource)       |
| `result.metadata.` | `{{result.metadata.lang}}`   | Keys from API `metadata` object (scalar values only) |
| `submission.`      | `{{submission.index}}`       | Alias for `result.*` (legacy)                        |

| Syntax                            | Meaning                                             |
| --------------------------------- | --------------------------------------------------- |
| `{{entity.field}}`                | Insert that field’s value                           |
| `{{entity.field\|fallback text}}` | Use fallback when the field is empty (pipe default) |
| `/`                               | Folder separator                                    |

### Shortcuts (legacy flat names)

Older patterns such as `{{result_index}}`, `{{submission_index}}`, `{{default_file_name}}`, and `{{sentiment}}` still work and map to the dotted fields above. `{{default_file_hash}}` is a deprecated alias for `{{default_file_name}}`.

### Rules

* Always use **`{{name}}`**, not `{name}`.
* Only listed [variables](#variables) are allowed.
* Path segments are sanitized for safe file names (invalid characters removed or replaced).
* Custom paths are limited to **500 characters**.
* You can nest variables inside a pipe fallback, e.g. `{{question_variable_name\|question-{{question_order_number}}}}`.

Pipe defaults are rendered with the same Mustache engine used elsewhere in Voiceform.

### Invalid syntax

These are rejected or highlighted as errors in the editor:

* Unknown variables, e.g. `{{foo}}`
* Single braces, e.g. `{result_index}`
* Unclosed `{{` without `}}`
* Mustache section tags (`{{#}}`, `{{^}}`) in paths

***

## Variables

Only listed fields are allowed (not arbitrary JSON or internal columns).

### Answer (`answer.*`)

Aligned with API v1 `AnswerResource`.

| Field             | Description                                              |
| ----------------- | -------------------------------------------------------- |
| `id`              | Answer UUID                                              |
| `created_at`      | ISO 8601 `created_at`                                    |
| `sentiment`       | `positive`, `negative`, `neutral`, or empty              |
| `sentiment_score` | Numeric score                                            |
| `date`            | `YYYY-MM-DD`                                             |
| `timestamp`       | Unix timestamp                                           |
| `filename`        | CDN file basename (same as `default_file_name` shortcut) |
| `file_extension`  | Extension without dot (`mp3`, `png`, …)                  |
| `loop_index`      | Loop index                                               |
| `loop_item`       | Loop item label                                          |
| `status`          | Processing status                                        |

### Question (`question.*`)

| Field           | Description               |
| --------------- | ------------------------- |
| `id`            | Question UUID             |
| `variable_name` | Variable name if set      |
| `text`          | Question text (sanitized) |
| `order`         | Order in the survey       |
| `type`          | Question type             |
| `hash`          | Question hash             |
| `description`   | Question description      |

### Result (`result.*`)

Aligned with [API v1 Results](https://docs.voiceform.com/reference) (`ResultsResource`). Respondent PII lives in `information_data` on the API, not as top-level path fields.

| Field        | Description                                                                                                                              |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `id`         | Result UUID                                                                                                                              |
| `hash`       | Result hash                                                                                                                              |
| `index`      | 1-based result number in this export                                                                                                     |
| `created_at` | ISO 8601 `created_at`                                                                                                                    |
| `updated_at` | ISO 8601 `updated_at`                                                                                                                    |
| `started_at` | ISO 8601 `started_at`                                                                                                                    |
| `ended_at`   | ISO 8601 `ended_at`                                                                                                                      |
| `date`       | `YYYY-MM-DD` (from `created_at`)                                                                                                         |
| `timestamp`  | Unix timestamp (from `created_at`)                                                                                                       |
| `month`      | `YYYY-MM` (from `created_at`)                                                                                                            |
| `sentiment`  | Average sentiment across answers                                                                                                         |
| `custom_id`  | Custom respondent ID your integration passes (`?response_id=` on the form URL or `metadata.response_id` on submit); stored on the result |

### Custom respondent ID

Many integrations pass a stable per-respondent identifier:

* Form URL: `?response_id=panel-user-123`
* API submit: `metadata.response_id` (copied to the result’s `custom_id` column)

In export paths you can use any of:

| Syntax                            | Example                                                      |
| --------------------------------- | ------------------------------------------------------------ |
| `{{result.custom_id}}`            | Recommended                                                  |
| `{{result.metadata.response_id}}` | Same value when set via metadata                             |
| `{{custom_respondent_id}}`        | Shortcut                                                     |
| `{{response_id}}`                 | Shortcut (not the result UUID; see `{{result_id}}` for that) |

### Result metadata (`result.metadata.*`)

Use keys from the API v1 result `metadata` JSON (same object returned by `GET /results`). Only **scalar** values (string, number, boolean) are supported in paths — nested objects and arrays are skipped.

In the export dialog, after `{{result.` choose **Metadata fields** (or type `metadata`) to see `result.metadata.<key>` suggestions from your responses.

Examples:

```text
{{result.metadata.lang}}/{{default_file_name}}
{{result.metadata.response_id}}/question - {{question_order_number}}/{{default_file_name}}
```

`submission.metadata.<key>` is an alias for `result.metadata.<key>`.

The export dialog suggests metadata keys found on your current responses (preview panel). You can still type any valid key name (`[a-z][a-z0-9_]*`) even if it has not appeared in the sample yet.

### Legacy names (still accepted)

Flat shortcuts and `submission.*` dotted names still work:

| Legacy                                     | Maps to                       |
| ------------------------------------------ | ----------------------------- |
| `result_id`, `submission_id`               | `result.id`                   |
| `result_index`, `submission_index`         | `result.index`                |
| `result_date`, `submission_date`           | `result.date`                 |
| `result_timestamp`, `submission_timestamp` | `result.timestamp`            |
| `submission_month`                         | `result.month`                |
| `submission.*`                             | `result.*` (same field names) |

Folder labels `submission -` and `response -` in saved paths are normalized to `result -`.

***

## Duplicate file names

If two files would end up with the same path inside the ZIP, Voiceform adds a copy suffix (macOS style):

```text
audio.mp3
audio (1).mp3
audio (2).mp3
```

***

## Large exports and email delivery

| Export scope                      | Behavior                                                                                                            |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Full form** (all files)         | Always prepared in the background. You receive an email with a download link when the ZIP is ready.                 |
| **Question** or **single result** | Download starts immediately if there are **25 or fewer** files. Above that, the export is queued and sent by email. |

Very large queued exports may be split into **multiple ZIP files** (default: up to 5,000 files per archive). The email lists one download button per part.

Download links in email are available for **7 days** (configurable on the server).

***

## Premade examples (Custom layout)

In the export dialog, click an example chip to apply a pattern:

| Example                       | Pattern                                                                                                     |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Result & question**         | `result - {{result_index}}/question - {{question_order_number}}/{{default_file_name}}`                      |
| **By result**                 | `result - {{result_index}}/{{default_file_name}}`                                                           |
| **By question**               | `question - {{question_order_number}}/{{default_file_name}}`                                                |
| **Result & question (names)** | `{{result_index}}/{{question_variable_name\|question-{{question_order_number}}}}/{{default_file_name}}`     |
| **Month → result → question** | `{{submission_month}}/result - {{result_index}}/question - {{question_order_number}}/{{default_file_name}}` |
| **Result → sentiment**        | `result - {{result_index}}/{{sentiment\|unknown}}/{{default_file_name}}`                                    |
| **Result → file type**        | `result - {{result_index}}/{{file_extension\|other}}/{{default_file_name}}`                                 |

***

## Examples

### Per result and question variable

```text
{{result_index}}/{{question_variable_name}}/{{default_file_name}}
```

### Date and question order

```text
{{result_date}}/Q{{question_order_number}}/{{default_file_name}}
```

### Fallback when variable name is missing

```text
result-{{result_index}}/{{question_variable_name|Q{{question_order_number}}}}/{{default_file_name}}
```

### By result only

```text
result - {{result_index}}/{{default_file_name}}
```

### By question only

```text
question - {{question_order_number}}/{{default_file_name}}
```

### Month, then result and question

```text
{{submission_month}}/result - {{result_index}}/question - {{question_order_number}}/{{default_file_name}}
```

### Result, then sentiment

```text
result - {{result_index}}/{{sentiment|unknown}}/{{default_file_name}}
```

### Result, then file type

```text
result - {{result_index}}/{{file_extension|other}}/{{default_file_name}}
```

### Flat custom names with result prefix

```text
{{result_index}}-{{default_file_name}}
```

***

## Preview

In the export dialog, **Example output** shows real paths from your **most recent files first** (up to 8 sample paths; total file count includes everything). The custom path field highlights valid variables in blue and invalid syntax in red. Type `{{` to pick **answer**, **question**, or **result**, then continue typing to autocomplete fields (e.g. `{{result.created_at}}` or `{{result.metadata.lang}}`).

***

## Related

* CSV/Excel export of response data is separate from file ZIP export.
* API file downloads use individual file URLs; see [Using Download API](https://docs.voiceform.com/reference/using-download-api).