How to Import Leads into VICIdial

Why Lead Imports Matter for Your Dialer

Your vicidial dialer is only as effective as the leads feeding it. Importing leads into VICIdial correctly determines whether agents spend their shift talking to prospects or wrestling with formatting errors, duplicate records, and empty hoppers. A clean lead import process is the foundation of every successful outbound campaign.

Whether you are loading a few hundred records from a spreadsheet or millions from a data provider, VICIdial's list management system gives you the tools to organize, filter, and dial those leads efficiently. This guide covers the complete vicidial setup workflow for lead imports—from CSV preparation through list assignment and ongoing list hygiene.

Preparing Your CSV File

VICIdial accepts lead data through CSV (comma-separated values) files uploaded via the admin interface or loaded directly on the vicidial server. Before uploading, your file must follow VICIdial's expected column structure.

Required and Optional Columns

At minimum, every lead record needs a phone number. VICIdial expects phone numbers in a consistent format—typically 10 digits for US numbers without country code, or with a leading 1 for 11-digit format. Mixed formats in the same file cause import failures or dialing errors.

• phone_number — Required. The primary dialable number
• phone_code — Country code (default 1 for US/Canada)
• first_name, last_name — Agent-facing contact name fields
• email — Optional but useful for CRM integrations
• address1, city, state, postal_code — Geographic data for filtering and compliance
• vendor_lead_code — Your internal lead ID for tracking and deduplication
• source_id — Identifies the lead source (e.g., WEB_FORM, PURCHASED_LIST)
• Custom fields (field1 through fieldN) — Map to campaign-specific data like product interest or loan amount

Remove header rows that do not match VICIdial's expected field names, strip special characters from phone numbers, and validate that no cells contain embedded commas unless properly quoted. Excel users should save as CSV UTF-8 rather than standard CSV to avoid encoding issues with international characters.

Creating a Lead List in VICIdial

Before importing, create a list container in Admin → Lists → Add a New List. The list ID is a numeric identifier (e.g., 101, 102) that groups leads for a specific campaign or data source.

1. Navigate to Admin → Lists → Add a New List
2. Enter a unique List ID (numeric, typically 100–999999)
3. Set List Name to something descriptive (e.g., March 2025 Purchased Leads)
4. Set Campaign to the outbound campaign that will dial this list, or leave blank to assign later
5. Set Active to Y when ready for dialing
6. Configure List Description for internal reference
7. Set expiration date if the list has a limited usable life
8. Save the list record

You can assign multiple lists to a single campaign and control dialing priority through list order settings. For teams running multiple data sources, separate lists make it easy to compare performance by source in your real-time reports.

Uploading Leads via the Admin Interface

The web-based upload is the most common method for teams without direct server access. Navigate to Admin → Lists → Load Leads and select your target list.

Step-by-Step Upload Process

1. Select the target List ID from the dropdown
2. Choose your CSV file from your local machine
3. Map CSV columns to VICIdial fields if the upload tool presents a mapping screen
4. Set duplicate handling — choose whether to update existing records or skip duplicates
5. Select the phone number column and confirm the phone code
6. Click Upload and wait for the confirmation message
7. Review the import summary for rejected records and error counts

Large files (over 100,000 records) may time out in the browser. For bulk imports, use the command-line load_leads.pl script on the vicidial server, which handles millions of records efficiently. Managed vicidial hosting providers often offer assisted bulk imports as part of their vicidial support services—worth checking your vicidial pricing plan if you regularly load large files.

Custom Fields and Data Mapping

VICIdial supports custom fields that display on the agent screen during live calls. These fields let agents personalize conversations without searching external systems. Configure custom field labels in Admin → System Settings → Custom Fields, then map your CSV columns to the corresponding field numbers during import.

Common custom field uses include loan amount, product SKU, previous contact date, appointment time, and account number. Keep custom field data concise—agents read these on screen during calls, and walls of text slow them down. If you integrate with Salesforce or HubSpot, align your custom field names with CRM field mappings. See our Salesforce integration guide and HubSpot integration guide for field mapping best practices.

Teams that manage leads in Google Sheets can automate imports using our Google Sheets integration to push new records into VICIdial lists without manual CSV exports.

Duplicate Handling and DNC Management

Duplicate leads waste dial attempts and annoy prospects who receive multiple calls. VICIdial offers several mechanisms to prevent and manage duplicates across your lead database.

Deduplication Options

• Vendor Lead Code — VICIdial checks for matching vendor_lead_code values across lists
• Phone Number — Duplicate phone check prevents the same number from appearing in multiple active lists
• Hopper VLC Dup Check — Prevents duplicate entries in the outbound hopper during dialing
• Internal DNC List — System-wide do-not-call list that blocks numbers regardless of which list they appear in
• Campaign DNC — Campaign-specific DNC for numbers that should not be re-dialed within a particular campaign

Before importing purchased lead lists, scrub against the National DNC Registry and your internal DNC list. Importing callable leads that include DNC numbers creates compliance risk and damages your caller reputation. Our guide on avoiding spam labeling covers how list quality affects your outbound caller ID reputation.

Assigning Lists to Campaigns

An imported list does nothing until it is assigned to an active outbound campaign. In Admin → Campaigns → modify your campaign and scroll to the Lists section. Add your list ID, set its priority order, and confirm the list is marked Active.

After assignment, verify the hopper populates by checking Admin → Campaigns → Hopper List or the Real-Time Report. If the hopper remains empty, confirm the list has leads with a status of NEW and that lead filters are not excluding your records. Once lists are assigned, your outbound campaign configuration controls how aggressively those leads are dialed.

List Maintenance and Lead Recycling

Leads do not last forever. After initial dialing passes, many records remain in statuses like NA (no answer), BUSY, or AA (answering machine) that can be recycled for additional attempts. Effective list management separates fresh leads from recycled ones and prevents over-dialing.

Create separate lists or use lead status filters to control recycling cadence. Our detailed guide on lead recycling best practices walks through optimal retry intervals, maximum attempt limits, and how to re-queue leads without burning your data. Review list performance weekly and archive or deactivate lists that have exhausted their useful life.

Troubleshooting Import Errors

Upload Times Out or Fails

Browser uploads fail on large files due to PHP upload limits or web server timeouts. Increase upload_max_filesize and post_max_size in PHP configuration, or switch to the command-line load_leads.pl script on the vicidial server. If you use managed vicidial hosting, ask your provider to run the import server-side.

Leads Imported But Not Dialing

Confirm the list is Active, assigned to an active campaign, and leads have a status of NEW. Check that Local Call Time permits dialing in the lead's area code. Verify the hopper is loading leads—manually reload if needed. Empty hoppers with callable leads usually indicate a list assignment or filter misconfiguration.

Garbled Characters or Encoding Issues

Save your CSV as UTF-8 encoding. Excel on Windows defaults to ANSI encoding, which corrupts accented characters and international names. Use Google Sheets or LibreOffice to export UTF-8 CSV files if Excel causes persistent encoding problems.

High Volume of Duplicate Phone Rejections

This is usually working as intended—VICIdial is preventing duplicate numbers from entering the database. Review your source data for duplicate phone numbers before import. If you intentionally want to update existing records, change the duplicate handling setting to UPDATE rather than SKIP during upload.

Conclusion

Importing leads into VICIdial is a repeatable process that becomes second nature once your templates and workflows are established. Clean CSV data, properly configured lists, and disciplined duplicate handling keep your vicidial dialer fed with callable prospects. Pair solid list management with thoughtful outbound campaign settings and reliable SIP carrier configuration for a complete dialing operation.

Whether you manage imports yourself or rely on vicidial hosting with assisted data loading, invest in list quality over list quantity. A smaller, verified list outperforms a massive unscrubbed file every time. For hands-on help with bulk imports or custom field mapping, contact your vicidial support provider with a sample CSV and your target campaign ID.