Managing lead lists effectively is crucial for call center performance and campaign optimization. VICIdial, a powerful open-source call center solution, allows administrators to update list settings dynamically and reset leads using the update_list API.
The update_list API enables managers and developers to modify existing lead lists, update their status, reset time, expiration, and caller ID, and reset lead statuses to make them callable again. This helps ensure better list segmentation, optimized call strategies, and efficient lead management.
Why Use the update_list API?
✅ Modify lead list settings without manual intervention
✅ Reset lead statuses for re-dialing in outbound campaigns
✅ Change list parameters such as caller ID, expiration date, and active status
✅ Automate campaign updates by modifying list settings in real time
✅ Ensure leads are available for dialing without manually resetting lists
In this tutorial, we will cover:
🔹 How the update_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 update_list API efficiently
Let’s get started! 🚀
Understanding the update_list API Function
The update_list API allows administrators to modify list settings and reset leads, making it useful for:
✔ Enabling or disabling lists dynamically
✔ Updating caller ID and expiration dates
✔ Resetting lead statuses for redialing
✔ Improving campaign efficiency by keeping lists updated
What Can Be Updated with update_list API?
✔ List Name – Change the name of the list
✔ Active Status – Activate (Y) or deactivate (N) a list
✔ Reset Lead Statuses – Reset leads to make them callable again
✔ Expiration Date – Set an expiry date for the list
✔ Reset Time – Define when the list resets lead statuses
✔ Campaign ID – Assign the list to a different campaign
✔ Caller ID – Change the caller ID for outbound calls
Common Use Cases for update_list API
🔹 Reactivating expired or inactive lists automatically
🔹 Resetting leads at the start of a new sales cycle
🔹 Updating list parameters dynamically from CRM integrations
🔹 Optimizing call flow by managing lists without manual intervention
Step 1: Prerequisites for Using the API
Before using the update_list API, ensure you have:
✅ VICIdial installed and configured
✅ An API-enabled user account with administrative permissions**
✅ An existing list ID to update
✅ 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 update_listto the **Allowed API Functions** (or set toALL`)
7️⃣ Click Save Changes
Now, your user is authorized to update list settings and reset leads 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 update_list API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (update_list) |
update_list |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | ListUpdateAutomation |
list_id |
The list ID to update | 1005 |
list_name |
(Optional) New name for the list | March Leads |
active |
(Optional) Activate (Y) or deactivate (N) the list |
Y |
reset_list |
(Optional) Reset leads in the list (Y) |
Y |
reset_time |
(Optional) Set the time when the list resets | 23:59:59 |
campaign_id |
(Optional) Assign list to a new campaign | OUTBOUND_SALES |
expiration_date |
(Optional) Set the expiration date of the list | 2024-12-31 |
caller_id |
(Optional) Set a caller ID for the list | 18005551234 |
Step 3: Sending the API Request
Method 1: Updating a Lead List via a Web Browser
Simply enter the following URL in your browser (replace credentials accordingly):
🔹 Press Enter, and the API should update the lead list settings.
Method 2: Updating 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 the list update.
Method 3: Updating 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 that the lead list has been updated
Step 4: Understanding API Responses
If the request is successful, VICIdial returns a response confirming the list was updated:
Breaking Down the Response
| Response Value | Meaning |
|---|---|
SUCCESS |
The request was processed successfully |
1005 |
The updated list ID |
List Updated |
The list settings were changed |
Reset Applied |
Leads in the list were reset |
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 NOT FOUND |
The list ID does not exist | Ensure list_id is correct |
ERROR: NO FUNCTION SPECIFIED |
Missing function parameter | Ensure function=update_list is included |
Conclusion
The update_list API function is an essential tool for managing and resetting lead lists dynamically in VICIdial. Whether you’re activating/deactivating lists, updating campaign assignments, resetting leads, or automating list settings, this API provides a powerful and efficient way to manage call center lead lists.
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
