Removing a number from DNC with delete_dnc_phone

Sometimes a number lands on the block list when it should not have - a typo, a wrong customer record, a callback request that came in after the opt-out was logged. The Non-Agent API gives you delete_dnc_phone to take a number back off a DNC list without hunting through the admin screens.

What delete_dnc_phone does

It removes a phone number from a DNC list. A DNC (do not call) entry blocks future dials, so deleting it makes that number callable again. You pick the list the same way you do when adding: a real campaign_id targets that campaign's Campaign DNC list, and SYSTEM_INTERNAL targets the shared Internal DNC list every campaign reads from.

Be deliberate here. Pulling a number off a [[dnc-list]] means the dialer can call it again, so only delete entries you are certain were added in error. A real opt-out from a DNC litigator belongs on the list.

Permissions you need first

Deletion asks for one more grant than adding. The API user must have user_level 8 or higher, the "modify lists" permission, and also "Delete From DNC Lists" enabled. That third flag is a deliberate guardrail - VICIdial does not want a routine list-editing account quietly un-blocking opted-out numbers. If you have ever locked down the API account, the steps are in how to secure the VICIdial API.

The required fields

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

Example call

Remove a number from one campaign's DNC list:

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

Remove it from the internal list instead:

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

How the call decides

flowchart TD
    A[delete_dnc_phone call] --> B{user_level 8 and Delete From DNC?}
    B -->|no| C[ERROR: NO PERMISSION]
    B -->|yes| D{number on this DNC list?}
    D -->|no| E[ERROR: DNC NUMBER DOES NOT EXIST]
    D -->|yes| F[remove DNC row]
    F --> G[SUCCESS: DNC NUMBER HAS BEEN DELETED]

Reading the response

A successful delete returns: SUCCESS: delete_dnc_phone DNC NUMBER HAS BEEN DELETED - 6666|7275551212|TESTCAMP. The errors to watch for:

• ERROR: delete_dnc_phone USER DOES NOT HAVE PERMISSION TO DELETE DNC NUMBERS - 6666|0 - the account is missing user_level 8, "modify lists", or "Delete From DNC Lists".
• ERROR: delete_dnc_phone YOU MUST USE ALL REQUIRED FIELDS - 6666|||1000 - phone_number or campaign_id is missing.
• ERROR: delete_dnc_phone DNC NUMBER DOES NOT EXIST - 6666|7275551212 - the number was not on that list to begin with, so check the campaign_id you sent.

The mirror function for putting numbers on the list is covered in adding a number to the DNC list with add_dnc_phone.

Run it on a hosted box

The API (application programming interface) ships with every VICIdial install, so delete_dnc_phone is ready the moment your dialer is up. VICIfast runs the API for you on every plan - see pricing.