File export path syntax

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:

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

Default path pattern:

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):

recording.mp3
photo.jpg
clip.webm

Custom

You define the folder and filename pattern. Use / to create folders. See Variables and Syntax below.

Default custom pattern (same as Structured):

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

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

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 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 (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:

{{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):

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

{{result_index}}/{{question_variable_name}}/{{default_file_name}}

Date and question order

{{result_date}}/Q{{question_order_number}}/{{default_file_name}}

Fallback when variable name is missing

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

By result only

result - {{result_index}}/{{default_file_name}}

By question only

question - {{question_order_number}}/{{default_file_name}}

Month, then result and question

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

Result, then sentiment

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

Result, then file type

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

Flat custom names with result prefix

{{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}}).

CSV/Excel export of response data is separate from file ZIP export.
API file downloads use individual file URLs; see Using Download API.