Bulk import troubleshooting

Having trouble importing contacts? This guide covers the most common import failures and how to fix them.

File issues

Problem	Cause	Fix
File too large	CSV exceeds 50MB or 50,000 rows	Split into smaller files. Import in batches
Wrong file type	Uploaded .xlsx, .xls, or .txt	Export as .csv from your spreadsheet application
Encoding errors	File saved as ANSI, ISO-8859, or other non-UTF-8	Re-save as UTF-8 CSV. In Excel: Save As → CSV UTF-8
File won’t upload	Browser timeout or connection issue	Try a smaller file, clear browser cache, or use a different browser

Formatting problems

Problem	Cause	Fix
Columns not recognized	Header names do not match HoopAI fields	Use the mapping step to manually assign columns. See CSV format guide
Date fields showing wrong values	Ambiguous date format (01/02/2024 — Jan 2 or Feb 1?)	Use YYYY-MM-DD format to eliminate ambiguity
Phone numbers missing country code	Numbers like 5551234567 without +1	Add country code prefix. Use E.164 format: +15551234567
Phone parsed as scientific notation	Excel converts long numbers to 5.55E+09	Format the phone column as Text in Excel before saving
Tags not importing	Tags column contains invalid formatting	Use comma-separated values in quotes: “tag1, tag2, tag3”
Special characters garbled	Non-UTF-8 encoding	Re-save file as UTF-8. Check for accented characters (é, ñ, ü)
Empty rows imported	Blank rows in the CSV	Remove empty rows before importing

Duplicate handling

Scenario	What happens	How to control
Email matches existing contact	Depends on your duplicate setting	Choose Skip, Update, or Create New during import
Phone matches existing contact	Same as email matching	Same options
Both email and phone match different contacts	May create confusion	Clean your list before import — deduplicate by email first

Duplicate options explained

Skip — the row is ignored and the existing contact is unchanged
Update — the existing contact’s fields are updated with the CSV data (non-empty fields only)
Create New — a new contact is created even if duplicates exist (not recommended)

Use Update if you are refreshing existing contact data. Use Skip if you only want to add new contacts.

Missing required fields

Every row needs at least one identifier (email or phone). Rows missing both are skipped. Common missing field issues:

Issue	Fix
Rows with no email or phone	Add at least one identifier per row, or remove the row
Required custom fields missing	Make sure your CSV includes columns for any required custom fields
Name fields empty	Not technically required, but contacts without names are hard to identify

Custom field mapping failures

Problem	Cause	Fix
Custom field not appearing in mapping	Field key does not match column header	Use the field’s key (not display name). Check in Settings → Custom Fields
Dropdown values not matching	CSV value does not match the dropdown options exactly	Ensure exact match including case and spacing
Number field receiving text	CSV contains non-numeric data in a number column	Clean the data — remove currency symbols, commas, text
Date field not populating	Date format not recognized	Use YYYY-MM-DD

Import stuck or timed out

Symptom	Cause	Fix
Import shows “Processing” for hours	Very large file or server load	Wait up to 1 hour for large imports. If still stuck, contact support
Import completed but contacts missing	Rows were skipped due to errors	Check the import results report — it shows skipped rows and reasons
Import succeeded but fields are empty	Column mapping was incorrect	Re-import with correct column mapping
Partial import	File had errors partway through	Fix the reported errors and re-import the remaining rows

Import results report

After every import, HoopAI generates a results summary:

Total rows processed
Successfully imported
Skipped (duplicates)
Failed (errors)
Download error report — a CSV listing failed rows with the specific error for each

Always check this report after importing to catch issues.

Best practices

Always do a test import first

Import 5–10 rows first to verify your formatting and column mapping before importing the full list.

Clean data in your spreadsheet first

Remove empty rows, fix phone formats, standardize dates, and deduplicate before exporting to CSV.

Keep a backup of the original file

Save a copy of your CSV before importing, in case you need to reference or re-import.

Tag imported contacts

Apply a tag during import (e.g., “March 2024 Import”) so you can easily find and manage them later.

General

Communication

Websites & Funnels

Workflows & Data

Integrations & Social

File issues

Formatting problems

Duplicate handling

Duplicate options explained

Missing required fields

Custom field mapping failures

Import stuck or timed out

Import results report

Best practices

​File issues

​Formatting problems

​Duplicate handling

​Duplicate options explained

​Missing required fields

​Custom field mapping failures

​Import stuck or timed out

​Import results report

​Best practices

File issues

Formatting problems

Duplicate handling

Duplicate options explained

Missing required fields

Custom field mapping failures

Import stuck or timed out

Import results report

Best practices