Skip to main content
Import contacts in bulk using CSV files. The import process validates numbers, normalizes formats, and handles duplicates automatically.

​
CSV Format

​
Required Column

ColumnDescriptionExample
phone_number or phone or msisdnContact phone number+14155551234 or 4155551234

​
Optional Columns

ColumnDescriptionExample
emailEmail address (stored but not used for SMS)user@example.com
first_nameContact first nameJohn
last_nameContact last nameDoe
carrierMobile carrier nameT-Mobile
line_typePhone line type (CELL PHONE, VOIP, LANDLINE, UNKNOWN)CELL PHONE
ad_network_sourceAd network source for attributionfacebook
ad_network_idAd network campaign/account IDcamp_123
Custom fields are set via the API’s custom_fields object when creating or updating contacts, not via CSV columns. See the API reference for details.

​
Example CSV

phone_number,first_name,last_name,email
+14155551234,John,Doe,john@example.com
+14155551235,Jane,Smith,jane@example.com
4155551236,Bob,Jones,bob@example.com

​
Import Process

Contacts can be imported via CSV through the dashboard or the bulk API endpoint.
The import supports a dry-run mode (dryRun: true, enabled by default) that validates all rows without persisting, so you can preview results before committing.

​
Phone Number Normalization

The import process automatically handles various phone number formats:
InputNormalized
4155551234+14155551234
(415) 555-1234+14155551234
415-555-1234+14155551234
+1 415 555 1234+14155551234
14155551234+14155551234
Numbers are assumed to be US (+1) unless they include a country code.

​
Duplicate Handling

When importing contacts that already exist:
ScenarioBehavior
Contact exists on this listCustom fields are merged (new values override)
Contact exists on different listAdded to this list with specified custom fields
Contact previously opted-outSkipped (opt-out is permanent)
New contactCreated and subscribed

​
Import Limits

The import endpoint accepts up to 5,000 contacts per request.

​
Import Validation

Each contact is validated during import:

​
Validation Rules

RuleInvalid ExampleResult
Valid phone formatabc123Skipped
Number length415555Skipped
Landline numbersLandline detectedStored (VOIP rejection is opt-in per account)
Not on blocklistPreviously blockedSkipped

​
Import Report

After import, you receive a report showing: 
Import Complete
---------------
Total rows: 10,000
Imported: 9,523
Skipped (invalid): 234
Skipped (opted-out): 198
Skipped (duplicate): 45

​
Triggering Welcome Journeys

When creating contacts via the API, set use_journeys: true on individual contacts to enroll them in active welcome journeys for the list.

​
Best Practices

Clean your CSV before importing. Remove obviously invalid numbers and test a small batch first.
Establish custom field naming conventions (e.g., source, campaign, cohort) and use them consistently across imports.
Always include a source custom field indicating where contacts came from. This helps with attribution and analysis.
Opted-out contacts cannot be resubscribed via import. This is by design for compliance.

​
Troubleshooting

Large imports can take time to start. Wait a few minutes. If still stuck, check file encoding (use UTF-8).
Check the skip reasons in the report. Common issues: invalid format, numbers already opted-out, landlines.
Ensure custom fields are passed in the custom_fields object when using the API. See the API reference for the correct format.
If numbers are non-US, include the full E.164 format with country code in the CSV.

​
Common Pitfalls

Common causes for import row failures:
  • Phone number format: Numbers must be in E.164 format (e.g., +14155551234). Numbers without the + prefix or country code are rejected.
  • Duplicate phone numbers: If the same phone number appears multiple times in your CSV, only the first occurrence is imported. Subsequent duplicates are skipped.
  • File encoding: CSV files must be UTF-8 encoded. Files saved with Windows-1252 or other encodings may produce garbled characters or parsing errors.
  • Column mapping: Ensure your CSV headers match the expected field names. Unrecognized columns are silently ignored.
  • Row limit: Each CSV import supports up to 5,000 rows. Split larger files into batches.

​
Next Steps

Custom Fields

Organize imported contacts

Audiences

Segment your contacts

Journeys

Automate onboarding