VICIdial is a widely used open-source call center software that offers powerful tools for managing agents, leads, and campaigns. One of its key administrative tasks is user management, which includes adding new agents, supervisors, or administrators.
The add_user API allows administrators to create new users programmatically, making it easier to manage user onboarding, automate account creation, and integrate VICIdial with external CRM systems.
Why Use the add_user API?
✅ Automate user creation without manual input
✅ Easily integrate user management with external applications
✅ Ensure new users have the correct roles and permissions
✅ Improve efficiency when setting up multiple agents
In this guide, we’ll cover:
🔹 What the add_user API does
🔹 How to configure and authenticate API access
🔹 How to construct and send API requests
🔹 Examples using a browser, cURL, and Postman
🔹 Understanding API responses and troubleshooting errors
🔹 Best practices for using the add_user API efficiently
Let’s get started! 🚀
Understanding the add_user API Function
The add_user API in VICIdial allows administrators to create new users programmatically. This function is useful when:
✔ Automating the onboarding process for agents and managers
✔ Creating users in bulk without manually entering data
✔ Ensuring proper role-based access control
✔ Integrating with HR systems or CRM platforms
Common Use Cases for add_user API
🔹 Creating agent accounts from a third-party system
🔹 Automating user setup during onboarding
🔹 Setting up new administrators with correct permissions
🔹 Integrating VICIdial user management with CRM or HR software
Step 1: Prerequisites for Using the API
Before using the add_user API, ensure you have:
✅ VICIdial installed and configured
✅ An API-enabled user account with administrative permissions
✅ A valid API username and password
✅ 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 add_userto the **Allowed API Functions** (or set toALL`)
7️⃣ Click Save Changes
Now, your user is authorized to create new accounts 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 add_user API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (add_user) |
add_user |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | CRM_UserSetup |
user_id |
The username for the new user | agent001 |
pass_hash |
Encrypted password for security | 5f4dcc3b5aa765d61d8327deb882cf99 |
full_name |
The user’s full name | John Doe |
user_level |
Permission level (1-9) | 1 (Agent), 7 (Manager), 9 (Admin) |
user_group |
Group assignment for role management | AGENTS |
phone_login |
Phone extension login | 8001 |
phone_pass |
Password for phone login | abc123 |
active |
Status of the user (Y for active, N for inactive) |
Y |
Step 3: Sending the API Request
Method 1: Creating a User via a Web Browser
Simply enter the following URL in your browser (replace credentials accordingly):
🔹 Press Enter, and the API response should confirm the user was created.
Method 2: Creating a User via cURL (Command Line)
For developers, cURL is a convenient tool for making API requests. Use the following command:
🔹 This will create the user and return the API response in the terminal.
Method 3: Creating a User 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 confirming the user creation:
Breaking Down the Response
| Value | Meaning |
|---|---|
agent001 |
The newly created user’s ID |
John Doe |
The full name of the user |
Created |
Confirmation that the user has been added successfully |
Step 5: Handling Errors & Troubleshooting
If something goes wrong, VICIdial will return an error message instead of 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: NO FUNCTION SPECIFIED |
Missing function parameter | Ensure function=add_user is included |
ERROR: USER ALREADY EXISTS |
The username is already taken | Use a unique user_id |
Step 6: Best Practices for Using the add_user API
✅ Ensure user permissions match their role to prevent security risks
✅ Use API logs to track created users for auditing and compliance
✅ Encrypt passwords before sending them via API
✅ Use unique usernames to avoid conflicts
✅ Automate bulk user creation to speed up onboarding
Conclusion
The add_user API function is an essential tool for efficiently managing user accounts in VICIdial. Whether you’re automating agent onboarding, integrating with HR systems, or ensuring accurate role assignments, this API provides a quick and effective solution.
📌 Key Takeaways
✅ The add_user API allows automated user creation in VICIdial
✅ Requires an API-enabled user with administrative 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
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
