> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dncscrub.com/llms.txt
> Use this file to discover all available pages before exploring further.
# VICIdial
> Add DNCScrub TCPA and Do Not Call compliance scrubbing to your VICIdial lists and inbound DIDs
This integration filters your [VICIdial](https://www.vicidial.org) 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](https://www.vicidial.com/?page_id=7) 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.
In the VICIdial admin, create a new Settings Container with the container ID `DNCDOTCOM`.
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.
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
```ini DNCDOTCOM theme={null}
# 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:
```bash theme={null}
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). |
```ini DNCDOTCOM (inbound additions) theme={null}
INBOUND_FILTER => USADNC,PROJDNC,LITIGATOR,INVALID
INBOUND_CACHE => 0
```
### Point a DID at the filter
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.
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`):
```text theme={null}
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.
## Related
For batch cellphone filtering specifically, see VICIdial's `CELLPHONE_USA_TCPA_FCC_COMPLIANCE.txt` document.
## Support
* [DNCScrub API Documentation](/api-reference/overview)
* [VICIdial DNC.com Integration Guide](https://vicidial.org/docs/DNC-dot-COM_integration.txt)
* [Contact Support](mailto:support@dnc.com)