Import & Export

Bulk import CSV data into forms and export entry views for analysis.

FormWork provides CSV import and export tools for managing entry data in bulk. Import existing data into a form, export a saved view for analysis, and track long-running jobs from the files area.

Exporting Entries

Quick Export

Exports are based on the current saved view. The view controls which entries are included and which columns appear in the CSV.

1. Go to your form’s Entries tab
2. Select or create the view you want to export
3. Click Export
4. Review the CSV preview
5. Start the export job
6. Download the CSV when the job completes

Export Options

CSV Export

CSV exports include:

• Header row with view column labels
• One row per entry
• Values formatted for spreadsheet use
• Form answers, metafields, status, timestamps, or other references included in the view

Example:

Status,Created At,Name,Email
complete,2026-01-15T10:30:00Z,John Smith,[email protected]
draft,2026-01-16T14:10:00Z,Jane Doe,[email protected]

Large Exports

For forms with many entries:

1. Export runs as a background job
2. Progress indicator shows completion
3. The generated CSV appears in the Files tab
4. Download the file when it is ready

Importing Entries

Preparing Import Data

Create a CSV file with a header row that matches your form field IDs.

1. Use field IDs as column headers
2. Match data types (numbers, dates, etc.)
3. Format dates as ISO 8601 (YYYY-MM-DD)
4. Leave optional fields empty if not applicable

The import dialog shows a copyable header row generated from the current form version.

Import Process

1. Go to form Entries tab
2. Click Import
3. Copy the suggested CSV header row if needed
4. Upload your CSV file
5. Start the import job
6. Review success and failure counts when it finishes

Creating or Updating Entries

Imports create new entries by default. To update an existing entry, include an id column containing the FormWork entry ID.

id,name,email,status
ent_001,John Smith,[email protected],approved
,Jane Doe,[email protected],new

Rows with a matching id update that entry. Rows with a blank or missing id create new entries.

Import Validation

The import job parses each CSV row, writes recognised field values, and recalculates the entry state after each row.

Rows can fail when:

• The row has a different number of columns than the header row
• An existing id belongs to another account or form
• The row cannot be written to the entry
• The CSV file cannot be read

Handling Errors

After import attempt:

1. View success and error counts
2. Download error report
3. Review specific issues
4. Fix and re-import failed rows

Common issues:

• Rows with a different number of columns than the header row
• Unknown or mistyped field IDs in the header row
• Existing entry IDs from a different form
• Values that import successfully but leave validation errors on the resulting entry

Import Templates

Header Template

The import dialog shows a header row containing the field IDs from the current form version. Copy it into the first row of your CSV.

name,email,phone,category,created_at
John Example,[email protected],555-1234,sales,2024-01-15

API Import/Export

Most users should use the import and export buttons in the admin interface. Use the API when another system needs to start a bulk import or export.

Exports and imports run as background jobs. The API returns a job_id, which can be checked through the jobs API.

Start an Export Job

Exports are created from a saved view. Create or select the view first, then start the export.

POST /api/v1/exports
Authorization: Bearer fwk_your_api_key
X-Account-ID: your_account_id
Content-Type: application/json

{
  "view_id": "view_id_to_export",
  "format": "csv"
}

The response includes:

{
  "job_id": "export_job_id"
}

List Export Files

Use the export list endpoint to find generated export files. You can optionally filter by form.

GET /api/v1/exports?form_id=your_form_id
Authorization: Bearer fwk_your_api_key
X-Account-ID: your_account_id

Start an Import Job

Imports are created from an uploaded CSV file. Upload the CSV first, then use the returned file_id to start the import.

POST /api/v1/imports
Authorization: Bearer fwk_your_api_key
X-Account-ID: your_account_id
Content-Type: application/json

{
  "form_id": "form_id_to_import_into",
  "file_id": "uploaded_file_id"
}

The response includes:

{
  "job_id": "import_job_id"
}

Best Practices

Before Importing

• Test with a small sample first
• Validate data in spreadsheet before upload
• Export the target view first if you plan to update existing entries
• Check that column headers match field IDs

Data Preparation

• Clean data before import
• Standardize formats (dates, phone numbers)
• Remove duplicate rows
• Check for empty required fields
• Include an id column only when you intentionally want to update existing entries

Large Imports

For imports over 1,000 rows:

• Split into smaller batches
• Import during off-peak hours
• Monitor for errors
• Consider using the API for automation

Regular Exports

For backups and analysis:

• Schedule regular exports
• Store exports securely
• Use consistent naming conventions
• Document what each export contains