Upload Lists & Lead Management

Prepare, upload, and manage lead lists for your Vicidial campaigns

Create a New List

Admin → Lists → Add a New List

List ID — Unique numeric identifier (e.g., 1001, 2001). Used to reference the list in campaigns.
List Name — Descriptive name (e.g., "Q1 Sales Leads", "Survey Contacts Jan 2025").
Campaign ID — Assign the list to a campaign. Required for the list to be dialed.
Active — Set to Y to make leads available for dialing.

Prepare Your CSV File

File Format: CSV or TXT, pipe or tab delimited

Vicidial accepts CSV (comma-separated), TXT (tab-separated), or pipe-delimited (|) files.
The first row should NOT contain headers (unless configured otherwise in upload settings).
phone_number is the only strictly required field. All others are optional but recommended.
Remove all formatting from phone numbers: no dashes, parentheses, or spaces. Just digits.
Ensure file encoding is UTF-8 to avoid character issues.

Upload the Lead File

Admin → Lists → [Select List] → Load Leads

Navigate to the list you created and click "Load Leads" or "Upload Leads".
Select your prepared file using the file browser.
Choose the file layout/format that matches your column order.
Or use "Custom Fields Layout" to manually map each column.
Set the duplicate check settings (see below).
Click "Upload" and review the results summary.

Map Custom Fields (if needed)

Admin → Lists → Custom Fields

If your file has additional columns beyond the standard fields, create custom fields first.
Admin → Lists → [List] → Custom Fields → Add New Field.
Each custom field gets a name, type (TEXT, AREA, SELECT, DATE, etc.), and label.
Custom field data is stored in a separate table (custom_[list_id]) and displayed on the agent screen.

Standard CSV Field Reference

Field Name	Required	Description
`vendor_lead_code`	No	Unique external ID for the lead (from your CRM or source system)
`source_id`	No	Source/campaign identifier for tracking lead origin
`list_id`	No	Target list ID (overrides upload form selection if set)
`phone_code`	No	Country dialing code (e.g., 1 for US, 44 for UK)
`phone_number`	Yes	The phone number to dial (10 digits for US, no formatting)
`title`	No	Mr., Mrs., Ms., Dr., etc.
`first_name`	No	Contact first name
`middle_initial`	No	Middle initial
`last_name`	No	Contact last name
`address1`	No	Street address line 1
`address2`	No	Street address line 2
`address3`	No	Street address line 3
`city`	No	City
`state`	No	State/Province (2-letter code for US)
`province`	No	Province (international)
`postal_code`	No	ZIP/Postal code (used for timezone detection)
`country_code`	No	ISO country code (US, UK, CA, etc.)
`email`	No	Contact email address
`comments`	No	Notes or comments about the lead

Sample CSV Format

# Standard Vicidial CSV format (no header row)
# vendor_lead_code|source_id|list_id|phone_code|phone_number|title|first_name|...
CRM001||1001|1|2125551234|Mr|John||Smith|123 Main St|||New York|NY||10001|US|john@email.com|Hot lead
CRM002||1001|1|3105559876|Ms|Jane||Doe|456 Oak Ave|||Los Angeles|CA||90001|US|jane@email.com|Referral
CRM003||1001|1|7735554567||Robert||Johnson|789 Elm Rd|||Chicago|IL||60601|US||Cold list

Duplicate Checking Options

Option	Description
`DUPLIST`	Check for duplicates within the same list only. Fastest check.
`DUPCAMP`	Check against all lists in the same campaign. Prevents cross-list duplicates.
`DUPSYS`	Check across the entire system (all lists). Most thorough but slowest.
`DUPTITLEALTPHONELIST`	Check by title and alt phone within the list.
`DUPPHONE`	Check phone number only (no other field matching).

Lead Recycling & Callbacks

Lead recycling allows you to re-attempt leads that received certain dispositions (like No Answer or Busy). Configure in Campaign → Lead Recycling:

Status — Which disposition to recycle (NA, B, AM, etc.)
Attempt Delay — Minutes to wait before retrying (e.g., 60 for 1 hour)
Maximum Attempts — How many times to retry (e.g., 3 attempts)
Agent Callbacks — When agents set CALLBK disposition, they schedule a specific date/time callback assigned to themselves.
Anyone Callbacks — CBHold callbacks are returned to the next available agent.

DNC (Do Not Call) Management

Internal DNC — System-wide DNC list. Numbers added here are blocked across all campaigns.
Campaign DNC — Per-campaign DNC list. Numbers blocked only for the specific campaign.
Auto-DNC — When an agent sets a DNC disposition, the number is automatically added to the DNC list.
DNC Upload — Bulk upload DNC numbers from a file via Admin → DNC → Load DNC Numbers.
DNC Check — Numbers are checked against the DNC list before being loaded into the hopper.

List Hygiene Best Practices

Clean Before Upload: Remove invalid numbers, duplicates, and known DNC numbers before uploading. This saves dialer time and improves contact rates.

Include ZIP/Postal Codes: Postal codes enable accurate timezone detection, which is critical for local call time compliance (TCPA/CRTC regulations).

Compliance Warning: Always scrub your lists against the national DNC registry before uploading. Failing to do so can result in significant fines. Vicidial provides DNC checking but it is YOUR responsibility to ensure compliance.

Back to Vicidial Guide Campaign Setup Carrier Setup