Compliance with Do-Not-Call (DNC) regulations is essential for call centers and telemarketing operations to avoid legal penalties and ensure ethical calling practices. VICIdial, a leading open-source call center solution, provides an API function called add_dnc_phone API, which allows administrators and developers to add phone numbers to the system-wide DNC list dynamically.
Instead of manually adding numbers to the VICIdial DNC list via the admin panel, this API enables businesses to automate DNC updates, integrate with external compliance databases, and streamline the management of opt-out requests.
Why Use the add_dnc_phone API?
✅ Ensure compliance with federal and local DNC regulations
✅ Automate DNC number additions based on customer opt-outs
✅ Prevent agents from dialing numbers on the DNC list
✅ Reduce the risk of fines and legal consequences for unsolicited calls
✅ Integrate DNC management with CRM and opt-out request forms
In this tutorial, we will cover:
🔹 How the add_dnc_phone API works
🔹 How to configure and authenticate API access
🔹 How to construct and send API requests
🔹 Examples using a browser, cURL, and Postman
🔹 How to interpret API responses and troubleshoot errors
🔹 Best practices for using the add_dnc_phone API efficiently
Let’s get started! 🚀
Understanding the add_dnc_phone API Function
The add_dnc_phone API allows administrators to add a phone number to VICIdial’s system-wide Do-Not-Call (DNC) list, ensuring that agents and dialers do not call numbers that have opted out.
What Information Does the add_dnc_phone API Require?
✔ Phone Number – The number that needs to be added to the DNC list
✔ Campaign ID – (Optional) If the DNC restriction applies to a specific campaign
✔ Source – A custom identifier for tracking API calls
Common Use Cases for add_dnc_phone API
🔹 Customers opting out of calls through IVR or website forms
🔹 Updating the DNC list dynamically from external compliance databases
🔹 Preventing repeat calls to numbers that have requested removal
🔹 Automating DNC list management for compliance teams
🔹 Blocking high-risk numbers from outbound call campaigns
Step 1: Prerequisites for Using the API
Before using the add_dnc_phone API, ensure you have:
✅ VICIdial installed and configured
✅ An API-enabled user account with administrative permissions**
✅ A valid phone number to add to the DNC list
✅ VICIdial server access credentials
How to Enable API Access in VICIdial
1️⃣ Log in to the VICIdial Admin Panel
2️⃣ Navigate to Admin > Users
3️⃣ Select the user who will access the API
4️⃣ Set API Access to 1 (Enabled)
5️⃣ Set User Level to 8 or higher** (Admin-level access) 6️⃣ Add add_dnc_phoneto the **Allowed API Functions** (or set toALL`)
7️⃣ Click Save Changes
Now, your user is authorized to add phone numbers to the DNC list dynamically using the API.
Step 2: Constructing the API Request
The VICIdial API uses HTTP GET requests, meaning you can access it via a browser, cURL, or API tools like Postman.
Base API URL
🔹 Replace your-vicidial-server with your actual VICIdial instance.
Required Parameters for add_dnc_phone API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (add_dnc_phone) |
add_dnc_phone |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | DNCUpdate |
phone_number |
The phone number to add to the DNC list | 18005551234 |
campaign_id |
(Optional) Campaign ID for campaign-specific DNC lists | SALES_CAMPAIGN |
Step 3: Sending the API Request
Method 1: Adding a Number to the DNC List via a Web Browser
Simply enter the following URL in your browser (replace credentials accordingly):
🔹 Press Enter, and the API should add the phone number to the system-wide DNC list.
Method 2: Adding a Number to the DNC List via cURL (Command Line)
For developers, cURL is a convenient tool for making API requests. Use the following command:
🔹 This will return a confirmation message indicating the phone number has been added to the DNC list.
Method 3: Adding a Number to the DNC List via Postman
1️⃣ Open Postman
2️⃣ Set the request type to GET
3️⃣ Enter the API URL
4️⃣ Click Send
5️⃣ The response should display the confirmation message for the DNC update
Step 4: Understanding API Responses
If the request is successful, VICIdial returns a response confirming the phone number has been added to the DNC list:
Breaking Down the Response
| Response Value | Meaning |
|---|---|
SUCCESS |
The request was processed successfully |
18005551234 |
The phone number added to the DNC list |
Added to DNC List |
Confirmation message |
Step 5: Handling Errors & Troubleshooting
| Error Message | Cause | Solution |
|---|---|---|
ERROR: USER DOES NOT HAVE PERMISSION TO USE THIS FUNCTION |
Insufficient API permissions | Ensure user level is 8+ and API Access is enabled |
ERROR: INVALID USERNAME OR PASSWORD |
Wrong credentials | Verify API username and password |
ERROR: PHONE NUMBER NOT PROVIDED |
No phone number specified in request | Ensure phone_number parameter is included |
ERROR: NO FUNCTION SPECIFIED |
Missing function parameter | Ensure function=add_dnc_phone is included |
Step 6: Best Practices for Using the add_dnc_phone API
✅ Ensure customer opt-outs are processed immediately
✅ Automate DNC list updates by integrating with CRM systems
✅ Restrict API access to authorized users to prevent unauthorized additions
✅ Regularly review the DNC list for accuracy and compliance
✅ Implement logging mechanisms to track DNC updates
Conclusion
The add_dnc_phone API function is an essential tool for ensuring compliance with Do-Not-Call regulations dynamically in VICIdial. Whether you’re blocking high-risk numbers, integrating with external opt-out systems, or automating DNC list updates, this API provides a fast and efficient way to maintain compliance.
Feel free to contact us or simply start a live chat to get connected to one of our team members. Here is our contact information.
Calling from US: +1 954-990-0053
Email: office@callix.ai
