Key Takeaways
✅ The add_lead API helps you add leads programmatically
✅ Authentication requires API-enabled user credentials
✅ You can make API requests via browser, cURL, or Postman
✅ Common errors are permission or input-related and can be fixed in Admin settings
VICIdial is one of the most powerful open-source contact center solutions, widely used for managing outbound, inbound, and blended campaigns. One of its most crucial features is its ability to handle leads efficiently.
The add_lead API function allows you to add new leads programmatically into VICIdial, making it an essential tool for:
✅ CRM integrations to automate lead imports
✅ Bulk lead uploads via scripts or external applications
✅ Dynamic lead entry from web forms, chatbots, or third-party tools
✅ Reducing manual data entry and improving efficiency
In this guide, we will cover:
- How the
add_leadAPI works - Prerequisites for using the API
- How to construct and send an API request
- Example API requests using a browser, cURL, and Postman
- Understanding API responses and handling errors
- Best practices for lead management in VICIdial
Let’s get started! 🚀
Understanding the add_lead API Function
The add_lead API function is used to insert a new lead into the VICIdial database with various details like phone number, name, address, email, and more.
Common Use Cases
🔹 Importing leads dynamically from a website form
🔹 Auto-adding leads from Facebook or Google Ads
🔹 Bulk lead uploads from external CRMs
🔹 Transferring leads from third-party lead vendors
Step 1: Prerequisites for Using the API
Before you can use the add_lead API, ensure you have:
✅ VICIdial installed and configured
✅ An API-enabled user account with sufficient permissions
✅ Your VICIdial server URL and credentials
✅ A lead list ID where new leads will be added
How to Enable API Access for a VICIdial User
1️⃣ Log in to the VICIdial Admin Panel
2️⃣ Go 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 add_lead to the Allowed API Functions (or set to ALL)
7️⃣ Click Save Changes
Now, your API user is ready to add leads.
Step 2: Constructing the API Request
The VICIdial API uses HTTP GET requests, meaning you can call it from a browser, terminal (cURL), or API tools like Postman.
Base API URL
🔹 Replace your-vicidial-server with your actual VICIdial instance.
Required Parameters for add_lead
| Parameter | Description | Example |
|---|---|---|
function |
API function (add_lead) |
add_lead |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | CRM_Integration |
phone_number |
The lead’s phone number | 9876543210 |
list_id |
The VICIdial list ID to store the lead | 101 |
first_name |
Lead’s first name | John |
last_name |
Lead’s last name | Doe |
email |
Lead’s email address (optional) | johndoe@example.com |
address1 |
Lead’s address (optional) | 123 Main St |
Step 3: Sending the API Request
Method 1: Adding a Lead via a Web Browser
Open your browser and enter the following URL (replace credentials accordingly):
🔹 Press Enter, and the API response should display in your browser.
Method 2: Adding a Lead via cURL (Command Line)
For developers, cURL is a powerful tool for API requests. Run this command in your terminal:
🔹 This will return the API response directly in the terminal.
Method 3: Adding 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, you will receive a response like this:
Breaking Down the Response
| Value | Meaning |
|---|---|
SUCCESS |
The lead was added successfully |
1 |
Lead ID assigned by VICIdial |
101 |
List ID where the lead was added |
John |
First Name |
Doe |
Last Name |
9876543210 |
Phone Number |
new |
Status of the lead |
Step 5: Handling Errors & Troubleshooting
If something goes wrong, VICIdial returns an error message instead of success details.
Common Errors & Fixes
| Error Message | Cause | Solution |
|---|---|---|
ERROR: USER DOES NOT HAVE PERMISSION TO USE THIS FUNCTION |
Insufficient API permissions | Set API Access to 1 and user level to 7+ |
ERROR: INVALID USERNAME OR PASSWORD |
Wrong credentials | Verify API username and password |
ERROR: NO FUNCTION SPECIFIED |
Missing function parameter | Ensure function=add_lead is included |
ERROR: MISSING PHONE NUMBER |
Phone number not provided | Add phone_number parameter |
ERROR: INVALID LIST ID |
Incorrect list ID | Ensure list_id exists in VICIdial |
Step 6: Best Practices for Using the add_lead API
✅ Validate leads before adding (Check for duplicate phone numbers)
✅ Use unique source identifiers for tracking API calls
✅ Schedule lead uploads during low-traffic periods to reduce server load
✅ Test API calls in a staging environment before production deployment
✅ Log API responses to monitor errors and optimize automation
Conclusion
The add_lead API function is a powerful tool for automating lead entry into VICIdial, making it ideal for CRM integrations, marketing automation, and bulk lead uploads. By following the steps outlined in this guide, you can ensure seamless and efficient lead management.
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
