CSV Import
Import feedback from CSV files into UserHero
CSV Import
Import feedback from a CSV (or TSV) file into UserHero. Upload your file, map columns to UserHero fields, and run the import.
File Requirements
- Format:
.csvor.tsvfile - Max size: 50 MB
- Encoding: UTF-8 (default) — other encodings may cause garbled text
- First row: Must be column headers
- Quoting: Fields containing commas or newlines should be wrapped in double quotes
Example CSV
subject,email,category,status,created_date
"Bug: login page broken",user@example.com,bug,Open,2025-06-01
Feature request: dark mode,user2@example.com,feature,New,2025-06-15
"Feedback, general",user3@example.com,other,Closed,2025-07-01Step-by-Step Guide
1. Start the Wizard
Navigate to Dashboard → Import Data and click New Import. Select CSV File as your provider.
2. Upload Your File
Drag and drop your CSV file into the upload area, or click to browse. The system uploads the file to secure storage and validates it:
- Detects the delimiter (comma by default)
- Reads column headers
- Counts the total number of rows
If validation fails, check that the first row contains headers and the file is valid CSV.
3. Map Fields
The wizard shows your CSV columns on the left and UserHero target fields on the right. Map each column:
| Your CSV Column | Map to | Notes |
|---|---|---|
| subject, title, description | message | The feedback message (required) |
| email, user_email | userEmail | Submitter email |
| name, user_name | userName | Submitter name |
| phone, user_phone | userPhone | Submitter phone number |
| assignee_email, agent_email | assigneeEmail | Assigned agent email |
| assignee_name, agent_name | assigneeName | Assigned agent name |
| company, company_name | companyName | Customer company name |
| category, type | category | Must be: bug, feature, suggestion, or other |
| status | status | Text labels are matched case-insensitively |
| priority, rating | rating | Numeric 1–5, or uses the priority transformation |
| tags, labels | tags | Comma-separated within the field |
| url, page_url | context.pageUrl | Original page URL |
| due_date, due_by | dueDate | Due date for SLA tracking |
| updated_at, updated_date | updatedAt | Last updated timestamp |
| id, external_id | externalId | Custom unique ID for stable re-imports |
| date, created_at, created_date | createdAt | Preserves original timestamp |
Set columns you don't need to Ignore.
At least one column must be mapped to message. If you map multiple columns to message, their values are concatenated with a newline.
4. Select Project
Choose the target project for imported feedback.
5. Review & Import
Review your configuration and click Start Trial (10 records) or Start Import (all records).
Date Detection
The import engine automatically detects date columns by looking for column names containing date or created. If a date column is found, records are filtered to your plan's import window. Standard date formats are supported:
2025-06-012025-06-01T12:00:00ZJune 1, 202506/01/2025
Row Identification
By default, each CSV row is assigned an ID based on its row number (csv-row-0, csv-row-1, etc.). If you run the same import again, rows are matched by this ID for upsert logic — existing records are updated, not duplicated.
To use a stable identifier instead, map a column to externalId. This uses your own unique ID (e.g., a ticket number or database ID) for deduplication, so re-imports remain accurate even if rows are reordered or the file is modified.
If you don't map an externalId column and modify the CSV between imports (reorder rows, add or remove rows), the row-based IDs will shift. This may cause duplicate records. Use the same file for re-imports, or map an externalId column.
Customer Records
Imported feedback is automatically linked to Customer records. If a userEmail or userPhone is present, UserHero matches it to an existing customer or creates a new one. Company names are also stored on the customer record when mapped.
Limitations
- No attachment support — CSV imports cannot migrate file attachments. Upload attachments manually after import if needed.
- 50 MB file size limit — For larger files, split them into multiple CSV files and import sequentially.
- Flat structure only — CSV files are inherently flat. For nested data, use JSON import instead.
Troubleshooting
| Issue | Solution |
|---|---|
| "CSV file has no headers" | Ensure the first row contains column names, not data. |
| Garbled characters | Save the file as UTF-8. In Excel: File → Save As → CSV UTF-8. |
| Wrong column split | Check your delimiter. TSV files use tabs — the system auto-detects commas by default. |
| Missing rows | Rows outside your plan's retention window are automatically skipped. |
| 0 records imported | Verify that at least one column is mapped to message. |