Upload Lists & Lead Management

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

1

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.
2

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.
3

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.
4

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 NameRequiredDescription
vendor_lead_codeNoUnique external ID for the lead (from your CRM or source system)
source_idNoSource/campaign identifier for tracking lead origin
list_idNoTarget list ID (overrides upload form selection if set)
phone_codeNoCountry dialing code (e.g., 1 for US, 44 for UK)
phone_numberYesThe phone number to dial (10 digits for US, no formatting)
titleNoMr., Mrs., Ms., Dr., etc.
first_nameNoContact first name
middle_initialNoMiddle initial
last_nameNoContact last name
address1NoStreet address line 1
address2NoStreet address line 2
address3NoStreet address line 3
cityNoCity
stateNoState/Province (2-letter code for US)
provinceNoProvince (international)
postal_codeNoZIP/Postal code (used for timezone detection)
country_codeNoISO country code (US, UK, CA, etc.)
emailNoContact email address
commentsNoNotes 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

OptionDescription
DUPLISTCheck for duplicates within the same list only. Fastest check.
DUPCAMPCheck against all lists in the same campaign. Prevents cross-list duplicates.
DUPSYSCheck across the entire system (all lists). Most thorough but slowest.
DUPTITLEALTPHONELISTCheck by title and alt phone within the list.
DUPPHONECheck 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