Freshsales CSV Import: Fix Contact and Deal Upload Errors

Freshsales CSV Import — Quick Reference:

• Owner field: must use the user's email address registered in Freshsales — not display name
• Deal stage: must match an exact pipeline stage name as defined in CRM settings
• Phone numbers: Freshsales applies format validation — international numbers need country code
• Duplicates: Freshsales deduplicates contacts on email by default; deals on deal name + account
• Custom module fields: column header must match field label exactly (case-sensitive in some versions)
• Error report: after import, click "View Report" to download the failure details CSV

---

Quick Answer

Freshsales CSV imports fail for four common reasons: the owner email doesn't match an active user, deal stage names don't match pipeline configuration exactly, phone numbers use formats Freshsales rejects, and custom module column headers don't match field labels.

Why it matters: Freshsales is popular with SMB sales teams who import frequently from spreadsheets, trade shows, and other CRMs. Unlike enterprise CRM imports where one person owns the process, Freshsales imports often run by team leads who don't know the CRM configuration details — owner mismatches and deal stage typos are constant.

The fix: Export active users from Admin → Users before building import files. Export your pipeline stages from Admin → Deal Stages. Pre-validate phone number formats for international numbers.

What actually happens when this goes wrong:

CONSEQUENCE LADDER:

Wrong owner assignment:
→ Lead not contacted in first 24 hours
→ Response rate drops 10x after first hour (Harvard Business Review, lead response data)
→ Pipeline stage stalls at "New Lead"
→ Sales manager runs pipeline review, sees unworked leads
→ Finger-pointing between ops (bad import) and sales (didn't check queue)
→ Deal delayed or lost

Wrong deal stage:
→ Pipeline report shows wrong distribution
→ Forecast models built on bad stage data
→ Management makes resource decisions on inaccurate pipeline
→ Quarter-end scramble when actuals don't match forecast

Configuration drift ignored:
→ Same import fails every month
→ Ops team spends 2–3 hours per import debugging avoidable errors
→ Trust in CRM data quality erodes across the team

Root cause: Freshsales validates against its live configuration — if a user account is deactivated or a deal stage was renamed after your import template was built, imports fail silently.

---

What Freshsales Error Messages Actually Mean

"Owner not found" or "Invalid owner" — The owner column contains an email address not found as an active Freshsales user. Common when importing records assigned to former employees or when using display names instead of email addresses.

"Invalid value for [deal stage field]" — The deal stage name in your CSV doesn't match any active pipeline stage in your Freshsales configuration. Pipeline stage names are exact-match and case-sensitive.

"Invalid phone number" — Phone number format doesn't pass Freshsales validation. Usually caused by missing country code on international numbers, or non-numeric characters.

"Duplicate record" — A contact with the same email (or deal with the same name under the same account) already exists. Behavior depends on your duplicate handling setting: merge, skip, or create as new.

Import completed but records missing fields — A soft failure: the record was created but field values were silently dropped. Download the error report to see which fields failed per row.

---

Fast Fix (90 Seconds)

⏱ Expected time by error type:

• Owner email fix: 10–15 minutes (export user list from Admin → Users)
• Deal stage fix: 5–10 minutes (export stages from Admin → Deal Stages)
• Phone format fix: 10–15 minutes (standardize to E.164 format)
• Custom field header fix: 5–10 minutes (check field labels in CRM settings)

🚑 Fast triage — what broke?

Owner not found         → Fix 1 (owner email)
Invalid deal stage      → Fix 2 (pipeline stages)
Invalid phone number    → Fix 3 (phone format)
Custom field blank      → Fix 5 (field label mismatch)
Mixed errors / unknown  → download error report → sort by error type → apply fix per category

If your Freshsales import just failed:

1. Go to Contacts (or Deals) → Import → View Report — download the error report for per-row failures
2. Sort the error report by error type — group identical failures to fix as a batch
3. For owner errors: Admin → Users → copy active user emails
4. For deal stage errors: Admin → Deal Stages → copy exact stage names
5. Validate locally before re-importing — run your corrected file through Data Validator without sending your contact data to another server

---

TL;DR: Freshsales import errors are concentrated in three areas: owner not found, deal stage mismatch, and phone format. All are fixable in the source CSV once you have the correct reference values from CRM settings. Use Data Validator — your sales data never leaves your browser.

---

Your Freshsales import ran. 2,400 contacts created. 380 failed. The error report says "Owner not found" on half the failures and "Invalid value for Deal Stage" on the other half.

The owner column uses full names. Freshsales expects emails. The deal stage column says "Qualified Lead." Freshsales calls it "Qualified."

Neither error is in the help docs for anyone to easily find. This guide maps every Freshsales import failure to its fix. All error behavior verified against Freshsales (Freshworks CRM) documentation and community guides, March 2026.

---

Table of Contents

• Fix 1: Owner Email Not Found
• Fix 2: Deal Stage Value Mismatches
• Fix 3: Phone Number Format Rejection
• Fix 4: Duplicate Record Handling
• Fix 5: Custom Module Field Mapping
• Freshsales Import Cause/Fix Table
• Additional Resources
• FAQ

---

Fix 1: Owner Email Not Found

Freshsales owner assignment requires the email address of an active Freshsales user. Display names, role-based emails, and former employee accounts all cause this failure.

❌ BROKEN — owner assignment failures in Freshsales:

Owner column values → Freshsales behavior:

"John Smith"                  → ❌ display name not accepted
"[email protected]"      → ✅ if John Smith is active in Freshsales
"[email protected]"          → ❌ email variant — must match Freshsales account exactly
"[email protected]"        → ❌ former employee, account deactivated
"[email protected]"           → ❌ role-based email, not a user account
[blank]                       → record imports unassigned (goes to importing user or unassigned pool)

HOW TO GET ACTIVE USER EMAILS:
Admin → Users → copy emails from the active user list
These are the exact strings to use in your owner column.

VLOOKUP to map source names to Freshsales emails:
=VLOOKUP(A2, freshsales_users_table, 2, FALSE)
Where A2 = salesperson name from your source CRM
And freshsales_users_table = exported user email/name mapping

❌ BROKEN — owner column using display name (most common Freshsales owner error):

CSV row:
First Name,Last Name,Email,Owner,Deal Stage
Alice,Chen,[email protected],John Smith,Qualified

Freshsales error report:
Row 2: Owner not found — "John Smith" is not a valid user.

Root cause: Freshsales expects owner as email address, not display name.
"John Smith" is how the rep's name appears in the UI — but the field
requires their login email.

FIXED:
First Name,Last Name,Email,Owner,Deal Stage
Alice,Chen,[email protected],[email protected],Qualified

How to find the correct owner email:
Admin → Users → Active Users → copy the Email column value exactly.

---

Fix 2: Deal Stage Value Mismatches

Deal stages in Freshsales are tied to a specific pipeline. The stage name in your CSV must match the pipeline stage name exactly as configured in your Freshsales instance.

❌ BROKEN — deal stage value mismatches:

Your CSV value         → Freshsales behavior

"Qualified Lead"       → ❌ if your stage is named "Qualified" (not "Qualified Lead")
"Proposal"             → ✅ if "Proposal" is an exact stage name in your pipeline
"proposal"             → ❌ case mismatch (if stage is "Proposal" with capital P)
"Won"                  → ❌ "Won" is a deal outcome, not a stage — use the pipeline stage name
"Closed Won"           → ❌ same issue — deal closure is separate from stage
"Demo Scheduled"       → ✅ if your pipeline has a stage called exactly this

FETCH EXACT STAGE NAMES:
Admin → Pipelines → click your pipeline → view stage names
Copy each stage name exactly. Don't type from memory.

MULTI-PIPELINE NOTE:
If your Freshsales has multiple pipelines (e.g., "Sales Pipeline" and "Enterprise Pipeline"),
each pipeline has its own stage names. If your CSV includes deals for both pipelines,
include a "Pipeline" column in your file to specify which pipeline each deal belongs to.

---

Fix 3: Phone Number Format Rejection

Freshsales applies phone format validation. Numbers that don't conform to expected format produce an "Invalid phone number" error or import with a blank phone field.

FRESHSALES PHONE FORMAT RULES:

US/Canada numbers:
Accepted: +15551234567 (E.164), (555) 123-4567, 555-123-4567, 5551234567
Best practice: +1XXXXXXXXXX (E.164 format — internationally unambiguous)

International numbers:
Required: country code prefix
+44 7911 123456 → ✅ UK mobile (with country code)
07911 123456    → ❌ UK mobile without country code — Freshsales can't determine country
+49 30 12345678 → ✅ German landline
030 12345678    → ❌ German number without country code

Common format errors:
"555-123-4567 ext. 123" → ❌ extensions cause format rejection
"(555) 123-4567"        → ✅ US format with parentheses (usually accepted)
"555.123.4567"          → depends on instance config — use E.164 to be safe
"+1 (555) 123-4567"     → ✅ full E.164 with spaces (usually accepted)
"1234567890123456"      → ❌ too many digits — phone field length limit

SAFEST FORMAT FOR ALL IMPORTS:
E.164: +[country code][number] with no spaces, dashes, or parentheses
Example: +15551234567 (US), +447911123456 (UK), +4930123456 (Germany)

To standardize to E.164 in Excel:
="+" & [country_code] & SUBSTITUTE(SUBSTITUTE(SUBSTITUTE(A2,"-",""),"(",""),")","")

---

❌ BROKEN — phone number without country code (most common Freshsales phone error):

CSV row:
First Name,Last Name,Email,Phone,Owner
Alice,Chen,[email protected],555-123-4567,[email protected]

Freshsales import result:
Contact created ✅ — Alice Chen imported
Phone field: [blank]
Why: "555-123-4567" has no country code prefix — Freshsales cannot determine
     country, fails phone validation, drops the field silently

FIXED — E.164 format with country code:
First Name,Last Name,Email,Phone,Owner
Alice,Chen,[email protected],+15551234567,[email protected]

Result:
Contact created ✅
Phone field: +15551234567 ✅

For international numbers:
UK:      +44 7911 123456 → +447911123456
Germany: +49 30 12345678 → +4930123456
Australia: +61 2 1234 5678 → +61212345678

Excel formula to add US country code to existing numbers:
="+1" & SUBSTITUTE(SUBSTITUTE(SUBSTITUTE(A2,"(",""),")",""),"-","")

Fix 4: Duplicate Record Handling

Freshsales deduplicates contacts on email address by default. For deals, deduplication is typically based on deal name within the same account.

FRESHSALES DUPLICATE BEHAVIOR (Contacts):

Default: dedup on email
→ Existing contact with same email = updated (not duplicated)
→ Import summary shows "Updated" for these records

If dedup is disabled:
→ Duplicate contacts created with the same email
→ Merge manually after import: select duplicates → Merge

FRESHSALES DUPLICATE BEHAVIOR (Deals):
→ Deal deduplication is less strict than contacts
→ Same deal name + same account = flagged as potential duplicate
→ Behavior depends on your configuration: may create or may skip

PRE-IMPORT DEDUPLICATION RECOMMENDATION:
Run your import file through deduplication before uploading.
Removing duplicates before import is faster than merging in Freshsales after.

---

Fix 5: Custom Module Field Mapping

Freshsales custom modules (custom record types beyond standard Contacts, Accounts, Deals) have their own field sets. CSV column headers for custom module imports must match the field label exactly.

CUSTOM MODULE FIELD MAPPING:

Field label in Freshsales UI   → Correct CSV column header

"Budget Range"                  → "Budget Range" (exact match, including spaces)
"budget range"                  → ❌ case mismatch (check your Freshsales version)
"Renewal Date"                  → "Renewal Date"
"renewal_date"                  → ❌ underscore format not matching display label

DATE FIELDS IN CUSTOM MODULES:
Freshsales date format for import: MM/DD/YYYY
"2026-03-19" → ❌ ISO format rejected
"03/19/2026" → ✅ MM/DD/YYYY accepted

NUMBER FIELDS:
No currency symbols. No thousand-separator commas.
"$45,000" → ❌  |  "45000" → ✅

HOW TO CHECK FIELD LABELS:
Admin → Custom Modules → select your module → Fields
Column headers in your CSV must match the display labels shown here exactly.

---

⚠️ Hidden Cause: Configuration Drift

If your import worked last month and fails today without any changes to your file, the problem is almost certainly configuration drift — not your CSV.

Freshsales configurations change constantly:

• User accounts change: sales reps leave, new ones join. Owner emails that worked in January don't exist after a team restructure in March.
• Deal stages renamed: a pipeline stage called "Qualified Lead" gets renamed to "Qualified" in a CRM cleanup. Every import that references the old name fails silently.
• Custom fields modified: a field gets deleted or its label changes. The column in your CSV no longer maps to anything.

CONFIGURATION DRIFT PROTECTION:

Before every import (not just the first one):
1. Export active user list → Admin → Users → confirm emails still match
2. Export pipeline stages → Admin → Pipelines → confirm stage names haven't changed
3. Export custom field labels → Admin → Custom Fields → confirm column headers still match

Time investment: 5 minutes
Import failures prevented: most of them

This is the expert-level insight most import guides skip. Treat your CRM configuration as live data that changes between imports — not a static reference you set once.

🚨 Import Success ≠ Correct Data in Freshsales

Freshsales reports "Import completed" even when field values are silently dropped. This is the most dangerous failure pattern for SMB teams — everything looks fine until you open a record.

SOFT FAILURE PATTERNS IN FRESHSALES:

Scenario A — Phone field drops:
Import shows: 500 contacts created ✅
Reality: 500 contacts with blank phone fields
Why: phone format failed validation silently
How to detect: open 5 contacts → check phone field

Scenario B — Custom field drops:
Import shows: 1,200 deals created ✅
Reality: 1,200 deals with blank Budget Range field
Why: column header didn't match field label exactly
How to detect: run a Freshsales report filtered to "Budget Range is empty"

Scenario C — Owner assignment fails silently:
Import shows: 800 leads assigned ✅
Reality: 800 leads assigned to the importing user, not the intended owner
Why: owner column used display names instead of emails
How to detect: check Owner field on 5 records → all show your name, not theirs

RULE: After every Freshsales import, manually verify 5 records.
"Completed" is not the same as "correct."

Freshsales Import Cause/Fix Table

---

✅ How to Confirm Your Freshsales Import Worked

1. Download the error report — after import, click "View Report" to access the error details CSV. Zero rows = clean import.
2. Open 5 imported records — verify: owner shows correct user (not blank), deal stage shows correct stage name, phone number is formatted correctly.
3. Check record count — the import summary shows created, updated, and skipped counts. Skipped = failures.
4. Run a test automation — if you have workflows that trigger on contact creation (assignment rules, welcome sequences), verify they fired for 2–3 of the new contacts.

🔁 Safe Re-Run Workflow

1. Download the error report from your failed import — it contains all failed rows
2. Fix the specific values (owner email, deal stage, phone format) in those rows
3. Re-import the corrected error rows only — Freshsales deduplicates on email for contacts, so re-importing just the failed rows is safe
4. For deal re-imports: verify deal name + account doesn't already exist to avoid duplicates

⚠️ Edge Case: If your Freshsales instance uses multiple currencies and your import file contains amounts in a non-base currency, include a currency code column in your deal import. Without it, Freshsales assigns the base currency to all imported deal amounts, which creates incorrect deal values for international opportunities.

🛡 Prevent This Next Time

1. Export your reference data before every import — active user emails, pipeline stage names, and custom field labels all change over time. Pull a fresh export from Admin settings before building each import template.
2. Standardize all phone numbers to E.164 at the source — build E.164 formatting into your lead capture forms and CRM exports so phone numbers arrive pre-formatted for import.
3. Test 5 rows per entity type — contacts, deals, and accounts each have different validation rules. Test a small batch of each entity type before running the full file.

---

⏱ Recovery Cost If You Don't Fix This Before Import

The validation step this guide describes takes under 10 minutes. The recovery work after a bad import routinely takes half a day. The math is straightforward.

🧠 Cross-CRM Pattern: The owner email requirement, exact picklist match, and configuration drift problem aren't unique to Freshsales. Every major CRM — Salesforce, HubSpot, Dynamics 365, Zoho — validates owner assignment against active user emails, validates dropdown fields against closed option lists, and goes stale when your team or pipeline configuration changes. Build the habit of exporting fresh reference data before every import across all your CRM tools, not just Freshsales.

Why Validate Freshsales Import Files Locally

Freshsales import files — especially deal imports — combine prospect contact information with internal pipeline data: deal values, close dates, owner assignments, and sales stage. This data represents both personal information subject to GDPR and confidential business data. Many teams run these files through cloud-based tools before import, creating an exposure point with its own data retention policy.

SplitForge validates files in Web Worker threads in your browser — for raw file contents, nothing is transmitted to any server during processing. Both the contact PII and the pipeline data stay on your machine throughout validation.

For cross-platform CRM error decoding, see CRM import error codes explained. For general CRM import preparation, see why your CRM rejects CSV imports. For the complete guide, see CRM import failures complete guide.

---

Additional Resources

Tested: Freshsales error messages and field behavior verified against Freshworks CRM documentation and Freshdesk community guides. Phone format behavior confirmed in Freshsales import documentation. March 2026.

Official Freshworks Documentation:

• Freshsales: Import contacts, accounts, deals — Official import guide
• Freshsales: Custom fields and modules — Custom field reference

Standards:

• ITU-T E.164 — International phone numbering — Specification for E.164 phone format (the safest format for international CRM imports)
• GDPR Article 28 — Processor obligations — Applies when validation tools receive your Freshsales import files

Related Guides:

• Pipedrive CSV Import Errors — Similar SMB CRM, comparable error patterns
• CRM Import Error Codes Explained — Cross-platform error taxonomy

---

FAQ