Call centers need to ensure phone number validity before dialing to improve agent efficiency, reduce call failures, and optimize lead conversion rates. VICIdial, a powerful open-source call center solution, provides the check_phone_number API, which allows administrators and developers to verify whether a phone number is dialable before adding it to a campaign.
The check_phone_number API helps call centers by preventing bad data from entering dialing lists, avoiding wasted calls on do-not-call (DNC) numbers, blacklisted numbers, or improperly formatted numbers.
Why Use the check_phone_number API?
✅ Validate phone numbers before dialing to reduce call failures
✅ Ensure compliance by checking numbers against DNC lists
✅ Improve lead quality by filtering out invalid or blacklisted numbers
✅ Optimize campaign efficiency by focusing only on valid contacts
✅ Automate lead validation and filtering processes
In this tutorial, we will cover:
🔹 How the check_phone_number 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 check_phone_number API efficiently
Let’s get started! 🚀
Understanding the check_phone_number API Function
The check_phone_number API allows users to verify if a phone number can be dialed based on VICIdial’s configuration. It checks for:
✔ Valid phone number formatting
✔ Presence in Do-Not-Call (DNC) lists
✔ Blacklist checks
✔ Phone number duplicates
✔ Lead availability in active campaigns
Common Use Cases for check_phone_number API
🔹 Call centers verifying phone numbers before dialing
🔹 Marketing teams filtering out invalid leads
🔹 Compliance teams checking numbers against the DNC list
🔹 CRM integrations for real-time number validation
🔹 Automated lead import validation for sales teams
Step 1: Prerequisites for Using the API
Before using the check_phone_number API, ensure you have:
✅ VICIdial installed and configured
✅ An API-enabled user account with administrative permissions**
✅ A valid phone number to verify
✅ 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 check_phone_numberto the **Allowed API Functions** (or set toALL`)
7️⃣ Click Save Changes
Now, your user is authorized to check phone number validity 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 check_phone_number API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (check_phone_number) |
check_phone_number |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | PhoneValidation |
phone_number |
The phone number to check | 18001234567 |
campaign_id |
(Optional) The campaign to validate against | OUTBOUND_SALES |
Step 3: Sending the API Request
Method 1: Checking Phone Number via a Web Browser
Simply enter the following URL in your browser (replace credentials accordingly):
🔹 Press Enter, and the API should return the phone number status.
Method 2: Checking Phone Number via cURL (Command Line)
For developers, cURL is a convenient tool for making API requests. Use the following command:
🔹 This will return the phone number validation status in the terminal.
Method 3: Checking Phone Number via Postman
1️⃣ Open Postman
2️⃣ Set the request type to GET
3️⃣ Enter the API URL
4️⃣ Click Send
5️⃣ View the API response in the output panel
Step 4: Understanding API Responses
If the request is successful, VICIdial returns a response showing the phone number status:
Breaking Down the Response
| Response Value | Meaning |
|---|---|
18001234567 |
The phone number being checked |
VALID |
The number format is valid |
NOT IN DNC |
The number is not on a Do-Not-Call list |
NOT BLACKLISTED |
The number is not in the blacklist |
OK TO DIAL |
The number can be dialed in VICIdial |
Step 5: Handling Errors & Troubleshooting
If something goes wrong, VICIdial will return an error message instead of a validation result.
Common Errors & Fixes
| 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: NO FUNCTION SPECIFIED |
Missing function parameter | Ensure function=check_phone_number is included |
ERROR: INVALID PHONE NUMBER FORMAT |
Phone number format incorrect | Ensure the phone number follows correct format |
ERROR: PHONE NUMBER IN DNC |
The number is in the Do-Not-Call list | Remove from DNC list or check compliance |
Step 6: Best Practices for Using the check_phone_number API
✅ Use this API before importing new leads into VICIdial
✅ Integrate phone number validation into your CRM system
✅ Regularly check and update DNC and blacklist databases
✅ Ensure API access is restricted to authorized users only
✅ Log API calls for auditing and tracking purposes
Conclusion
The check_phone_number API function is an essential tool for verifying phone number validity in VICIdial. Whether you’re filtering out DNC numbers, ensuring compliance, or optimizing dialing efficiency, this API provides quick and accurate validation for better call center performance.
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
