How to upload and load a country DNC list in bulk

Loading a country-level DNC list into VICIdial requires more than dropping a file somewhere on the server. The International DNC Loader provides a structured workflow: you upload the file, configure three parameters, and then trigger processing through the admin interface. The background script handles the actual ingestion. This walkthrough covers each step in order so the file ends up correctly loaded in the right country's suppression table.

Before you start

Confirm that the "Enable International DNC" system setting is turned on. If it is off, none of the processing steps will have any effect — uploaded files will sit in the queue indefinitely. Also confirm that you know which country the file covers and which file layout format it follows. You will need both pieces of information at step four. If you are unsure about the file format, check the DNC_IMPORT_FORMATS settings container before proceeding — if your format is not listed there, add it first, otherwise the file cannot be processed correctly.

The upload and configuration flow

flowchart TD
  A[Obtain DNC file from provider] --> B[Upload file via International DNC Loader page]
  B --> C[File appears in queue with READY status]
  C --> D[Select DNC country code]
  D --> E[Select DNC file action: PURGE or APPEND]
  E --> F[Select DNC file layout format]
  F --> G[Click START FILE]
  G --> H[Status changes to PENDING]
  H --> I[Background script picks up file]
  I --> J[Numbers loaded into country DNC table]
  J --> K[Status changes to finished]

Step by step

1. Open the International DNC Loader from the VICIdial admin panel. The page shows the current file queue table with status for each entry.
2. Upload your DNC file. Once uploaded, it appears in the queue with a READY status, meaning it is waiting for configuration before processing begins.
3. Set the DNC country code. This field lists countries pulled from the vicidial_country_iso_tld table in the database. Pick the country that matches the suppression list you uploaded. Every number in the file will be stored under this country's table.
4. Set the DNC file action to either PURGE or APPEND. PURGE replaces all existing records for that country's DNC table with the contents of the new file. APPEND adds distinct new numbers to the existing records without removing anything already there. If this is the first file you have ever loaded for this country, both options produce the same result.
5. Set the DNC file layout. This tells the processing script what format the file is in and where to look inside each row for the phone number. The available formats come from the DNC_IMPORT_FORMATS settings container. If your file format is not listed, it needs to be added to that container first.
6. Click the START FILE button. This changes the file's status to PENDING. The automated background script detects PENDING files, processes them, and updates the status to finished when done.
7. Monitor progress on the same page. The queue display updates as the background script works through the file. A finished status confirms the numbers are now in the country's DNC suppression table.

What happens if you need to cancel

If a file is still in a READY state and you have not yet pressed START FILE, you can cancel it. Clicking CANCEL sets the file status to CANCELLED. The background script will then purge it from the queue table and remove it from the DNC storage folder. Once a file is PENDING or finished, the cancel path no longer applies. If you realize a mistake after processing has started, you will need to load a corrected file — either with PURGE to replace the bad data, or by removing the wrong entries through another method.

Confirming the load was successful

After the status shows finished, the numbers from the file are now stored in the country's suppression table. From this point, any Lead imported through the lead loader that matches a number in that table will be suppressed. The scrub runs at import time, not at dial time, so leads that were already in the Campaign before the DNC file was loaded will not be retroactively removed from the dialer hopper. If you need to clean previously imported leads, run a separate suppression pass using the lead management tools.

When you need to decide between PURGE and APPEND, see when to use PURGE vs APPEND for an international DNC file. For the broader context of how this tool fits into VICIdial admin batch operations, read our VICIdial admin bulk tools guide. The TCPA implications of calling numbers on a country DNC list make this step non-optional for compliant international campaigns.

Want a hosted dialer where international DNC scrubbing works from day one? See VICIfast pricing - you can be live in under 40 seconds.