Call centers rely on lead lists to organize and manage outbound calling campaigns efficiently. VICIdial, a powerful open-source call center solution, allows administrators to create new lead lists dynamically using the add_list API.
The add_list API enables call center managers and developers to automate list creation, ensuring better lead segmentation, improved campaign targeting, and increased agent productivity. Instead of manually setting up lead lists via the VICIdial interface, this API allows for seamless bulk list creation and integration with third-party CRMs or lead management systems.
Why Use the add_list API?
✅ Automate lead list creation without manual input
✅ Integrate VICIdial with external lead management and CRM platforms
✅ Improve campaign efficiency by categorizing leads dynamically
✅ Reduce human errors in manually creating lead lists
✅ Enable real-time campaign updates by adding new lists instantly
In this tutorial, we’ll cover:
🔹 How the add_list 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_list API efficiently
Let’s dive in! 🚀
Understanding the add_list API Function
The add_list API allows users to create a new lead list in VICIdial for use in outbound or inbound campaigns.
What Information Does the add_list API Require?
✔ List ID – A unique identifier for the lead list
✔ List Name – A descriptive name for the list
✔ Campaign ID – The campaign this list will be assigned to
✔ Active Status – Whether the list is active (Y) or inactive (N)
✔ Reset Time – Defines when the list resets lead statuses
Common Use Cases for add_list API
🔹 Automatically generating new lead lists for campaigns
🔹 CRM integrations that push lead data into VICIdial dynamically
🔹 Marketing teams creating targeted lead segments in bulk
🔹 Ensuring newly imported leads are properly categorized
🔹 Reducing agent downtime by keeping fresh leads available
Step 1: Prerequisites for Using the API
Before using the add_list API, ensure you have:
✅ VICIdial installed and configured
✅ An API-enabled user account with administrative permissions**
✅ A valid campaign ID to assign the lead list to
✅ 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_listto the **Allowed API Functions** (or set toALL`)
7️⃣ Click Save Changes
Now, your user is authorized to create 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 add_list API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (add_list) |
add_list |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | LeadListCreation |
list_id |
Unique identifier for the new lead list | 1005 |
list_name |
A descriptive name for the list | New Leads - March |
campaign_id |
The campaign to assign this list to | OUTBOUND_SALES |
active |
Whether the list is active (Y) or inactive (N) |
Y |
reset_time |
Reset time for lead statuses (HH:MM:SS) | 23:59:59 |
Step 3: Sending the API Request
Method 1: Creating a Lead List via a Web Browser
Simply enter the following URL in your browser (replace credentials accordingly):
🔹 Press Enter, and the API should create the new lead list.
Method 2: Creating a Lead List via cURL (Command Line)
For developers, cURL is a convenient tool for making API requests. Use the following command:
🔹 This will return a success message confirming list creation.
Method 3: Creating a Lead 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 confirm the lead list has been created
Step 4: Understanding API Responses
If the request is successful, VICIdial returns a response confirming the list was created:
Breaking Down the Response
| Response Value | Meaning |
|---|---|
SUCCESS |
The request was processed successfully |
1005 |
The unique list ID of the newly created list |
New Leads - March |
The name of the lead list |
OUTBOUND_SALES |
The campaign the list is assigned to |
Step 5: Handling Errors & Troubleshooting
If something goes wrong, VICIdial will return an error message instead of a success confirmation.
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 ALREADY EXISTS |
The list ID is already in use | Choose a unique list_id |
ERROR: NO FUNCTION SPECIFIED |
Missing function parameter | Ensure function=add_list is included |
Conclusion
The add_list API function is an essential tool for automating lead list creation in VICIdial. Whether you’re running outbound sales campaigns, integrating CRM lead imports, or optimizing lead management, this API provides a fast and reliable way to create new lists dynamically.
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
