Documentation Index
Fetch the complete documentation index at: https://docs.fanfare.io/llms.txt
Use this file to discover all available pages before exploring further.
Import Consumers
Import consumers in bulk using CSV files or integrations like Klaviyo. This guide covers all import methods and best practices for successful data imports.
Import Methods
| Method | Description | Best For |
|---|
| CSV Upload | Upload a CSV file | One-time imports, migrations |
| Klaviyo Import | Sync from Klaviyo lists | Ongoing marketing sync |
CSV Import
Starting a CSV Import
- Navigate to Audiences in the sidebar
- Click Create > Import Audience
- Follow the import wizard
Caption: Start the import wizard by uploading a CSV file
File Requirements
| Requirement | Specification |
|---|
| Format | CSV (comma-separated values) |
| Encoding | UTF-8 |
| Max Size | 10 MB |
| Max Rows | 100,000 rows |
| Header Row | Required |
Required Fields
At minimum, your CSV must include one identifier:
| Field | Description | Example |
|---|
| email | Email address (recommended) | [email protected] |
| phone | Phone number | +1234567890 |
| externalId | Your system’s ID | CUST-12345 |
Optional Fields
Include additional data to enrich consumer profiles:
| Field | Description | Example |
|---|
| firstName | First name | John |
| lastName | Last name | Smith |
| fullName | Full name | John Smith |
| tags | Comma-separated tags | VIP,Newsletter,Beta |
| loyaltyPoints | Current points | 1500 |
| loyaltyTier | Tier name | Gold |
| metadata | JSON custom data | {"source":"import"} |
Example CSV
email,firstName,lastName,tags,loyaltyPoints
[email protected],John,Smith,"VIP,Newsletter",1500
[email protected],Jane,Doe,Newsletter,500
[email protected],Bob,Johnson,"VIP,Beta",3000
Import Wizard Steps
Step 1: Upload File
- Drag and drop your CSV file
- Or click to browse and select
- File is validated for format
Caption: Drag and drop or browse to select your CSV file
Step 2: Map Fields
Map your CSV columns to Fanfare consumer fields:
- Review detected columns
- Select matching Fanfare field for each
- Skip columns you don’t want to import
- Validate mappings
Caption: Map your CSV columns to consumer fields
Set up how imported consumers will be organized:
| Option | Description |
|---|
| Create New Audience | Create a new audience with imported consumers |
| Add to Existing | Add consumers to an existing audience |
| Update Only | Update existing consumers, don’t create new |
Step 4: Review & Import
- Review the import summary
- Check for validation warnings
- Click Start Import
- Wait for processing
Caption: Review your import before processing
Step 5: Monitor Progress
Track import progress:
- Progress bar shows completion
- Errors are logged for review
- Success count updates in real-time
Caption: Monitor your import as it processes
Handling Duplicates
Duplicate Detection
Duplicates are detected by:
- Email (primary)
- Phone (secondary)
- External ID (if provided)
Duplicate Handling Options
| Option | Description |
|---|
| Skip | Don’t import duplicates |
| Update | Update existing with new data |
| Create New | Create separate record (not recommended) |
Klaviyo Import
If Klaviyo is configured, import directly from Klaviyo lists.
Prerequisites
- Klaviyo integration configured in Settings
- API key with list access
- Lists exist in Klaviyo
Starting Klaviyo Import
- Navigate to Audiences > Create > Import from Klaviyo
- Select the Klaviyo list to import
- Configure sync settings
- Start import
Caption: Select a Klaviyo list to import
Sync Options
| Option | Description |
|---|
| One-time Import | Import once, no ongoing sync |
| Continuous Sync | Keep synced with Klaviyo list |
Synced Audiences
When continuous sync is enabled:
- New Klaviyo subscribers are added automatically
- Removed subscribers are removed from audience
- Audience displays sync status and last sync time
Import Errors
Common Errors
| Error | Cause | Solution |
|---|
| Invalid email | Malformed email address | Fix email format in CSV |
| Missing required field | No identifier provided | Ensure email/phone/externalId |
| Invalid phone | Phone format incorrect | Use E.164 format (+1234567890) |
| Row too long | Data exceeds limits | Check for extra commas |
| Encoding error | Wrong file encoding | Save as UTF-8 |
Error Report
After import, download the error report:
- Click Download Error Report
- Review failed rows and reasons
- Fix issues in original CSV
- Re-import failed rows only
Caption: Download the error report to review failed imports
Best Practices
Before Import
- Clean your data - Remove duplicates, fix formatting
- Validate emails - Ensure valid email formats
- Use UTF-8 - Save CSV with proper encoding
- Test with small batch - Import 100 rows first
During Import
- Don’t close the browser - Let import complete
- Monitor progress - Watch for unexpected errors
- Note the import ID - For troubleshooting
After Import
- Review the summary - Check success/error counts
- Verify a sample - Check random consumers imported correctly
- Download error report - Review any failures
- Clean up - Delete source files with sensitive data
Data Privacy
Handling Sensitive Data
- Don’t import unnecessary personal data
- Consider data minimization
- Comply with GDPR/CCPA requirements
- Document data sources
Data Retention
- Imported consumer data is subject to your retention policies
- Sync sources are documented for compliance
- Audit trail available for imports
Troubleshooting
Import Stuck at 0%
- Check file size isn’t too large
- Verify file format is correct CSV
- Try refreshing the page
- Re-upload the file
Import Completed but No Consumers
- Check duplicate handling settings
- Verify field mapping was correct
- Review error report
- Ensure file had data rows
Consumers Missing Data
- Check field mapping
- Verify column names in CSV
- Look for encoding issues
- Check for extra whitespace
