Skip to main content
Last Updated: May 13, 2026, 11:42 AM

Importing Contacts

Import hundreds of contacts safely in just minutes. Quantixone guides you through a 4-phase process with duplicate detection and data validation at each step. This guide explains all file formats, field requirements, and data format specifications so you can prepare your import without errors.


Supported File Formats

You can import contacts using any of these file formats:

FormatExtensionMax SizeNotes
CSV.csv5 MBComma-separated values, UTF-8 encoding recommended
Excel.xlsx5 MBMicrosoft Excel 2007 and newer
Excel.xls5 MBMicrosoft Excel 97-2003 format

Tip: CSV files are the most reliable. If using Excel, ensure your file is saved in standard format (not protected or macro-enabled).


Field Format Specifications

Before preparing your import file, understand how each field should be formatted:

Required Fields

Email Address

  • Format: user@domain.tld
  • Example: rajesh@company.com, priya.sharma@example.co.in
  • Must be valid email format (validated during import)
  • Only one email per row (additional emails in separate column)

Phone Number

  • System stores in E.164 format (international standard): +919876543210
  • Input can use any format — system automatically converts and removes formatting
  • E.164 format examples: +919876543210 (India), +918765432109 (India)
  • Accepted input formats:
    • With dashes: +91-9876543210, +91-8765432109
    • With spaces: +91 9876543210, +91 8765432109
    • Local format: 9876543210 (requires default country setting) ✓
    • No formatting: +919876543210
  • Only one phone per row (additional phones in separate column)
  • System removes dashes, spaces, and other formatting automatically

Name Fields

  • first_name: Text (required if contact_name not provided), 255 characters max
  • last_name: Text (optional), 255 characters max
  • contact_name: Text (required if first_name not provided), 255 characters max
  • Example: Rajesh and Kumar OR Rajesh Kumar

Company Name

  • Format: Text, 255 characters max
  • Example: Acme Corporation, Startup Inc.
  • Auto-creates company if doesn't exist

Date & Time Fields

Date of Birth

  • Format: YYYY-MM-DD (ISO 8601 format)
  • Example: 1990-05-15, 1985-12-25
  • Any other format will be rejected

Task Due Date (when creating tasks via import)

  • Format: One of these three formats (all interpreted as UTC):
    • Date only: YYYY-MM-DD (e.g., 2026-05-01)
    • DateTime without timezone: YYYY-MM-DDTHH:MM:SS (e.g., 2026-05-01T14:30:00)
    • DateTime with Z: YYYY-MM-DDTHH:MM:SSZ (e.g., 2026-05-01T14:30:00Z)
  • Invalid formats are silently ignored (due_date left empty)

Location & Address Fields

FieldFormatExample
addressText, street address123 Main Street
cityTextNew York
stateText or abbreviationNY or New York
postal_codeText10001, M5V 3A9
countryText or ISO codeUS, United States, IN, India
timezoneIANA timezoneAmerica/New_York, Asia/Kolkata

Other Standard Fields

FieldFormatExample
titleJob title, textVP of Sales, Software Engineer
gendermale, female, non_binary, prefer_not_to_saymale
websiteFull URL with protocolhttps://example.com
linkedin_urlFull LinkedIn URLhttps://linkedin.com/in/rajesh-kumar
twitter_urlFull Twitter URLhttps://twitter.com/rajeshkumar
instagram_urlFull Instagram URLhttps://instagram.com/rajesh_kumar
github_urlFull GitHub URLhttps://github.com/rajesh-kumar
skype_idSkype usernamerajesh.kumar123
preferred_languageISO 639-1 language codeen, es, fr, hi
preferred_contact_methodemail, phone, smsemail
typelead, prospect, customer, partner, otherlead

Structured List Fields

These fields accept semicolon-separated values:

Tags

  • Format: Semicolon-separated text
  • Example: VIP;Enterprise;Hot
  • Auto-creates new tags if they don't exist
  • Maximum 50 tags per contact

Skills (from enrichment or manual)

  • Format: Semicolon-separated
  • Example: Python;JavaScript;Project Management;Sales

Languages (from enrichment or manual)

  • Format: Semicolon-separated
  • Example: English;Spanish;Hindi

Departments (enriched)

  • Format: Semicolon-separated
  • Example: Sales;Marketing;Business Development

Functions (enriched)

  • Format: Semicolon-separated
  • Example: Sales;Account Management;Business Development

Task Enums for Import

When creating tasks during import, use ONLY these valid values:

Task Status — Start task with one of these:

  • pending — Task waiting to be started
  • in_progress — Task actively being worked on
  • completed — Task finished
  • blocked — Task cannot proceed

Task Priority — Set importance level:

  • low — Non-urgent, background work
  • medium — Normal priority (default)
  • high — Urgent, needs immediate attention

Task Type — Specify what action is needed:

  • call — Phone call required
  • email — Email follow-up required
  • follow_up — General follow-up (default)
  • meeting — Meeting or appointment
  • other — Miscellaneous task type

Important: Invalid enum values (like complete, important, phone_call) are silently converted to defaults. Use EXACT values shown above.

Custom Fields

Custom fields must be created BEFORE import. Use your custom field name directly as the column header — the system automatically recognizes it.

Field TypeFormatExample
TextPlain textCompany details here
NumberNumeric (no currency symbols)85, 1250.50
DateYYYY-MM-DD2026-05-01
DropdownExact match from field optionsHigh, Medium, Low
Checkboxtrue, false, 1, 0true
Multi-selectSemicolon-separated valuesOption1;Option2;Option3

Column Header Format: Just use the field name exactly as it appears in your Settings:

  • If your custom field is named Lead Score → column header is Lead Score
  • If your custom field is named Industry → column header is Industry
  • No prefix needed!

Column Naming Conventions

Your CSV/Excel headers must match field names exactly:

Column Header Names

Standard System Fields:

first_name, last_name, email, phone, company, date_of_birth,
address, city, state, postal_code, country, timezone,
title, gender, website, linkedin_url, twitter_url,
skype_id, preferred_language, preferred_contact_method,
tags, skills, languages, departments, functions

Custom Fields: Simply use your custom field name exactly as it appears in Quantixone Settings:

Lead Score, Industry, Annual Revenue, Department, Market Segment

No prefix needed — just match the field name in your Settings.

When importing notes or tasks, use these column headers:

Notes (auto-created):

  • note.body — Add notes to contacts automatically

Tasks (auto-created with task enums):

  • task.title — Task name (required)
  • task.description — Task description (optional)
  • task.statuspending, in_progress, completed, or blocked
  • task.prioritylow, medium, or high
  • task.typecall, email, meeting, follow_up, or other
  • task.due_date — Format: YYYY-MM-DD

4-Phase Import Process

Import contacts safely using a structured 4-phase workflow:

Phase 1: Upload → Phase 2: Validate & Detect → Phase 3: Confirm → Phase 4: Execute
(CSV file) (Dry-run, no data written) (Merge decisions) (Background job)

Each phase is reversible until Phase 4, so you can adjust your approach.


Phase 1: Upload Your File

Phase 1: Uploading a file

Step 1: Go to Contacts > Import

  1. Click Contacts in left sidebar
  2. Click Import Contacts

Step 2: Select Your File

  1. Click Choose File
  2. Select CSV or Excel file from your computer
  3. File size limit: 5 MB
  4. Support formats: .csv, .xlsx, .xls

Step 3: Map Your Columns

Mapping your columns

The system shows your file's columns and lets you map them to contact fields:

  1. System Fields — Email, phone, name, company, etc.
  2. Custom Fields — Use format: custom.field_name
  3. Skip Columns — Leave unmapped columns blank
  4. Reorder — Drag to reorder (optional)

Step 4: Review Preview

  1. See first few rows of your data
  2. Confirm mapping is correct
  3. Check data looks reasonable
  4. Click Next to move to validation

Phase 2: Validate & Detect Duplicates

This is a dry-run. No data is written yet.

The system analyzes your import file and checks against existing contacts.

Step 1: System Validates Data

System checks for:

  • Required Fields — No empty required fields
  • Email Format — Valid email addresses
  • Phone Format — Properly formatted phone numbers
  • Field Types — Data matches field types (number, date, etc.)
  • Invalid Values — Out-of-range values for dropdowns

Result: Shows validation errors (if any) by row

Step 2: Duplicate Detection

System detects three types of duplicates:

Duplicates Within Your Import File:

  • Rows that are identical to each other
  • Example: Same email appears twice in your CSV

Duplicates Against Existing Contacts:

  • Your import rows match contacts already in the system
  • Example: rajesh@company.com already exists in database
  • System shows which existing contact matches

Fuzzy Matches (Similarity Detected):

  • Name + company similar to existing contacts
  • Confidence level shown (70%, 80%, 90%, 100%)
  • Flagged for you to review

Step 3: Review Results Summary

  1. Total Rows: How many you're importing
  2. New Contacts: Rows that will create new contacts
  3. Updates: Rows that match existing contacts (will merge)
  4. Flagged Duplicates: Rows needing manual review
  5. Errors: Rows with validation issues
  6. Ready to Import: Count of valid rows

Step 4: Check Details (Optional)

Click on any flagged row to see:

  • What existing contact it matches
  • Confidence level (how similar)
  • Specific fields that match
  • Preview of what will happen if merged

Phase 3: Confirm & Make Merge Decisions

Confirm and merge decisions

Still no data written. You control what happens next.

Step 1: Review Duplicate Flags

For each flagged duplicate, decide:

  1. AUTO Merge — Let system choose the best match automatically
  2. MANUAL Merge — You pick which existing contact to merge with
  3. OVERRIDE — Don't merge, create as new contact anyway

Step 2: Set Field Precedence

Setting field precedence

When merging, which source should win?

  1. Keep Existing Data — Keep current contact's values
  2. Use Import Data — Update with values from your import file
  3. Combine Both — Keep existing + add new (for additional fields)

Step 3: Confirm Ready to Import

  1. Review summary one more time
  2. Confirm:
    • Number of new contacts to create
    • Number of updates to existing contacts
    • Number of merges to execute
  3. Click Proceed with Import to enter Phase 4

Phase 4: Execute Import

Data is now written. Import runs in the background.

Step 1: System Processes Import

Import executes asynchronously in the background:

  • System processes in batches (200 rows at a time)
  • Doesn't timeout even with large files
  • You can navigate away; import continues
  • Progress available in Background Jobs

Step 2: Track Progress

  1. Go to Contacts > Import Status (or Background Jobs)
  2. See progress:
    • Processed — Rows completed so far
    • Successful — Rows successfully imported
    • Failed — Rows with errors
    • Status — In Progress / Completed

Step 3: Review Results

Import results

When import completes:

  1. Success Summary

    • Total new contacts created
    • Total contacts updated
    • Total duplicates merged
    • Total errors (if any)
  2. Detailed Results (downloadable)

    • Row-by-row status
    • New contact IDs created
    • Errors with explanations
    • Merge confirmations

What Gets Imported

During import, the system creates or updates:

Contacts

  • All mapped contact fields
  • System fields (name, email, phone, etc.)
  • Custom fields (using field names from Settings)

Companies (Auto-Created)

  • If company_name included in import
  • Company auto-created if doesn't exist
  • Contact linked to company

Tags (Auto-Created)

  • If tags column included
  • Tags auto-created if new
  • Applied to imported contacts

Custom Fields

  • Populated if mapped correctly
  • Use field name exactly as it appears in Settings (e.g., Lead Score, Industry)
  • Must exist before import (create custom fields first)

Tasks (Optional)

  • If task.title included in your file
  • Auto-creates follow-up task for each imported contact
  • Use task enums from top of this page for task.status, task.priority, task.type
  • Example: task.title, task.description, task.status, task.priority, task.type
  • Useful for assigning work after import

Notes (Optional)

  • If note.body included
  • Auto-creates note on each contact
  • Useful for import source tracking

Complete Import Examples

CSV Example with All Field Types

first_name,last_name,email,phone,company,date_of_birth,city,state,postal_code,country,title,gender,website,Lead Score,Industry,tags,task.title,task.status,task.priority,task.type,task.due_date,note.body
Rajesh,Kumar,rajesh@acmecorp.com,+919876543210,Acme Corp,1990-05-15,Mumbai,MH,400001,IN,VP of Sales,male,https://acmecorp.com,85,Technology,VIP;Enterprise;Hot,Follow up with Rajesh,pending,high,call,2026-05-15,Met at conference
Priya,Sharma,priya@startupindia.io,+918765432109,Startup India,1992-03-22,Bangalore,KA,560001,IN,Product Manager,female,https://startupindia.io,60,SaaS;Tech,Prospect;Tech,Schedule demo,in_progress,medium,meeting,2026-05-10,Requested product demo
Vikram,Patel,vikram@techsolutions.com,+919123456789,Tech Solutions,1988-11-30,Hyderabad,TS,500001,IN,CTO,male,,95,Consulting,Partner;Enterprise,Contract review,pending,high,email,2026-05-20,VP referral

Excel Example with Proper Formatting

First NameLast NameEmailPhoneCompanyDate of BirthCityStatePostal CodeCountryTitleGenderWebsiteLead ScoreIndustryTagsTask TitleTask StatusTask PriorityTask TypeTask Due DateNote Body
RajeshKumarrajesh@acmecorp.com+919876543210Acme Corp1990-05-15MumbaiMH400001INVP of Salesmalehttps://acmecorp.com85TechnologyVIP;Enterprise;HotFollow up with Rajeshpendinghighcall2026-05-15Met at conference
PriyaSharmapriya@startupindia.io+918765432109Startup India1992-03-22BangaloreKA560001INProduct Managerfemalehttps://startupindia.io60SaaS;TechProspect;TechSchedule demoin_progressmediummeeting2026-05-10Requested product demo
VikramPatelvikram@techsolutions.com+919123456789Tech Solutions1988-11-30HyderabadTS500001INCTOmale95ConsultingPartner;EnterpriseContract reviewpendinghighemail2026-05-20VP referral

Key Points in Examples Above:

  1. Email Format: rajesh@company.com — Must be valid email format
  2. Phone Format: System stores in E.164 standard (+919876543210 no dashes). Input can have dashes/spaces which are automatically removed.
  3. Date Format: 1990-05-15 — Must be YYYY-MM-DD
  4. Tags: VIP;Enterprise;Hot — Semicolon-separated, auto-creates if new
  5. Task Status: pending, in_progress, completed, blocked — Must use exact values
  6. Task Priority: low, medium, high — Must use exact values
  7. Task Type: call, email, meeting, follow_up, other — Must use exact values
  8. Task Due Date: 2026-05-15 — Format as YYYY-MM-DD
  9. Custom Fields: Lead Score, Industry — Use field name exactly as shown in Settings (no prefix)
  10. Optional Fields: Leave empty/blank if not needed — no errors from missing optional fields

Common Import Scenarios

Scenario 1: Simple Contact List (Minimal Fields)

first_name,last_name,email,phone
Rajesh,Kumar,rajesh@example.com,+919876543210
Priya,Sharma,priya@example.com,+918765432109

(Note: You can also use +91-9876543210 or 9876543210 with spaces/dashes - system automatically converts to E.164 format)

Scenario 2: Contacts with Tags and Custom Fields

first_name,last_name,email,company,tags,Lead Score
Rajesh,Kumar,rajesh@example.com,Acme India,VIP;Enterprise,85
Priya,Sharma,priya@example.com,Startup India,Prospect,60

Scenario 3: Contacts with Auto-Generated Tasks

first_name,last_name,email,task.title,task.status,task.priority,task.type
Rajesh,Kumar,rajesh@example.com,Initial meeting,pending,high,meeting
Priya,Sharma,priya@example.com,Follow-up call,pending,medium,call

Scenario 4: Full Contact Record with Everything

first_name,last_name,email,phone,company,date_of_birth,city,state,title,tags,Lead Score,task.title,task.status,task.priority,note.body
Rajesh,Kumar,rajesh@example.com,+919876543210,Acme Corp,1990-05-15,Mumbai,MH,VP Sales,VIP;Enterprise,85,Follow up,pending,high,Met at trade show

Import Best Practices

Before Importing: Data Preparation Checklist

  1. Create Custom Fields First

    • Set up all custom fields BEFORE uploading import file
    • System cannot create custom fields during import
    • Column headers must match field names exactly (case-sensitive)
    • Example: If custom field is "Lead Score", use Lead Score as column header
  2. Format Verification

    • ✅ Emails: Valid format like user@domain.com (not user@domain, not user@@domain.com)
    • ✅ Phones: Any format with or without dashes/spaces (e.g., +919876543210, +91-9876543210, 555-0123, 9876543210)
    • ✅ Dates of Birth: ISO format YYYY-MM-DD (not 05/15/1990, not 15-May-1990)
    • ✅ Task Enums: Exact values — pending, in_progress, completed, blocked (lowercase)
    • ✅ Tags: Semicolon-separated Tag1;Tag2;Tag3 (not comma-separated, not pipe-separated)
    • ✅ URLs: Full format https://example.com (not example.com)
    • ✅ Country: US, IN, GB or full name (not United States abbreviation)
    • ✅ Custom Fields: Use field name exactly as it appears in Settings (e.g., Lead Score not custom.lead_score)
  3. Data Quality Steps

    • Remove duplicate rows in your file before uploading
    • Remove test/sample rows
    • Trim whitespace from names (e.g., RajeshRajesh)
    • Standardize phone formats (pick E.164 or local, be consistent)
    • Validate email addresses (use email validation tool)
    • Fix misspelled company names
  4. Test with Small Import

    • Extract 10-20 sample rows
    • Test import process end-to-end
    • Verify all formats work correctly
    • Review Phase 2 validation results
    • Only then import full file
  5. Prepare Merge Strategy

    • Decide in advance: keep existing data or use import data?
    • Plan for fuzzy duplicates (similar names)
    • Know which field takes precedence (e.g., if phone conflicts)

During Import: Phase-by-Phase Best Practices

Phase 1: Upload

  • Verify column headers match exactly (case-sensitive for custom fields)
  • Check preview rows for correct mapping
  • Ensure first few rows are representative

Phase 2: Validate & Detect

  • Read ALL validation errors (don't skip to Phase 3)
  • Fix field format issues in your file
  • Review duplicate detection carefully — fuzzy matches need judgment
  • Check row counts: does "Ready to Import" match expectation?

Phase 3: Confirm Decisions

  • Don't rush merge decisions (these are permanent)
  • Review auto-merge preview to see what will happen
  • For fuzzy matches: click details to compare side-by-side
  • Set field precedence based on data quality

Phase 4: Execute

  • Don't interrupt import while in progress
  • Background job will continue even if you leave
  • Monitor progress in Background Jobs section
  • Review final results and error report

After Import: Verification & Cleanup

  1. Verify Sample Contacts

    • Open 5-10 randomly selected imported contacts
    • Check fields populated correctly
    • Verify dates display in correct format
    • Confirm tasks created properly
  2. Check Import Results Report

    • Download detailed results
    • Review any error rows (if failed rows exist)
    • Verify merge counts match expectations
  3. Fix Issues if Needed

    • If large numbers of rows failed, re-run with corrected file
    • Update any incorrectly merged contacts
    • Add missing data that couldn't be imported
  4. Organize & Enrich

    • Add tags to organize imported contacts
    • Assign tasks to team members
    • Run enrichment on high-value contacts
    • Follow up on created tasks

Troubleshooting & Format Issues

Email Format Problems

Problem: "Invalid email format in the 'email' column"

  • rajesh@company — Missing domain extension
  • rajesh@@company.com — Double @
  • rajesh company.com — Missing @
  • rajesh@company.com — Correct format
  • priya.sharma@example.co.in — Correct with subdomain

Solution: Verify each email has format user@domain.tld


Phone Format Problems

Problem: Phone not recognized or formatted incorrectly

  • 9876543210 (without country code) — Ambiguous which country
  • 91-9876543210 (country code without + prefix)
  • +919876543210 (no dashes, hard to read)
  • +91-9876543210 — E.164 with dashes
  • 555-0123 — Local format (country applied from default)

Solution:

  • Use E.164 format: +<country_code>-<phone> for international
  • Or use local format: system will apply default country (India)
  • Set default country in Phase 2 if needed

Date Format Problems

Problem: "Invalid date format" or date appears blank

For Date of Birth field:

  • 05/15/1990 — Wrong format (American style)
  • 15-May-1990 — Text format not recognized
  • 1990/05/15 — Wrong separators
  • 1990-05-15 — Correct ISO format (YYYY-MM-DD)

For Task Due Dates:

  • 05-01-2026 — Ambiguous (US vs international)
  • May 1, 2026 — Text format not recognized
  • 2026-05-01 — Date only (ISO format)
  • 2026-05-01T14:30:00 — With time (no timezone)
  • 2026-05-01T14:30:00Z — With Z suffix (UTC)

Solution: Always use ISO format YYYY-MM-DD for dates, YYYY-MM-DDTHH:MM:SS for datetime


Task Enum Problems

Problem: Tasks created but with wrong status/priority/type

Task Status Issue:

  • complete — Not recognized (silently becomes pending)
  • done — Not recognized (silently becomes pending)
  • pending — Correct
  • in_progress — Correct
  • completed — Correct
  • blocked — Correct

Task Priority Issue:

  • important — Not recognized (becomes medium)
  • urgent — Not recognized (becomes medium)
  • low — Correct
  • medium — Correct
  • high — Correct

Task Type Issue:

  • phone_call — Not recognized (becomes other)
  • email_followup — Not recognized (becomes other)
  • call — Correct
  • email — Correct
  • meeting — Correct
  • follow_up — Correct
  • other — Correct

Solution: Use EXACT lowercase values. Invalid values silently convert to defaults (pending, medium, other)


Custom Field Problems

Problem: Custom field data not imported or mapped wrong

  • lead_score — Wrong format (use exact field name from Settings)
  • Lead score — Wrong capitalization
  • leadScore — Wrong capitalization
  • Lead Score — Correct (matches field name in Settings exactly)

Solution:

  • Custom field must exist BEFORE import
  • Use exact field name as shown in Quantixone Settings (copy-paste to avoid typos)
  • Column headers are case-sensitive

Problem: "Field type mismatch" error

  • For Number fields: Use 85 or 1250.50 (no commas, no $ symbols)
  • For Date fields: Use YYYY-MM-DD format
  • For Dropdown: Use exact option value from dropdown list
  • For Checkbox: Use true, false, 1, or 0
  • For Multi-select: Use semicolon-separated values

Tag Problems

Problem: Tags not created or merged incorrectly

  • VIP, Enterprise, Hot — Comma-separated (treated as one tag)
  • VIP | Enterprise | Hot — Pipe-separated (treated as one tag)
  • VIP;Enterprise;Hot — Semicolon-separated

Solution: Use semicolon (;) to separate multiple tags, not commas or pipes


Duplicate Detection Problems

Problem: "Duplicates not detected"

  • Exact email match: rajesh@company.com — Must match exactly (case-insensitive)
  • Exact phone match: +91-9876543210 — Must match exactly
  • Fuzzy match: Requires name + company to be 80%+ similar

Solution:

  • Verify email/phone formats match
  • Check if company names have typos (fuzzy match helps but not perfect)
  • Review Phase 2 detection results carefully

Problem: "Too many fuzzy matches flagged"

  • Fuzzy matching is conservative (80%+ threshold)
  • "Rajesh" vs "Raj" + same company = fuzzy match
  • Clean company names in your file to reduce false positives

Solution: Fix company name typos before import, review flagged matches carefully


File Upload Problems

Problem: "File size exceeds limit"

  • Maximum file size: 5 MB
  • Solution: Split into smaller files and import separately

Problem: "Unsupported file format"

  • Supported: .csv, .xlsx, .xls
  • Not supported: .ods, .numbers, .txt, .json
  • Solution: Convert to Excel or CSV format

Problem: "File appears corrupted"

  • File was protected or macro-enabled
  • Solution: Open in Excel, Save As standard format (.xlsx)

Column Mapping Problems

Problem: "Column name not recognized"

  • Column headers are case-sensitive for custom fields
  • Must match system field names exactly
  • Example: first_name ✅ but firstName ❌ or First Name

Solution:

  • Check spelling of column headers
  • For custom fields, verify exact name in Settings
  • Copy field name from Quantixone to avoid typos

Import Completion Problems

Problem: "Some rows failed, import partially completed"

  • Error report shows which rows failed and why
  • Download detailed results
  • Fix issues in those specific rows and re-import

Problem: "Import still running after 30 minutes"

  • Background job continues even if browser closed
  • Check Status in Background Jobs section
  • Large imports (10,000+ rows) may take time

Video Walkthrough

Watch the complete video tutorial on importing contacts into QuantixOne CRM.


What's Next