Freshdesk Migration
Import tickets from Freshdesk into UserHero step by step
Freshdesk Migration
Import your Freshdesk support tickets into UserHero as feedback items. The migration connects to the Freshdesk API, fetches tickets within your plan's retention window, maps fields to UserHero's data model, and optionally migrates file attachments.
Prerequisites
- A Freshdesk account with API access enabled
- Your Freshdesk API key
- Your Freshdesk subdomain (the
yourcompanypart ofyourcompany.freshdesk.com)
Finding Your API Key
- Log in to Freshdesk
- Click your profile picture in the top-right corner
- Select Profile Settings
- Your API key is displayed on the right side of the page under Your API Key
Your API key has the same permissions as your Freshdesk account. Do not share it. UserHero encrypts it with AES-256-GCM and only uses it during the migration process.
Step-by-Step Guide
1. Start the Wizard
Navigate to Dashboard → Import Data and click New Import. Select Freshdesk as your provider.
2. Enter Credentials
- Subdomain: Enter your Freshdesk subdomain (e.g.,
mycompany). Do not include.freshdesk.com. - API Key: Paste your API key.
Click Validate to test the connection. The system will connect to the Freshdesk API and report the number of tickets available within your import window.
3. Map Fields
The wizard auto-detects Freshdesk ticket fields and suggests default mappings:
| Freshdesk Field | Default Target | Notes |
|---|---|---|
subject | message | Ticket subject becomes the feedback message |
description | message | Appended to the message if both are mapped |
type | category | Mapped to bug, feature, suggestion, or other |
status | status | Freshdesk status codes are transformed (see below) |
priority | rating | Freshdesk priority codes are transformed to 1–5 rating |
tags | tags | Comma-separated tag list |
requester.email | userEmail | Original submitter email |
requester.name | userName | Original submitter name |
requester.phone | userPhone | Submitter phone number |
agent.email | assigneeEmail | Assigned agent email (resolved to workspace member) |
agent.name | assigneeName | Assigned agent name |
company.name | companyName | Customer company name |
due_by | dueDate | Ticket SLA due date |
updated_at | updatedAt | Last updated timestamp |
created_at | createdAt | Preserves the original ticket creation date |
You can change any mapping by selecting a different target field from the dropdown, or set it to Ignore to skip the field.
Status Mapping
Freshdesk uses numeric status codes. These are automatically transformed:
| Freshdesk Code | Freshdesk Label | UserHero Status |
|---|---|---|
| 2 | Open | new |
| 3 | Pending | in-progress |
| 4 | Resolved | resolved |
| 5 | Closed | archived |
Custom Freshdesk statuses are matched by label (case-insensitive). Unknown statuses default to new.
Priority to Rating
Freshdesk priorities are converted to a 1–5 star rating:
| Freshdesk Code | Freshdesk Label | UserHero Rating |
|---|---|---|
| 1 | Low | 2 |
| 2 | Medium | 3 |
| 3 | High | 4 |
| 4 | Urgent | 5 |
4. Select Project
Choose which UserHero project should receive the imported feedback.
5. Review & Import
The review screen shows:
- Provider and connection details
- Number of field mappings configured
- Target project
- Whether this is a trial run or full import
Click Start Trial to import only the first 10 records, or Start Import for a full migration.
Monitoring Progress
After starting the import, you're taken to the job detail page where you can monitor:
- Records processed — Total, created, updated, skipped, and failed counts
- Attachments — Download and upload progress
- Conversations — Number of replies and notes imported (Starter plans and above)
- Customers — Number of customer records created and updated
- Errors — Expandable error log with details per record
You can cancel a running import at any time. Partially imported records are preserved.
Conversations & Notes
On Starter plans and above, the import fetches ticket conversations from Freshdesk. Customer replies are stored as comments on the feedback item, and agent notes are stored as internal notes. This preserves the full conversation history from each ticket.
Customer Records
During import, UserHero automatically creates or updates Customer records based on the requester information. Customers are matched by email address or phone number — if a matching customer already exists, their record is updated. Otherwise, a new customer is created.
Company names from Freshdesk tickets are also stored on the customer record.
Assignee Resolution
When a Freshdesk ticket has an assigned agent, the import matches the agent's email address to your workspace members. If a match is found, the feedback item is automatically assigned to that team member. Unmatched agent names are preserved for reference.
SLA & Due Dates
The due_by field from Freshdesk tickets is preserved as the due date on each feedback item. UserHero automatically computes whether the SLA was breached based on the due date and current resolution status, giving you historical SLA performance data in your dashboard.
After Import
Imported feedback appears in your project's inbox with:
- The original creation date preserved
- A
migrationsource tag for easy filtering - External reference linking back to the Freshdesk ticket ID
Troubleshooting
| Issue | Solution |
|---|---|
| "Invalid API key" | Verify the API key in your Freshdesk profile settings. Ensure it hasn't been regenerated. |
| "Connection failed" | Check that the subdomain is correct and your Freshdesk account has API access enabled. |
| 0 tickets found | Your plan's import window may be too narrow. Check the date range shown in the wizard. |
| Slow import | Large ticket volumes (10,000+) take time. The import processes 100 tickets per page with rate limit handling. |
| Attachment errors | Some attachments may have been deleted in Freshdesk. These are logged as errors but don't block the import. |