Managing lead lists efficiently is essential for maximizing campaign performance, improving call center efficiency, and ensuring that agents are working with fresh and accurate data. VICIdial, a powerful open-source call center solution, provides the list_info API, which allows administrators to fetch summary details about a specific lead list.
The list_info API helps managers, supervisors, and developers by providing real-time insights into lead list performance, including the total number of leads, callable leads, dialed leads, and more. This API is particularly useful for campaign optimization, CRM integration, and real-time reporting.
Why Use the list_info API?
✅ Retrieve real-time statistics for a lead list
✅ Monitor how many leads are available for dialing
✅ Ensure campaign efficiency by checking lead availability
✅ Integrate list summary data with external reporting tools
✅ Optimize dialing strategies based on list performance
In this tutorial, we’ll cover:
🔹 How the list_info 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 list_info API efficiently
Let’s get started! 🚀
Understanding the list_info API Function
The list_info API allows administrators to fetch detailed summary statistics for a specific lead list.
What Information Does the list_info API Provide?
✔ List Name and Campaign ID
✔ Total Leads in the List
✔ Callable Leads (Leads Available for Dialing)
✔ Leads Already Dialed
✔ New Leads (Never Called)
✔ Lead Expiration Date
✔ Active or Inactive Status
✔ DNC (Do Not Call) Leads Count
Common Use Cases for list_info API
🔹 Supervisors monitoring lead list performance in real-time
🔹 Call center managers ensuring enough leads are available for dialing
🔹 CRM integrations that need lead availability data
🔹 Automated reporting and campaign optimization
🔹 Ensuring compliance by tracking DNC leads in a list
Step 1: Prerequisites for Using the API
Before using the list_info API, ensure you have:
✅ VICIdial installed and configured
✅ An API-enabled user account with administrative permissions**
✅ A valid list ID to retrieve summary information
✅ 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 list_infoto the **Allowed API Functions** (or set toALL`)
7️⃣ Click Save Changes
Now, your user is authorized to retrieve summary data for lead lists 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 list_info API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (list_info) |
list_info |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | ListSummaryReport |
list_id |
The lead list ID to retrieve information for | 1005 |
Step 3: Sending the API Request
Method 1: Fetching List Summary via a Web Browser
Simply enter the following URL in your browser (replace credentials accordingly):
🔹 Press Enter, and the API should return the lead list summary.
Method 2: Fetching List Summary via cURL (Command Line)
For developers, cURL is a convenient tool for making API requests. Use the following command:
🔹 This will return a summary report for the specified list.
Method 3: Fetching List Summary 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 lead list summary:
Breaking Down the Response
| Response Value | Meaning |
|---|---|
1005 |
List ID |
Outbound Sales Leads |
List Name |
OUTBOUND_SALES |
Campaign ID assigned to this list |
10000 |
Total leads in the list |
4500 |
Callable leads (leads available for dialing) |
5500 |
Leads already dialed |
2000 |
New leads (never called before) |
500 |
Leads marked as “Do Not Call” (DNC) |
500 |
Expired leads (not callable anymore) |
Y |
List is active (Y for active, N for inactive) |
2024-12-31 |
List expiration date |
Step 5: Handling Errors & Troubleshooting
If something goes wrong, VICIdial will return an error message instead of the lead list summary.
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: LIST ID NOT FOUND |
The list ID does not exist | Ensure list_id is correct |
ERROR: NO FUNCTION SPECIFIED |
Missing function parameter | Ensure function=list_info is included |
Step 6: Best Practices for Using the list_info API
✅ Use this API to monitor list performance in real-time
✅ Integrate list statistics into CRM dashboards
✅ Ensure campaigns have enough callable leads before starting
✅ Restrict API access to authorized users to prevent data leaks
✅ Automate list reporting to keep agents updated
Conclusion
The list_info API function is an essential tool for retrieving real-time lead list summaries in VICIdial. Whether you’re monitoring lead availability, optimizing campaign efficiency, or integrating list data with external tools, this API provides quick and accurate insights into lead list 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
