Import Contacts

Importing contacts from CSV files is the fastest way to add your audience to Waflow. This guide covers file preparation, the import process, column mapping, validation, and error handling.

Preparing Your CSV File

Required Format

Your CSV file must meet these requirements:

Phone Number Format

Phone numbers must include the country code:

Tip: Always include the country code to avoid ambiguity. "4155551234" could be a US number or part of another country's number.

Sample CSV File

Here's an example of a properly formatted CSV:

phone,first_name,last_name,email,company,purchase_date,customer_type
+14155551234,John,Doe,[email protected],Acme Corp,2024-01-15,vip
+14155555678,Jane,Smith,[email protected],Tech Inc,2024-02-20,regular
+442071234567,Bob,Wilson,[email protected],London Ltd,2024-03-10,new
+919876543210,Priya,Kumar,[email protected],Mumbai Co,2024-04-05,vip

Column Naming

Use clear, consistent column names:

Waflow will attempt to auto-match common column names.

Download Sample Template

Get a properly formatted template:

1. Go to Contacts > Import
2. Click Download Sample Template
3. Open in your spreadsheet application
4. Replace sample data with your contacts
5. Save as CSV

The template includes all default fields plus example custom fields.

Import Process

Step 1: Start Import

1. Go to Contacts in the sidebar
2. Click Import button
3. Select CSV Import

Step 2: Upload File

1. Drag and drop your CSV file, or click to browse
2. Wait for the file to upload and parse
3. Waflow will preview the first few rows

If your file has encoding issues, try:

• Saving as UTF-8 in your spreadsheet application
• Selecting UTF-16 encoding option in Waflow

Step 3: Map Columns

Waflow displays your CSV columns and asks you to map them to Waflow fields:

┌─────────────────────────────────────────────────────────────────┐
│ Map Your Columns                                                 │
├─────────────────────────────────────────────────────────────────┤
│ CSV Column         →    Waflow Field                            │
├─────────────────────────────────────────────────────────────────┤
│ phone              →    [Phone Number ▼]        (Required)      │
│ first_name         →    [First Name ▼]                          │
│ last_name          →    [Last Name ▼]                           │
│ email              →    [Email ▼]                               │
│ company            →    [Company ▼]                             │
│ purchase_date      →    [+ Create Custom Field]                 │
│ customer_type      →    [Import as Tag ▼]                       │
└─────────────────────────────────────────────────────────────────┘

For each CSV column, select:

• Waflow field: Map to an existing field
• Create custom field: Create a new field for this data
• Import as tag: Convert values to tags
• Do not import: Skip this column

Auto-Matching

Waflow automatically matches common column names:

Review auto-matches and correct if needed.

Step 4: Configure Options

Set import behavior options:

Duplicate Handling

Choose what happens when a phone number already exists:

Tip: Use "Update duplicates" to enrich existing contacts with new data without losing information.

Tag Options

Optionally add tags to all imported contacts:

• Enter tag names separated by commas
• Tags are created if they don't exist
• Useful for tracking import batches (e.g., "import-dec-2024")

Empty Value Handling

Choose how to handle empty cells:

Step 5: Preview and Validate

Before importing, Waflow shows:

Import Summary

• Total rows in file
• Valid rows (will be imported)
• Invalid rows (will be skipped)
• Duplicate rows (based on your setting)

Sample Preview

First 5 rows as they will appear in Waflow:

┌────────────────────────────────────────────────────────────┐
│ Preview (first 5 contacts)                                  │
├────────────────────────────────────────────────────────────┤
│ Phone          Name          Email           Tags          │
│ +14155551234   John Doe      [email protected]     vip           │
│ +14155555678   Jane Smith    [email protected]     regular       │
│ +442071234567  Bob Wilson    [email protected]    new           │
│ +919876543210  Priya Kumar   [email protected]     vip           │
│ ...                                                        │
└────────────────────────────────────────────────────────────┘

Validation Errors

Review any validation issues:

Step 6: Import

1. Review the summary and preview
2. Click Start Import
3. Wait for the import to complete

Progress is shown in real-time:

Importing contacts...
████████████████████░░░░░░░░░░ 67%
6,700 of 10,000 contacts imported

Large imports may take several minutes. You can navigate away; the import continues in the background.

Step 7: Review Results

After import completes:

┌─────────────────────────────────────────────────────────────────┐
│ Import Complete                                                  │
├─────────────────────────────────────────────────────────────────┤
│ ✓ 9,850 contacts imported successfully                          │
│ ↻ 100 contacts updated (duplicates)                             │
│ ✗ 50 rows skipped (errors)                                      │
├─────────────────────────────────────────────────────────────────┤
│ [Download Error Report]  [View Imported Contacts]  [Done]       │
└─────────────────────────────────────────────────────────────────┘

Download the error report to see which rows failed and why.

Error Report

The error report is a CSV containing:

Common Errors

Invalid Phone Number

Row 45: +123 - Invalid phone number format

Cause: Number doesn't match any valid country code pattern

Fix: Verify the number and country code

Duplicate Phone Number

Row 102: +14155551234 - Duplicate phone number (skipped)

Cause: This number already exists in your contacts

Fix: Change duplicate handling to "Update" if you want to merge data

Invalid Email Format

Row 78: john@example - Invalid email address

Cause: Email doesn't contain a valid domain

Fix: Correct the email or leave empty

Date Format Error

Row 156: 15/01/2024 - Invalid date format, use YYYY-MM-DD

Cause: Date is not in the expected format

Fix: Convert dates to YYYY-MM-DD format (2024-01-15)

Field Type Mismatch

Row 203: "abc" - Expected number for field 'age'

Cause: Value doesn't match the custom field type

Fix: Ensure values match field types (numbers for number fields, etc.)

Fixing and Re-importing

If many rows failed:

1. Download the error report
2. Open your original CSV
3. Fix the issues identified
4. Save the corrected file
5. Import again

Use "Skip duplicates" on re-import to avoid creating duplicates of successfully imported contacts.

Import Limits

For very large imports (500k+), contact support for batch processing.

Import History

View past imports:

1. Go to Contacts > Import History
2. See list of all imports
3. Click any import to view:
   • Import date and time
   • Number of contacts imported
   • Settings used
   • Error report (if any)

Best Practices

Before Import

1. Clean your data: Remove duplicates, fix formatting
2. Validate phone numbers: Ensure country codes are present
3. Standardize formats: Consistent date formats, capitalization
4. Backup your CSV: Keep the original file
5. Test with a small batch: Import 10-20 contacts first

Column Mapping

1. Map all relevant columns: Don't skip valuable data
2. Create custom fields for unique data points
3. Use tags strategically: Import categories as tags
4. Review auto-mapping: Verify automatic matches

Duplicate Handling

Large Imports

For imports over 10,000 contacts:

1. Split into multiple files
2. Import during off-peak hours
3. Monitor import progress
4. Review error reports promptly

Automation via API

For regular imports, consider the API:

# Upload and import a file
curl -X POST https://api.waflow.com/v1/contacts/import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "duplicate_handling=update" \
  -F "tags=crm-sync"

See API Documentation for details.

Troubleshooting

File Won't Upload

• Check file size (under 10 MB)
• Verify it's a .csv file
• Try a different browser
• Check your internet connection

Encoding Issues (Special Characters)

If names show as "é" instead of "e":

1. Open CSV in a text editor (not Excel)
2. Save as UTF-8 encoding
3. Re-upload

All Rows Failing

• Check that phone column is correctly mapped
• Verify phone numbers have country codes
• Look for invisible characters (copy/paste issues)

Import Stuck

• Refresh the page and check import history
• Import may still be processing in background
• Contact support if stuck for more than 30 minutes

Next Steps

After importing contacts:

• Add tags to organize
• Create segments for targeting
• Set up custom fields
• Create a campaign