JSON Import

Import feedback from a JSON file into UserHero. JSON import supports nested objects and dot-notation field access, making it ideal for structured data exports from APIs or databases.

File Requirements

Format: .json file containing an array of objects
Max size: 50 MB
Encoding: UTF-8

Example JSON

[
  {
    "id": 1,
    "title": "Login page is broken",
    "description": "Cannot log in with SSO",
    "reporter": {
      "email": "user@example.com",
      "name": "Jane Doe"
    },
    "priority": "high",
    "tags": ["bug", "auth"],
    "created_at": "2025-06-01T10:30:00Z"
  },
  {
    "id": 2,
    "title": "Add dark mode",
    "description": "Would love a dark theme option",
    "reporter": {
      "email": "user2@example.com"
    },
    "priority": "low",
    "tags": ["feature"],
    "created_at": "2025-06-15T14:00:00Z"
  }
]

The file must be an array of objects ([{...}, {...}]). A single object ({...}) or other JSON structures are not supported.

Step-by-Step Guide

1. Start the Wizard

Navigate to Dashboard → Import Data and click New Import. Select JSON File as your provider.

2. Upload Your File

Drag and drop your JSON file or click to browse. The system validates that the file contains a valid JSON array and detects the top-level fields from the first 10 records.

3. Map Fields

The wizard displays detected fields on the left. Map each to a UserHero target field:

JSON Field	Map to	Notes
title, subject	message	Feedback message (required)
description, body	message	Concatenated if multiple fields map to message
reporter.email	userEmail	Dot-notation for nested fields
reporter.name	userName	Submitter name
reporter.phone	userPhone	Submitter phone number
assignee.email	assigneeEmail	Assigned agent email
assignee.name	assigneeName	Assigned agent name
company.name	companyName	Customer company name
category, type	category	bug, feature, suggestion, or other
status	status	Text labels matched case-insensitively
priority	rating	Use the priority-to-rating transform
tags	tags	Array or comma-separated string
url, page_url	context.pageUrl	Original page URL
due_date	dueDate	Due date for SLA tracking
updated_at	updatedAt	Last updated timestamp
id, external_id	externalId	Custom unique ID for stable re-imports
created_at	createdAt	Preserves original timestamp

4. Select Project

Choose the target project for the imported feedback.

5. Review & Import

Review your settings and click Start Trial or Start Import.

Nested Field Access

JSON import supports dot-notation to access nested fields. For example, given this structure:

{
  "reporter": {
    "email": "user@example.com",
    "profile": {
      "url": "https://example.com/profile"
    }
  }
}

You can map:

reporter.email → userEmail
reporter.profile.url → context.pageUrl

The field mapping UI shows top-level fields by default. Enter dot-notation paths manually for nested fields.

Date Detection

The import engine automatically looks for common date field names:

created_at
createdAt
date
timestamp
created

If found, dates are parsed and used to filter records within your plan's import window. ISO 8601 format (2025-06-01T10:30:00Z) is recommended for reliable parsing.

Row Identification

By default, each JSON object is assigned an ID based on its array index (json-row-0, json-row-1, etc.). Re-running the same import updates existing records via upsert logic.

To use a stable identifier instead, map a field 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 objects are reordered or the file is modified.

If you don't map an externalId field and modify the JSON array between imports (reorder objects, add/remove entries), the index-based IDs will shift. Use the same file for re-imports, or map an externalId field.

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 — JSON imports cannot migrate file attachments.
50 MB file size limit — For larger files, split the array into multiple files.
Array of objects only — Nested arrays, primitives, or mixed structures are not supported.
Top-level fields only in auto-detect — Nested fields must be referenced via dot-notation in the mapping configuration.

Troubleshooting

Issue	Solution
"JSON file must be an array of objects"	Wrap your data in an array: `[{...}, {...}]`.
"JSON array is empty"	The file contains `[]`. Add at least one record.
"File is not valid JSON"	Check for syntax errors — missing commas, unquoted keys, trailing commas.
Nested fields not showing	Enter the dot-notation path manually (e.g., `reporter.email`).
Missing records	Records outside your plan's retention window are skipped.

JSON Import

On this page