VICIdial is a widely used open-source call center solution, offering powerful tools for lead management, campaign automation, and agent efficiency. One of its most valuable API functions is lead_search, which allows users to find leads by phone number in real-time.
This API is particularly useful for:
✅ Quickly retrieving lead details based on phone numbers
✅ CRM integrations to check if a lead already exists
✅ Ensuring agents have the correct lead information before making calls
✅ Preventing duplicate lead entries in campaigns
In this guide, you’ll learn:
- What the
lead_searchAPI does and why it’s useful - How to configure and authenticate API access
- How to construct and send API requests
- Examples of API calls using a browser, cURL, and Postman
- How to interpret API responses and troubleshoot errors
- Best practices for using the
lead_searchAPI efficiently
Let’s get started! 🚀
Understanding the lead_search API Function
The lead_search API allows users to find leads in VICIdial by phone number, returning detailed lead information if a match is found.
Key Features of lead_search API
✔ Instantly find leads using a phone number
✔ Retrieve full lead details including status, campaign, and agent assignment
✔ Helps prevent duplicate lead entries
✔ Can be used in CRM systems for seamless data integration
Common Use Cases
🔹 Call Verification – Ensure that agents call the right leads with correct details
🔹 CRM Synchronization – Check if a lead exists before adding new records
🔹 Duplicate Lead Prevention – Avoid adding the same lead multiple times
🔹 Lead Follow-ups – Quickly access lead history before making a call
Step 1: Prerequisites for Using the API
Before using the lead_search API, ensure you have the following:
✅ VICIdial installed and configured
✅ An API-enabled user account with the correct permissions
✅ A valid phone number to search for (already stored in VICIdial)
✅ 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_search to the Allowed API Functions (or set to ALL)
7️⃣ Click Save Changes
Now, your user is authorized to retrieve lead details 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 lead_search API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (lead_search) |
lead_search |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | CRM_Query |
phone_number |
The phone number to search for | 9876543210 |
Step 3: Sending the API Request
Method 1: Searching for a Lead via a Web Browser
Simply enter the following URL in your browser (replace credentials accordingly):
🔹 Press Enter, and the lead details should display in your browser.
Method 2: Searching for a Lead via cURL (Command Line)
For developers, cURL is a convenient tool for making API requests. Use the following command:
🔹 This will return the lead information directly in the terminal.
Method 3: Searching for a Lead 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 lead details 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_search is included |
ERROR: NO MATCHING LEADS FOUND |
No leads match the phone number | Ensure the phone number exists in VICIdial |
Step 6: Best Practices for Using the lead_search API
✅ Use correct phone number formatting to avoid search mismatches
✅ Ensure API user permissions are properly configured
✅ Test with different phone numbers to validate results
✅ Store and analyze retrieved data for reporting and CRM integration
✅ Monitor API usage logs to optimize search performance
Conclusion
The lead_search API function is an essential tool for finding leads by phone number in VICIdial. Whether you need to verify lead existence, prevent duplicates, or enhance CRM integrations, this API ensures quick and accurate lead retrieval.
📌 Key Takeaways
✅ The lead_search API allows finding leads by phone number
✅ Requires an API-enabled user with appropriate permissions
✅ API requests can be made via browser, cURL, or Postman
✅ Common errors are permission and input-related and can be fixed in Admin settings
