# Import Contacts

> Learn how to import contacts into Waflow using CSV files, including file format requirements, column mapping, and error handling.

Source: https://edesy.in/docs/waflow/contacts/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:

| 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:

```csv
phone,first_name,last_name,email,company,purchase_date,customer_type
+14155551234,John,Doe,john@example.com,Acme Corp,2024-01-15,vip
+14155555678,Jane,Smith,jane@example.com,Tech Inc,2024-02-20,regular
+442071234567,Bob,Wilson,bob@example.co.uk,London Ltd,2024-03-10,new
+919876543210,Priya,Kumar,priya@example.in,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:

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:

| 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      john@ex.com     vip           │
│ +14155555678   Jane Smith    jane@ex.com     regular       │
│ +442071234567  Bob Wilson    bob@ex.co.uk    new           │
│ +919876543210  Priya Kumar   priya@ex.in     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

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:

| 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:

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

| 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:

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

| 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:

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:

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

See [API Documentation](https://edesy.in/docs/waflow/settings/integrations) 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](https://edesy.in/docs/waflow/contacts/tags-segments)
- [Create segments for targeting](https://edesy.in/docs/waflow/contacts/tags-segments)
- [Set up custom fields](https://edesy.in/docs/waflow/contacts/custom-fields)
- [Create a campaign](https://edesy.in/docs/waflow/campaigns/create-campaign)