VICIdial

This integration filters your VICIdial lists against state, federal (FTC), and internal DNC lists, as well as TCPA and Litigator scrub — directly through your DNC.com account. It works in two modes: batch outbound list filtering that updates lead statuses before you dial, and inbound DID filtering that screens calls coming in through DIDs on your system.

DNC.com offers VICIdial users a free 15-day trial of real-time integrated TCPA and DNC Safe Harbor lead scrubbing. Contact VICIdial for details on the free offer.

Prerequisites

A VICIdial system with command-line (CLI) access to one of your dialers
A DNCScrub account with API access — your Login ID (API ID) and, optionally, a Project ID or Campaign ID
Permission to create a Settings Container and edit DID entries in the VICIdial admin

Step 1: Create the Settings Container

Both the outbound and inbound filters read their configuration from a single VICIdial Settings Container with the ID DNCDOTCOM. Create it once and customize it for your DNC.com account.

Add the container

In the VICIdial admin, create a new Settings Container with the container ID DNCDOTCOM.

Enter your account and connection settings

Add your DNC.com credentials and connection options (see the table below). At minimum, set your LOGIN_ID and the lists you want to scrub.

Map the result codes to statuses

Set each STATUS_* option to the VICIdial status you want a number to receive when DNC.com returns that result code.

Connection and account settings

Setting	Description
`DNC_DOT_COM_URL`	The DNC.com API endpoint. You should not need to change `http://www.dncscrub.com/app/main/rpc/scrub` unless DNC.com changes their API.
`LOGIN_ID`	Your DNC.com API ID.
`PROJ_ID`	The project whose scrub settings to use. If both `PROJ_ID` and `CAMPAIGN_ID` are omitted, the Master Project is used.
`CAMPAIGN_ID`	The campaign to scrub in. If specified, you may omit `PROJ_ID`. If omitted, the Default Campaign of `PROJ_ID` (or of your Master Project) is used.
`VERSION`	A value of `2`+ enables Version 2.0 features; `3`+ enables Version 3.0 features, which add result code `Y` for VoIP. With versions below 3, VoIP numbers return as `W` (when VoIP scrubbing is enabled).
`VICI_LISTS`	The list IDs to scrub, separated by a hyphen — for example `105-106`.
`VICI_STATUS_SKIP`	Statuses within those lists to skip, separated by a hyphen — for example `SALE-DNC`.
`ADD_INFO_TO_COMMENTS`	`YES` or `NO`. When `YES`, the `vicidial_list` comments field is overwritten with extra DNC.com fields (DateField, Reason, RegionAbbrev, etc.), comma separated.

Example Settings Container

DNCDOTCOM

# Connection
DNC_DOT_COM_URL => http://www.dncscrub.com/app/main/rpc/scrub
LOGIN_ID        => 1234567890QWERTYUIOP1234567890QWERTYUIOP
PROJ_ID         =>
CAMPAIGN_ID     =>
VERSION         => 3

# Lists to scrub and statuses to skip
VICI_LISTS       => 105-106
VICI_STATUS_SKIP => SALE-DNC

# Result-code to status mappings (see table below)
STATUS_X => XDNCCM
STATUS_C => CDNCCM
STATUS_O => ODNCCM
STATUS_E => EDNCCM
STATUS_R => RDNCCM
STATUS_W => WDNCCM
STATUS_G => GDNCCM
STATUS_H => HDNCCM
STATUS_L => LDNCCM
STATUS_F => FDNCCM
STATUS_V => VDNCCM
STATUS_I => IDNCCM
STATUS_M => MDNCCM
STATUS_B => BDNCCM
STATUS_P => PDNCCM
STATUS_D => DDNCCM
STATUS_S => SDNCCM
STATUS_T => TDNCCM
STATUS_Y => YDNCCM

# Overwrite the comments field with extra DNC.com detail (YES/NO)
ADD_INFO_TO_COMMENTS => NO

Result codes

When DNC.com scrubs a number, it returns a result code. Each STATUS_* setting controls the VICIdial status the lead is updated to for that code. The defaults above (*DNCCM) are examples — set them to whatever fits your dial plan.

Code	Setting	Meaning
`X`	`STATUS_X`	Industry eXemption applied to an otherwise Do Not Call number — number can be called
`C`	`STATUS_C`	Clean number — can be called
`O`	`STATUS_O`	EBR Override applied to an otherwise Do Not Call number (including an explicit EBR overriding a number in Project DNC) — number can be called
`E`	`STATUS_E`	Valid EBR, currently valid, not on a Do Not Call list — number can be called
`R`	`STATUS_R`	Expired EBR — formerly a valid EBR, not on a Do Not Call list; number can be called (this result code will be available in the near future)
`W`	`STATUS_W`	US Wireless number — not in any DNC database (or overridden by an industry exemption), but cannot be called from a predictive dialer
`G`	`STATUS_G`	Valid EBR and US Wireless or VoIP number, not on any DNC database (v2+) — still cannot be called from a predictive dialer, as EBRs are not an exemption to those rules
`H`	`STATUS_H`	US Wireless or VoIP number that is also a valid EBR overriding an otherwise DNC number (v2+) — still cannot be called from a predictive dialer
`L`	`STATUS_L`	Wireless number in a US state that does not allow telemarketing to wireless numbers even if manually dialed; not on any DNC list and not an EBR (v2+)
`F`	`STATUS_F`	Valid EBR and wireless number in a US state that does not allow telemarketing to wireless numbers even if manually dialed; not on any DNC list (v2+)
`V`	`STATUS_V`	Valid EBR overriding an otherwise DNC number that is also a wireless number in a US state that does not allow telemarketing to wireless even if manually dialed (WY, NJ, TX, LA, AZ) (v2+)
`I`	`STATUS_I`	Invalid — area code not active, or reserved/special-use phone number pattern (e.g. `555-5555`)
`M`	`STATUS_M`	Malformed — number is not 10 digits, etc. (this typically returns an error response instead of this code)
`B`	`STATUS_B`	Blocked — number is in an area code not covered by the project’s National Subscription, a configured no-call area code, or no exemption was available in a pre-recorded call campaign
`P`	`STATUS_P`	Project DNC or DNF (Do Not Fax) database match (no further checks are performed)
`D`	`STATUS_D`	Do Not Call database match; the Reason field provides additional detail
`S`	`STATUS_S`	Disconnected — number matched a disconnected-numbers database (future service)
`T`	`STATUS_T`	Tier C phone company (call may be more expensive) (future service)
`Y`	`STATUS_Y`	VoIP number not in any DNC database (or overridden by an industry exemption). Returned only when `VERSION => 3` and the project has VoIP scrubbing enabled; otherwise such numbers return as `W`

Step 2: Run Outbound List Filtering

Outbound filtering runs in batch mode against lists that are already loaded on your system. It does not look up numbers as they are dialed. Run the filter script from the Linux command line, passing the lists to scrub:

AST_DNCcom_filter.pl --lists=LISTID1-LISTID2

Schedule it from the crontab of one of your dialers. Run it after-hours, or only during calling hours on inactive lists, to avoid scrubbing leads that are actively being dialed.

The --lists argument and the VICI_LISTS setting both identify lists with IDs separated by a hyphen (for example 105-106).

Step 3: Configure Inbound DID Filtering

A separate script, DNCcom_inbound_filter.php, screens calls coming in through your DIDs. It uses the same DNCDOTCOM Settings Container, plus two inbound-specific options.

Inbound settings

Setting	Description
`INBOUND_FILTER`	A comma-separated list of what to block: `USADNC` (federal DNC numbers), `PROJDNC` (internal project DNC numbers), `LITIGATOR` (the litigator list, if subscribed), and `INVALID` (invalid numbers).
`INBOUND_CACHE`	Number of days of recent DNC.com query results to search before making a new request, to reduce redundant lookups. Default is `0` (disabled).

DNCDOTCOM (inbound additions)

INBOUND_FILTER => USADNC,PROJDNC,LITIGATOR,INVALID
INBOUND_CACHE  => 0

Point a DID at the filter

Set the inbound filter to URL

On the DID entry, set Filter Inbound Number to URL. For a system-wide filter, use the did_system_filter DID entry, reached from the link on the Admin → System Settings page.

Enter the Filter URL

Set the DID’s Filter URL to point at the inbound filter script on your webserver. Replace the IP with the local address your dialers use to reach the webserver (the example below assumes 192.168.1.3):

http://192.168.1.3/vicidial/DNCcom_inbound_filter.php?phone=--A--phone_number--B--

If you receive calls from North America, set the DID option Clean CID Number to R10 so numbers are always looked up as proper 10-digit values.

For batch cellphone filtering specifically, see VICIdial’s CELLPHONE_USA_TCPA_FCC_COMPLIANCE.txt document.

Integrations

Prerequisites

Step 1: Create the Settings Container

Connection and account settings

Example Settings Container

Result codes

Step 2: Run Outbound List Filtering

Step 3: Configure Inbound DID Filtering

Inbound settings

Point a DID at the filter

Support

​Prerequisites

​Step 1: Create the Settings Container

​Connection and account settings

​Example Settings Container

​Result codes

​Step 2: Run Outbound List Filtering

​Step 3: Configure Inbound DID Filtering

​Inbound settings

​Point a DID at the filter

​Related

​Support

Prerequisites

Step 1: Create the Settings Container

Connection and account settings

Example Settings Container

Result codes

Step 2: Run Outbound List Filtering

Step 3: Configure Inbound DID Filtering

Inbound settings

Point a DID at the filter

Related

Support