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:

Requirement	Details
File type	CSV (Comma-Separated Values)
Encoding	UTF-8 (recommended) or UTF-16
Size limit	10 MB per file (up to 100,000 rows)
Header row	First row must contain column names
Phone column	Required - contains phone numbers

Phone Number Format#

Phone numbers must include the country code:

Format	Valid?	Notes
+14155551234	Yes	Recommended format
14155551234	Yes	Will add + automatically
+1 415 555 1234	Yes	Spaces removed automatically
+1-415-555-1234	Yes	Dashes removed automatically
(415) 555-1234	No	Missing country code
4155551234	No	Missing 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:

Good Names	Avoid
phone, phone_number	Column1, A
first_name, firstName	name1
email, email_address	contact
purchase_date	date

Waflow will attempt to auto-match common column names.

Download Sample Template#

Get a properly formatted template:

Go to Contacts > Import
Click Download Sample Template
Open in your spreadsheet application
Replace sample data with your contacts
Save as CSV

The template includes all default fields plus example custom fields.

Import Process#

Step 1: Start Import#

Go to Contacts in the sidebar
Click Import button
Select CSV Import

Step 2: Upload File#

Drag and drop your CSV file, or click to browse
Wait for the file to upload and parse
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:

CSV Column	Auto-Matched To
phone, mobile, whatsapp	Phone Number
first_name, firstname, first	First Name
last_name, lastname, last	Last Name
email, email_address	Email
company, organization, org	Company

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:

Option	Behavior
Skip duplicates	Keep existing contact, ignore import row
Update duplicates	Merge import data into existing contact
Replace duplicates	Overwrite existing contact with import data

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:

Option	Behavior
Keep empty	Set field to empty/null
Keep existing	Don't overwrite if updating
Use default	Apply a default value

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:

Error Type	Example	Resolution
Invalid phone	Missing country code	Fix in CSV and re-upload
Invalid email	Bad format	Fix or skip the column
Missing required	Empty phone field	Fix or remove the row
Invalid date	Wrong date format	Use YYYY-MM-DD format

Step 6: Import#

Review the summary and preview
Click Start Import
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:

Column	Description
row_number	Original row in your CSV
phone	Phone number (if valid)
error_type	Category of error
error_message	Detailed explanation
original_data	The original row data

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:

Download the error report
Open your original CSV
Fix the issues identified
Save the corrected file
Import again

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

Import Limits#

Plan	Contacts per Import	Imports per Day
Starter	5,000	3
Professional	25,000	10
Business	100,000	Unlimited
Enterprise	Unlimited	Unlimited

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

Import History#

View past imports:

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

Best Practices#

Before Import#

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

Column Mapping#

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

Duplicate Handling#

Scenario	Recommended Setting
First import ever	Skip (no duplicates expected)
Regular sync from CRM	Update (merge new data)
Complete data refresh	Replace (overwrite old data)
Uncertain source	Skip (safe option)

Large Imports#

For imports over 10,000 contacts:

Split into multiple files
Import during off-peak hours
Monitor import progress
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)#

Open CSV in a text editor (not Excel)
Save as UTF-8 encoding
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: