Zendesk CSV Import: Fix Ticket and User Upload Errors (2026)

Quick Answer

Zendesk's CSV import supports users and organizations only — tickets cannot be imported via CSV. They require the Zendesk API. The most common user import failures are missing required headers (name, email, restriction are mandatory), phone numbers without country codes, encoding issues from Windows Excel exports, and importing users before their organizations exist.

The fix: Download Zendesk's own CSV template from Admin Center > Data Importer > Import > Download a CSV template. Use that exact structure. Import organizations before users.

Why it happens: Zendesk's Data Importer maps CSV columns to user properties by exact header name match. A column named Phone won't map to the phone property. Required fields that are absent cause the entire import to fail, not just individual rows.

---

What Zendesk's Error Messages Actually Mean

"The file you tried to upload doesn't contain valid headers" — Your CSV is missing required column headers, or the headers don't match Zendesk's expected format. Required headers for user import: name, email, restriction. Download the template to get the exact format.

"There was an error processing your file" — Generic file-level error. Usually encoding (file isn't UTF-8) or structural (extra blank rows, inconsistent column count, file too large).

"Insufficient permissions to edit user" — The agent running the import doesn't have sufficient Zendesk permissions to create or edit users. The importing account needs Administrator role.

"Phone number is not valid" — Phone numbers must include a country code. (555) 234-5678 fails. +15552345678 works.

Import succeeds but user count is lower than expected — Duplicate rows in your CSV (same email twice) cause one to be skipped. Or rows with invalid emails were silently excluded.

Welcome emails sent to every imported user — This is expected behavior, not an error. Zendesk sends verification emails to newly created users by default. Disable this before importing to prevent sending thousands of emails to your user list.

---

Required vs Optional Headers Quick Reference

Save this. It's the single table most Zendesk admins need open during a migration:

Common header mistakes:

• phone (singular) fails — Zendesk requires phones (plural)
• role fails — Zendesk requires restriction
• Extra space in a header (name with trailing space) causes the column to be silently ignored
• Headers are case-sensitive: Email works, EMAIL does not

---

Fast Fix (2 Minutes)

If your Zendesk CSV import just failed:

1. Download the official template — Admin Center → Data Importer → Import → Download a CSV template. Use this exact structure.
2. Check encoding — Save your CSV as UTF-8 from Excel: File → Save As → CSV UTF-8 (Comma delimited).
3. Verify required headers — name, email, and restriction are required for every user row.
4. Import organizations first — If your users belong to organizations, import the organizations CSV before the users CSV.
5. Disable welcome emails — Admin Center → People → Configuration → End users → uncheck "Also send a verification email when a new user is created by an agent or administrator."

If specific rows are failing, continue below.

---

TL;DR: Zendesk's CSV import is limited to users and organizations — no ticket import via CSV. Most failures trace to missing required headers, phone numbers without country codes, or importing users before their organizations. Download Zendesk's own template, validate your CSV with SplitForge Data Validator before uploading, then import organizations first.

---

You're migrating to Zendesk. You have 5,000 tickets in your old help desk system, exported as CSV. You try to import them into Zendesk. There's no CSV import option for tickets in Admin Center. You search the Zendesk docs and find that ticket import requires the Zendesk API.

Then you try to import your users. The import completes but only 3,847 of 5,000 users were created. The missing 1,153 all have one thing in common: their organization was in a separate CSV you planned to import after.

Zendesk's import system has specific requirements and a specific sequence. This guide covers both.

Each error was reproduced using Zendesk's Admin Center Data Importer and legacy Bulk Import tools, March 2026.

---

---

Table of Contents

• Required vs Optional Headers Quick Reference
• The Ticket CSV Import Problem
• Fix 1: Required Headers and Field Names
• Fix 2: Phone Number Format
• Fix 3: Encoding Issues
• Fix 4: Organization Import Order
• Fix 5: Welcome Email Flood Prevention
• Fix 6: Role and Permission Mapping
• Import Limits and File Requirements
• The Privacy Consideration
• Additional Resources
• FAQ

---

This guide is for: Zendesk administrators importing users and organizations in bulk, and teams migrating data from another help desk platform.

---

The Ticket CSV Import Problem

Zendesk does not support CSV import for tickets. This is not an error — it's a deliberate architecture decision.

Tickets in Zendesk have complex relationships: they're linked to requesters (users), assignees (agents), organizations, groups, and custom fields. A flat CSV can't represent these relationships reliably.

The actual import paths for tickets:

If you found this guide because you're trying to import tickets via CSV — stop, and use the API instead. Attempting to work around this limitation with hacks typically results in tickets that are missing metadata, incorrectly dated, or orphaned from users.

Fix 1: Required Headers and Field Names

Zendesk's Data Importer maps CSV columns to user properties by exact header name. Case matters. Spacing matters.

Required headers for user import:

Optional but commonly needed:

What a broken vs correct file looks like:

❌ BROKEN (wrong header names):
Name,Email Address,Role
Alice Johnson,[email protected],Agent
Bob Smith,[email protected],End User

Zendesk error: "The file you tried to upload doesn't contain valid headers"
Cause: "Name" (capital N) and "Email Address" (two words) don't match
       Zendesk's required "name" and "email" headers

FIXED:
name,email,restriction
Alice Johnson,[email protected],agent
Bob Smith,[email protected],end-user

Fix: Download Zendesk's CSV template from Admin Center → Data Importer → Import → Download a CSV template. The template uses the exact header names Zendesk expects. Build your CSV from the template rather than trying to match headers manually.

Fix 2: Phone Number Format

Zendesk requires phone numbers to include a country code. A phone number without a country code is rejected.

Required format: E.164 international format — +[country code][area code][number] with no spaces, dashes, or parentheses.

❌ BROKEN (missing country code):
name,email,phone
Alice Johnson,[email protected],(555) 234-5678
Bob Smith,[email protected],555-234-5678

Zendesk error: "Phone number is not valid"

FIXED:
name,email,phone
Alice Johnson,[email protected],+15552345678
Bob Smith,[email protected],+15552345678

Use SplitForge Data Cleaner to standardize phone numbers to E.164 format across all rows locally before uploading. Your contact list never leaves your browser — important when the file contains Zendesk end-user personal data subject to GDPR or CCPA requirements.

For a complete phone standardization guide, see standardize phone numbers in CSV for CRM import.

Fix 3: Encoding Issues

Zendesk's Data Importer requires UTF-8 encoding. Files exported from Windows Excel are often Windows-1252 (ANSI), which produces garbled characters in names containing accented letters.

❌ BROKEN (Windows-1252 file read as UTF-8):
Émilie → becomes → Émilie in Zendesk
Müller → becomes → Müller

FIXED: Re-export the file as UTF-8 before importing.
In Excel: File → Save As → CSV UTF-8 (Comma delimited) (*.csv)

If you're on a Mac, Excel for Mac exports CSV as UTF-8 by default. The issue is primarily Windows Excel.

For files that can't be re-exported (e.g., received from a third party), run through SplitForge Delimiter & Encoding Fixer to convert encoding locally before uploading to Zendesk.

Zendesk's own troubleshooting documentation recommends uploading your CSV to Google Sheets and downloading it as CSV if you have encoding problems — this works because Google Sheets exports UTF-8 automatically.

Fix 4: Organization Import Order

Zendesk creates user-organization relationships at import time. If you import users before their organizations exist, those users are created without organization assignments. You can't retroactively assign them in bulk via CSV — you'd need to run a second import to update them.

Correct import sequence:

1. Import organizations CSV first
2. Verify organizations were created correctly
3. Import users CSV with organization names

What goes wrong if you reverse the order:

❌ BROKEN (users imported before organizations):
Users CSV includes:
Alice Johnson,[email protected],end-user,Acme Corp

But "Acme Corp" doesn't exist in Zendesk yet.

Result: Alice is created as a user with no organization.
         "Acme Corp" is silently ignored — no error shown.

FIXED: Import organizations CSV first.
Then import users — "Acme Corp" now exists and Alice is assigned to it.

Organization CSV required headers: name (required). Optional: domain_names, external_id, tags, notes.

Fix 5: Welcome Email Flood Prevention

By default, Zendesk sends a verification email to every new user created via bulk import. If you're importing 5,000 users, 5,000 emails go out immediately. This is expected behavior — but it's usually not what you want when importing historical user data.

Disable before importing:

1. Admin Center → People → Configuration → End users
2. In the "User welcome email" section, uncheck "Also send a verification email when a new user is created by an agent or administrator."
3. Run your import.
4. Re-enable after import if needed.

This is not reversible for emails already sent. Disable it before the first import run.

Fix 6: Role and Permission Mapping

The restriction column controls what role a user gets in Zendesk. Values are case-sensitive.

Valid values for restriction:

Enterprise plan agents:

On Enterprise plans, standard agent restrictions are replaced by custom roles. Instead of restriction, use the custom role name exactly as it appears in your Zendesk admin panel. If the role name doesn't match, the user is created as a Light Agent.

Light Agents can be CC'd on tickets and view tickets but cannot be assigned to them. This is a common unintended outcome when role names don't match — agents who should be full agents get created as Light Agents with limited permissions.

---

Import Limits and File Requirements

Practical note on the 128KB row limit: A row that contains very long notes or description fields can hit this limit. If your import fails with no clear error, check whether any individual row contains unusually large text fields. Use =LEN(A2) in Excel to check row content lengths.

File splits for large imports: Zendesk allows only one file import at a time. If your user list exceeds 500,000 rows, split it into multiple files and import them sequentially. Use SplitForge CSV Splitter to divide large files by row count.

The Privacy Consideration

Zendesk user import files contain end-user personal data: names, email addresses, phone numbers, and organization affiliations. Under GDPR Article 28, any tool that processes this data on its servers may become a data processor, requiring a signed DPA before use.

Many CSV cleaning and validation tools upload your file to a remote server to check for errors or format issues. For Zendesk user import files specifically, that upload exposes personal data before you've even verified it's correct.

SplitForge processes CSV files in Web Worker threads in your browser. For raw file contents, nothing is transmitted to any server during validation, encoding conversion, or deduplication. The file stays on your machine until you upload it to Zendesk directly.

For more on processing personal data without cloud exposure, see our privacy-first data processing guide.

Additional Resources

Zendesk Official Documentation:

• Bulk importing user data with the data importer — Official limits, required fields, and template download
• I am trying to import users or organizations and get an error — Official troubleshooting table

Standards:

• RFC 4180: CSV Format Specification — CSV structure standard
• ITU-T E.164 Telephone Numbering — International phone number format (required by Zendesk)
• GDPR Article 28 — Processor obligations — Relevant when using third-party tools to process user data

Related Guides:

• Why CRMs reject CSV imports — Common rejection causes across all platforms
• CSV import errors complete guide — Full error taxonomy

FAQ