CSV Import Guide

How do I prepare my CSV file?

Required Headers (minimum):

• firstName
• lastName
• phoneNumber

Tip

Clean your CSV before uploading to avoid validation errors and ensure successful delivery.

CSV Preparation Checklist:

• Include required headers exactly as shown
• Remove empty rows and columns

What’s the step-by-step import process?

1. Access the Send View

   • Go to Bulk SMS page
   • Select “Send” view
   • Click “Upload CSV File”

2. Select Your File

   • Choose your prepared CSV file
   • Click “Open” to begin upload

3. Fix Header Issues

   • If headers aren’t formatted correctly
   • Click “Convert All Headers”
   • System will standardize header names

4. Resolve Phone Number Issues

   • If phone numbers are malformed
   • Click “Fix All Issues”
   • System will standardize phone formats

5. Remove Duplicates

   • If duplicate phone numbers exist
   • Click “Remove All Duplicates”
   • System will keep unique entries only

6. Proceed to Campaign Setup

   • Click “Next” to continue
   • Move to campaign configuration

What are List Segmentation and Campaign Assignment?

After uploading your CSV, you’ll see two optional features:

List Segmentation

What it does: Uploads a large list and sends in equal proportions over hours/days

When to use:

• Large campaigns (1000+ contacts)
• Protecting deliverability rates
• Spreading sends over time

Recommended limit: No more than ~100 messages every 5 minutes

Campaign Assignment

What it does: Managers/admins can assign the campaign to specific users’ accounts

When to use:

• Team management scenarios
• Management Assigning of Campaigns

Can I use both together? Yes! List Segmentation and Campaign Assignment can be used together. If you don’t need either feature, simply click “Next” to skip.

What validation errors might I see?

Common CSV Issues:

Header Problems:

• Missing required headers
• Incorrectly spelled headers
• Extra spaces in header names
• Solution: Click “Convert All Headers”

Phone Number Issues:

• Invalid phone number formats
• Missing area codes
• International formatting problems
• Solution: Click “Fix All Issues”

Duplicate Data:

• Same phone number appears multiple times
• Duplicate contact entries
• Solution: Click “Remove All Duplicates”

Data Quality Issues:

• Empty required fields
• Invalid characters in names
• Malformed data entries
• Solution: Clean CSV manually and re-upload

How do I fix validation errors?

1. Review Error Messages

   • System will highlight specific issues
   • Note which columns/rows have problems

2. Use Built-in Fixes

   • Try “Convert All Headers” first
   • Then “Fix All Issues” for phone numbers
   • Finally “Remove All Duplicates”

3. Manual Corrections (if needed)

   • Download the error report
   • Fix issues in your CSV file
   • Re-upload the corrected file

4. Verify Results

   • Check that all errors are resolved
   • Confirm data looks correct
   • Proceed to campaign setup

What’s the best CSV format?

Recommended CSV Structure:

firstName,lastName,phoneNumber
John,Smith,5551234567
Jane,Doe,5559876543
Mike,Johnson,5555551234

Additional Optional Fields:

• email (if available)
• vehicle (for targeted messaging)
• source (for tracking)
• notes (for context)

Note

While additional fields can be included, only firstName, lastName, and phoneNumber are required for campaign creation.

What should I avoid when preparing CSVs?

Don’t Include:

• Special characters in names (unless necessary)
• Inconsistent phone number formats
• Empty rows between data
• Multiple header rows
• Merged cells or complex formatting

Do Include:

• Clean, consistent data
• Proper phone number formatting
• Complete required fields for all contacts
• Logical, readable structure

How do I handle large files?

For Large Lists (1000+ contacts):

• Use List Segmentation feature
• Consider breaking into smaller files
• Plan sending schedule carefully
• Monitor Twilio health scores

File Size Recommendations:

• Keep individual files under 10MB when possible
• Test with smaller batches first
• Use segmentation for delivery control

---

Once your CSV is successfully imported and validated, continue to Creating Campaigns to set up your messaging and schedule.