How to add a number to the DNC list with add_dnc_phone

When a customer asks to be taken off your call list, you need that number blocked before the next dial pass runs. Clicking through the admin screen works, but if the request arrives from your own CRM or a web form, it is easier to push the number straight in with an API call. The Non-Agent API exposes a function named add_dnc_phone that does exactly this.

What add_dnc_phone does

This function adds a phone number to a DNC list. A DNC (do not call) (Do-Not-Call) entry tells VICIdial to skip that number on future dial attempts. You choose which list it lands on with the campaign_id field: pass a real campaign ID and it goes onto that campaign's Campaign DNC list, or pass the literal value SYSTEM_INTERNAL to put it on the shared Internal DNC list that every campaign honors.

This matters for TCPA compliance. Litigators count on dialers that keep calling after an opt-out, so getting numbers onto a DNC list quickly is the cheapest insurance you can buy.

Permissions you need first

The API user you authenticate with must have a user_level of 8 or higher and the "modify lists" permission enabled. If either is missing, the call is rejected before it touches the database. Permission tuning is covered in VICIdial API user level and permissions.

The required fields

• phone_number — the number to block, 6 to 20 characters
• campaign_id — 2 to 30 characters, a valid campaign ID, or SYSTEM_INTERNAL for the shared internal DNC list

Example call

To drop a number onto a single campaign's DNC list:

http://your-server/vicidial/non_agent_api.php?source=test&function=add_dnc_phone&user=6666&pass=1234&phone_number=7275551212&campaign_id=TESTCAMP

To block it everywhere, use the internal list instead:

http://your-server/vicidial/non_agent_api.php?source=test&function=add_dnc_phone&user=6666&pass=1234&phone_number=7275551212&campaign_id=SYSTEM_INTERNAL

How the call flows

sequenceDiagram
    participant C as Your CRM
    participant API as non_agent_api.php
    participant DB as VICIdial DB
    C->>API: add_dnc_phone (number, campaign_id)
    API->>API: check user_level and modify lists
    API->>DB: number already on this DNC list?
    DB-->>API: no
    API->>DB: insert DNC row
    API-->>C: SUCCESS: DNC NUMBER HAS BEEN ADDED

Reading the response

A clean add returns: SUCCESS: add_dnc_phone DNC NUMBER HAS BEEN ADDED - 6666|7275551212|TESTCAMP. The trailing pipe-delimited values echo back your API user, the number, and the campaign so you can log the result.

The errors you are most likely to hit:

• ERROR: add_dnc_phone USER DOES NOT HAVE PERMISSION TO ADD DNC NUMBERS - 6666|0 — the API user is missing user_level 8 or "modify lists".
• ERROR: add_dnc_phone YOU MUST USE ALL REQUIRED FIELDS - 6666|||1000 — you left out phone_number or campaign_id.
• ERROR: add_dnc_phone DNC NUMBER ALREADY EXISTS - 6666|7275551212 — the number is already on that list, so nothing changed.

Note that the ALREADY EXISTS message is a safe outcome, not a failure — the number you wanted blocked is blocked. Treat it as success in your integration logic. Parsing these strings is its own small art, covered in how to read VICIdial API responses.

Run it on a hosted box

The Non-agent API is part of every standard VICIdial install, so add_dnc_phone is available out of the box. VICIfast runs the API for you on every plan, with the permissions screen already in reach — see pricing.