Skip to main content
Import large numbers of leads at once using CSV or Excel files. The import system validates each row, processes large files in the background, and generates a detailed error report for any rows that fail.

​
What the importer supports

  • CSV (.csv) and Excel (.xlsx, .xls) files
  • Background processing for large files
  • Automatic validation with error reporting
  • Secondary contacts included in the same file
  • Variable column mapping from your assistant’s configuration

​
Preparing your import file

​
Required columns

ColumnDescription
phone_numberPrimary contact phone number (required)
Variable columnsOne column per variable configured on your assistant

​
Optional columns

  • Additional phone number columns for secondary contacts (e.g., secondary_phone_1, secondary_phone_2)
  • Secondary contact variable columns (e.g., secondary_1_name, secondary_1_role)

​
File format example

phone_number,customer_name,company,budget_range,secondary_phone_1,secondary_phone_2
+14155551234,John Smith,ABC Corp,10k-50k,+14155551235,+14155551236
+14155557890,Jane Doe,XYZ Inc,50k-100k,+14155557891,
+14155554567,Bob Johnson,Tech Start,5k-10k,,

​
Phone number formats

​
Import steps

1

Start the import

  1. Navigate to the Leads section or a campaign’s leads tab.
  2. Click Import Leads.
  3. Select the campaign to assign the leads to.
  4. Optionally download the sample file to see the expected format.
2

Configure import settings

Before uploading your file, set these options:Secondary contacts — Select how many secondary phone numbers per lead (0–10) are included in your file.Phone number format — Choose International or National format. If National, select the country code.
3

Upload your file and map columns

  1. Select your CSV or Excel file.
  2. Map your file’s columns to system fields:
    • Phone number (required) — Select the column with primary phone numbers
    • Assistant variables — Map each variable to the corresponding column
    • Secondary contacts — If configured, map secondary phone number and variable columns
  3. The system auto-detects mappings based on common header names. Review and adjust as needed.
  4. Click Import to begin processing.
4

Monitor and review results

For large files, processing runs in the background. You will receive an email notification when the import completes.The notification includes:
  • Number of leads successfully imported
  • Count and details of any failed rows
  • A download link for the error report

​
Validation rules

​
Phone numbers

  • International format is preferred (+1234567890)
  • Duplicate phone numbers are detected and prevented
  • Invalid or impossible numbers are flagged and skipped

​
Variables

  • Variables marked as required must have values
  • Text, number, and boolean fields are validated for correct data type
  • Maximum character limits are enforced

​
Secondary contacts

  • Same phone number format validation as primary numbers
  • Secondary numbers must differ from the primary number
  • Each secondary contact’s variables are validated independently

​
Error handling

The import system is designed for partial success — valid rows are always imported, and invalid rows are reported without blocking the rest.
OutcomeWhat happens
Valid rowLead is added to the campaign
Invalid rowSkipped and added to the error report
Import completeEmail notification sent with summary

​
Downloading the error report

After import, download the error report from the notification or the import history. The report includes:
  • The original row data
  • A description of each validation error
  • Guidance for correcting the issue
You can fix the errors in your file and re-import the corrected rows.

​
Common errors

ErrorCause
Invalid phone numberIncorrect format or an impossible number
Missing required fieldA required variable column is empty
Duplicate phone numberThis number already exists in the system
File format issueCorrupted file or unsupported format

​
Secondary contacts in your file

​
Multiple phone numbers per lead

Add secondary contact phone number columns after your primary number and variables: 
phone_number,customer_name,secondary_phone_1,secondary_phone_2,secondary_phone_3
+14155551234,John Smith,+14155551235,+14155551236,+14155551237

​
Secondary contact variables

Add variable columns alongside secondary phone numbers: 
phone_number,customer_name,secondary_phone_1,secondary_1_name,secondary_1_role
+14155551234,John Smith,+14155551235,Jane Smith,Decision Maker
Contacts are called in column order — secondary_phone_1 is tried before secondary_phone_2, and so on.

​
Processing times for large files

File sizeTypical processing time
< 100 rowsUnder 1 minute
100–1,000 rows2–5 minutes
1,000+ rows10–30 minutes
10,000+ rowsMay take several hours
Large files are queued automatically and processed in the background without affecting platform performance.

​
Best practices

  • Download the sample file — Use the provided template to ensure your file matches the expected format before importing.
  • Test with a small batch — Start with 5–10 rows to confirm column mappings and variable values are correct before importing your full list.
  • Use international format — Phone numbers in +country_code_number format (no spaces or separators) avoid the most common import errors.
  • Clean your data — Remove empty rows, fix encoding issues, and validate phone numbers before uploading.
  • Match your assistant’s variables — Make sure your column headers align with the variable names configured on the campaign’s assistant.

​
Next steps