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
Log in to the VICIdial Admin Panel
Go to Admin > Users
Select the user who will access the API
Set API Access to 1 (Enabled)
Set User Level to 7 or higher
Add add_lead to the Allowed API Functions (or set to ALL)
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
Open Postman
Set the request type to GET
Enter the API URL
Click Send
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
