Import Contacts from CSV

Bulk import contacts from CSV files with column mapping.

Import hundreds or thousands of contacts from CSV files in minutes.

Prepare Your CSV

Required Columns

Your CSV must have:

Column	Format	Required
name	Any text	Yes
phone	E.164 format: [phone]	Yes

Optional Columns

Column	Format
email	Email address
company	Any text
tags	Comma-separated: prospect,enterprise

Example CSV

name,phone,email,company,tags
John Doe,[phone],[e-mail],Acme Corp,prospect
Jane Smith,[phone],[e-mail],Globex Inc,prospect,enterprise
Bob Johnson,[phone],[e-mail],Initech,lead

Save your CSV with UTF-8 encoding to preserve special characters in names.

Preview Import (Dry Run)

Always preview before importing:

consuelo contacts import contacts.csv --dry-run

Output shows:

Dry run: 150 contacts to import

Validation:
  ✓ 148 valid rows
  ✗ 2 rows with errors

Errors:
  Row 23: Invalid phone format (missing + prefix)
  Row 87: Invalid phone format (contains spaces)

Summary:
  Would import: 148 contacts
  Would skip: 2 contacts

Import Contacts

Once you’ve verified with dry-run:

consuelo contacts import contacts.csv

Progress is shown:

Importing contacts.csv...
  [████████████████████████████████████████] 100%

Imported: 148 contacts
Skipped: 2 contacts (validation errors)

Column Mapping

If your CSV uses different column names:

Map Different Names

consuelo contacts import contacts.csv \
  --map "Full Name=name,Phone Number=phone,Email Address=email"

The format is: CSV Column=CLI Field

Map Multiple CSVs

consuelo contacts import leads.csv \
  --map "Contact Name=name,Mobile=phone"

consuelo contacts import prospects.csv \
  --map "full_name=name,phone_number=phone"

Handle Import Errors

Common Validation Errors

Error	Cause	Fix
Invalid phone format	Missing + prefix	Add + before country code
Invalid phone format	Contains spaces/dashes	Remove all non-digit characters except +
Invalid phone format	Not E.164	Use +<country><number> format
Missing required field	Empty name or phone	Ensure all rows have values
Duplicate phone	Phone already exists	Skip or update existing contact

Fix CSV Before Import

For small errors, fix the CSV directly:

# View problematic rows
consuelo contacts import contacts.csv --dry-run 2>&1 | grep "Row"

# Edit CSV in your preferred editor
# Re-run import
consuelo contacts import contacts.csv

Skip Invalid Rows

If you want to import valid rows and skip invalid:

consuelo contacts import contacts.csv --skip-invalid

Skipped rows are logged for review.

Large Imports

For imports of 1000+ contacts:

Check File Size

ls -lh contacts.csv

Maximum file size is 50 MB. For larger files, split into multiple CSVs.

Monitor Progress

The CLI shows progress for large imports:

Importing contacts.csv (5,000 contacts)...
  [████████░░░░░░░░░░░░░░░░░░░░░░] 20% (1,000/5,000)

Performance Tips

• Use --quiet for slightly faster imports: consuelo contacts import large.csv --quiet
• Close other applications to free memory
• For very large imports (10k+), split into 5000-row chunks

Import with Tags

Add tags during import:

consuelo contacts import contacts.csv --tags "imported,2024-q1"

Tags are added to all imported contacts, in addition to any tags in the CSV.

Verify Import

After import, verify:

consuelo contacts list --filter "tags=imported" --limit 200

Export for Backup

Export contacts before making bulk changes:

consuelo contacts list --json > contacts-backup.json

Next Steps

• Contact Management — Manage imported contacts
• Queue Management — Add contacts to dial queues
• Set Up Twilio — Configure calling