Key Takeaways
The lead_status_search API in VICIdial is a powerful tool that enables users to filter leads based on their status and call date, making it easier to retrieve relevant lead data for follow-ups, reporting, and CRM integrations. This functionality is particularly useful for call centers that need to track lead progress, automate callbacks, or analyze campaign performance.
To use this API, the requesting user must have API access enabled and the necessary permissions configured in VICIdial. The user account should have a User Level of 7 or higher and explicit access to the lead_status_search function (or full API access). Without the correct permissions, the API request will be denied, preventing access to filtered lead data.
The API requests can be executed using a web browser, cURL (command-line tool), or Postman (API testing tool), offering flexibility for different use cases and system integrations. Whether searching for specific lead statuses, retrieving call data for a specific date, or exporting filtered leads, this API ensures efficient data retrieval.
However, common errors such as insufficient permissions or incorrect input parameters can impact the request’s success. Most issues can be resolved by verifying the user’s API access settings in the VICIdial Admin Panel and ensuring that the status, call date, and list ID parameters are correctly formatted. Proper error handling and validation will help maintain smooth API functionality and optimize lead management processes.
VICIdial is a feature-rich, open-source call center solution widely used for managing inbound and outbound campaigns. One of the most valuable API functions for lead management is the lead_status_search API, which allows you to search for leads based on their status and call date.
This API is particularly useful for:
✅ Filtering leads based on their status (SALE, DNC, CALLBACK, etc.)
✅ Retrieving leads contacted within a specific date range
✅ Automating follow-up actions on leads
✅ Exporting filtered lead data for analysis and reporting
In this tutorial, we will cover:
- How the
lead_status_searchAPI works - Prerequisites for using the API
- How to construct and send API requests
- Example API calls using a browser, cURL, and Postman
- Understanding API responses and handling errors
- Best practices for searching and retrieving leads efficiently
Let’s dive in! 🚀
Understanding the lead_status_search API Function
The lead_status_search API allows users to search for leads by status and call date, returning a list of matching leads along with their details.
Key Features of lead_status_search API
✔ Filter leads based on their current status (SALE, NOT INTERESTED, DNC, etc.)
✔ Retrieve leads contacted within a specific date range
✔ Search within a specific list or across all lists
✔ Export lead data for further processing and reporting
Common Use Cases
🔹 CRM Integration – Sync only leads that meet specific conditions
🔹 Lead Follow-ups – Identify and re-engage leads that need callbacks
🔹 Data Export – Retrieve leads for analysis, reporting, or migration
🔹 Campaign Optimization – Measure lead quality and conversion rates
Step 1: Prerequisites for Using the API
Before using the lead_status_search API, ensure you have:
✅ VICIdial installed and configured
✅ An API-enabled user account with the correct permissions
✅ A valid campaign, list, or lead status to search for
✅ 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 7 or higher
6️⃣ Add lead_status_search to the Allowed API Functions (or set to ALL)
7️⃣ Click Save Changes
Now, your user is ready to execute lead search queries via 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 lead_status_search API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (lead_status_search) |
lead_status_search |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | CRM_Query |
list_id |
The VICIdial list to search within | 101 |
status |
The lead status to filter by | SALE |
call_date |
The date when the lead was last contacted | 2024-01-10 |
Step 3: Sending the API Request
Method 1: Searching for Leads via a Web Browser
Simply enter the following URL in your browser (replace credentials accordingly):
🔹 Press Enter, and the list of matching leads should display in your browser.
Method 2: Searching for Leads via cURL (Command Line)
For developers, cURL is a powerful tool for making API requests. Use the following command:
🔹 This will return the matching lead information directly in the terminal.
Method 3: Searching for Leads 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 with matching leads in a pipe-separated format (|):
Breaking Down the Response
| Value | Meaning |
|---|---|
1001 |
Lead ID |
John |
First Name |
Doe |
Last Name |
9876543210 |
Phone Number |
SALE |
Lead Status |
2024-01-10 |
Last Call Date |
Campaign1 |
Campaign Name |
List101 |
List ID |
Step 5: Handling Errors & Troubleshooting
If something goes wrong, VICIdial will return an error message instead of lead details.
Common Errors & Fixes
| Error Message | Cause | Solution |
|---|---|---|
ERROR: USER DOES NOT HAVE PERMISSION TO USE THIS FUNCTION |
Insufficient API permissions | Ensure user level is 7+ 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=lead_status_search is included |
ERROR: NO MATCHING LEADS FOUND |
No leads match the criteria | Adjust filters (status, call date, list ID) |
Step 6: Best Practices for Using the lead_status_search API
✅ Use specific filters to refine search results efficiently
✅ Ensure API user permissions are configured correctly
✅ Test with different date ranges and statuses for optimal results
✅ Export and store retrieved data for reporting and CRM integrations
✅ Monitor API usage logs to optimize search performance
Conclusion
The lead_status_search API function is an essential tool for filtering leads by status and call date in VICIdial. Whether you need to extract leads for follow-ups, generate reports, or integrate with a CRM, this API ensures seamless data retrieval and automation.
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
