Importing Contacts

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

CSV Format

Required Column

Column	Description	Example
`phone_number`, `phone`, `phonenumber`, `mobile`, or `number`	Contact phone number	+14155551234 or 4155551234

Headers are matched case-insensitively against known aliases. Besides the phone aliases above, email/email_address, first_name/firstname/first/fname, last_name/lastname/last/lname, carrier, line_type/linetype/type, source/network_source, campaign_id/network_id, and the consent_date aliases listed below are detected automatically. Any header that isn’t a recognized alias must be mapped to the right field manually during import.

Optional Columns

Column	Description	Example
`email`	Email address (stored but not used for SMS)	user@example.com
`first_name`	Contact first name	John
`last_name`	Contact last name	Doe
`carrier`	Mobile carrier name	T-Mobile
`line_type`	Phone line type (CELL PHONE, VOIP, LANDLINE, UNKNOWN)	CELL PHONE
`consent_date`	Date the contact gave consent to be messaged. Accepts `YYYY-MM-DD`, `MM/DD/YYYY`, `MM-DD-YYYY`, or full ISO 8601 datetime. Future dates are rejected. Also accepted as column headers: `consentdate`, `consent`, `opted_in_date`, `optin_date`.	2025-01-15
`ad_network_source`	Ad network source for attribution	facebook
`ad_network_id`	Ad network campaign/account ID	camp_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.

Providing consent_date preserves the original opt-in date for contacts you collected outside of Trackly (e.g. migrated from another platform or a legacy form). This is part of the TCPA consent evidence trail — see Opt-In Tool Data & Retention for how Trackly records consent for opt-ins captured through the platform.

Example CSV

phone_number,first_name,last_name,email,consent_date
+14155551234,John,Doe,john@example.com,2025-01-15
+14155551235,Jane,Smith,jane@example.com,2025-03-22
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:

Input	Normalized
`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:

Scenario	Behavior
Contact exists on this list	Custom fields are merged (new values override)
Contact exists on different list	Added to this list with specified custom fields
Contact previously opted-out	Skipped (opt-out is permanent)
New contact	Created and subscribed

Import Limits

CSV imports through the dashboard accept up to 1,000,000 rows and 250MB per file. The bulk contacts endpoint (POST /v2/contacts/bulk) accepts up to 1,000 contacts per request.

Import Validation

Each contact is validated during import:

Validation Rules

Rule	Invalid Example	Result
Valid phone format	`abc123`	Error
Number length	`415555`	Error
Landline numbers	Landline detected	Stored (VOIP/landline blocking is a separate OTP delivery setting, on by default)
Not unsubscribed on this list	Previously opted out	Skipped

The import itself only skips contacts who are already unsubscribed on this list. Other delivery blocks — carrier rejections and STOP replies recorded against your sending number — are enforced when you send, not at import time.

Import Report

After import, you receive a report showing:

Import Complete
---------------
Total rows:            10,000
Created (new):          9,280
Updated (existing):       243
Duplicate (already on list, or repeated in file):  45
Skipped (opted-out):      198
Error (invalid row):      234

skipped counts only active opt-out refusals. duplicate covers both in-file repeats and the race-condition case where a concurrent importer already added the contact to this list between your upload and ours.

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. Enrollment is skipped if the contact previously opted out with a keyword such as STOP — that carrier-level block clears only when they text START — and, unless you send skip_journey_if_exists: false, if the contact is already in an active journey.

Best Practices

Validate before importing

Clean your CSV before importing. Remove obviously invalid numbers and test a small batch first.

Use consistent custom field naming

Establish custom field naming conventions (e.g., source, campaign, cohort) and use them consistently across imports.

Include source custom fields

Always include a source custom field indicating where contacts came from. This helps with attribution and analysis.

Don't re-import opted-out contacts

Opted-out contacts cannot be resubscribed via import. This is by design for compliance.

Troubleshooting

Import stuck at 0%

Large imports can take time to start. Wait a few minutes. If still stuck, check file encoding (use UTF-8).

High skip rate

Check the report — rows land in different buckets. Invalid phone format and bad number length are counted as errors, not skips; skipped rows are contacts already unsubscribed on this list. Landlines are never skipped — they import like any other number.

Custom fields not appearing

Ensure custom fields are passed in the custom_fields object when using the API. See the API reference for the correct format.

Wrong country code

If numbers are non-US, include the full E.164 format with country code in the CSV.

Common Pitfalls

Why are rows failing during import?

Common causes for import row failures:

Phone number format: Numbers are normalized automatically — a 10-digit number is given a +1 prefix, and any other digit string is given a leading +. Only numbers that still don’t match E.164 format after that 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: CSV imports support up to 1,000,000 rows and 250MB per file.

Next Steps

Custom Fields

Organize imported contacts

Audiences

Segment your contacts

Journeys

Automate onboarding

Getting Started

AI Agents & MCP

Guides

Account & Team

Integrations

Resources

CSV Format

Required Column

Optional Columns

Example CSV

Import Process

Phone Number Normalization

Duplicate Handling

Import Limits

Import Validation

Validation Rules

Import Report

Triggering Welcome Journeys

Best Practices

Troubleshooting

Common Pitfalls

Next Steps

Custom Fields

Audiences

Journeys

​CSV Format

​Required Column

​Optional Columns

​Example CSV

​Import Process

​Phone Number Normalization

​Duplicate Handling

​Import Limits

​Import Validation

​Validation Rules

​Import Report

​Triggering Welcome Journeys

​Best Practices

​Troubleshooting

​Common Pitfalls

​Next Steps

Custom Fields

Audiences

Journeys

CSV Format

Required Column

Optional Columns

Example CSV

Import Process

Phone Number Normalization

Duplicate Handling

Import Limits

Import Validation

Validation Rules

Import Report

Triggering Welcome Journeys

Best Practices

Troubleshooting

Common Pitfalls

Next Steps