Importing leads into VICIdial - CSV format

VICIdial accepts leads as CSV. Here's the working format + the gotchas we get asked about most.

Minimum required columns

phone_number

That's it. Everything else is optional. Phone numbers should be numeric digits, no formatting. Country codes prefix is fine - 15555551234 for a US number.

Recommended columns

phone_number,first_name,last_name,address1,city,state,postal_code,email,custom_id
15555551234,Tom,Smith,123 Main St,Boston,MA,02108,tom@example.com,LEAD-12345

VICIdial maps these to its standard columns automatically. custom_id is your internal id - store anything you want here for later joins.

Where to upload

VICIdial admin → Admin → Lists → List Loader (the bulk loader).

1. Pick or create a list (lists are scoped to a campaign).
2. Pick a phone code default (country prefix to apply to leads with no + prefix). For US, 1.
3. Upload the CSV.
4. Choose duplicate handling: skip / overwrite / load anyway.

Custom fields

If you have data fields VICIdial's standard schema doesn't have, use Admin → Custom Fields to add them per-list. Reference them in scripts and dial plans via {custom_field_name}.

DNC + suppression

Before going live, build your suppression. Two layers:

1. Federal/State DNC - VICIdial has a built-in DNC list (vicidial_dnc). Load it via Admin → Lists → DNC List. The standard US DNC is downloadable from telemarketing.donotcall.gov.
2. Internal DNC - your own opt-out list. Enable per-campaign with DNC=Y.

For state-level lists (NY, FL, etc.), maintain separately and load before each campaign.

TCPA gotchas

This is not legal advice. But the patterns we see customers run into:

• Calling time windows - VICIdial's Local Call Time restricts when each lead's local clock allows dialing. Set this; it's how you stay on the right side of the FTC.
• Reassigned-numbers database - the FCC RND. If you make a TCPA-regulated call, this is now mandatory before you dial. There are commercial services that pre-clean lists against it.
• Opt-out tracking - every campaign needs a way to mark a contact as "stop calling" that updates the lead in real time. VICIdial does this via the Hotkey Form.

For what the statute requires, read TCPA compliance for outbound dialing. For the VICIdial fields that enforce it, read VICIdial settings for TCPA compliance.

Duplicate strategies

Three options when the loader sees a phone number that already exists in any list:

• Skip - don't load the row. Use for ongoing imports where leads might re-appear.
• Overwrite - replace the existing lead. Use when you have a fresh dump and want it to win.
• Load anyway - load as a new row. Useful when the same number can have multiple leads (e.g. a household).

Big lists

For lists over ~100k leads, upload via SCP rather than the web UI to avoid PHP upload-size limits, then use the CLI loader (/usr/share/astguiclient/ADMIN_lead_loader.pl).

Testing the load

Before kicking off a campaign on a fresh list:

1. Sort by vendor_lead_code and check a few rows look right.
2. Filter status=NEW and confirm count matches what you uploaded.
3. Run a 5-lead test campaign with one agent against it.