Custom fields play a vital role in call center lead management, allowing businesses to store additional data that goes beyond standard lead information. VICIdial, a robust open-source call center solution, provides an API endpoint called list_custom_fields API, which allows administrators to retrieve all custom fields associated with a specific lead list.
The list_custom_fields API is particularly useful for businesses that need to store industry-specific lead information, CRM integrations, and personalized customer interactions. Instead of manually checking the VICIdial admin panel, this API enables real-time access to custom fields, making automation, reporting, and CRM synchronization more efficient.
Why Use the list_custom_fields API?
✅ Retrieve all custom fields assigned to a lead list
✅ Enhance CRM and third-party software integrations
✅ Ensure agents have complete lead information before dialing
✅ Improve reporting by accessing extended lead data
✅ Automate workflows by fetching custom field definitions dynamically
In this tutorial, we will cover:
🔹 How the list_custom_fields API works
🔹 How to configure and authenticate API access
🔹 How to construct and send API requests
🔹 Examples using a browser, cURL, and Postman
🔹 How to interpret API responses and troubleshoot errors
🔹 Best practices for using the list_custom_fields API efficiently
Let’s get started! 🚀
Understanding the list_custom_fields API Function
The list_custom_fields API enables users to retrieve a list of custom fields assigned to a specific lead list in VICIdial.
What Information Does the list_custom_fields API Provide?
✔ Custom Field Name – The name of the custom field
✔ Field Type – Text, number, date, etc.
✔ Field Label – Display name for agents
✔ Field Order – Determines the sequence in the form
✔ Required Status – Whether the field is mandatory
✔ Field Length – Maximum characters allowed
✔ Default Value – Pre-filled value if not updated
✔ Active Status – Whether the field is active (Y) or inactive (N)
Common Use Cases for list_custom_fields API
🔹 Supervisors retrieving all custom fields in a list for quality assurance
🔹 Developers integrating VICIdial custom fields with external CRMs
🔹 Automating the retrieval of custom field data for lead management
🔹 Ensuring agents have the correct custom fields available when making calls
🔹 Validating field definitions before importing leads into VICIdial
Step 1: Prerequisites for Using the API
Before using the list_custom_fields API, ensure you have:
✅ VICIdial installed and configured
✅ An API-enabled user account with administrative permissions**
✅ A valid list ID to retrieve custom fields
✅ 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 list_custom_fieldsto the **Allowed API Functions** (or set toALL`)
7️⃣ Click Save Changes
Now, your user is authorized to retrieve custom field details for a lead list 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 list_custom_fields API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (list_custom_fields) |
list_custom_fields |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | CustomFieldRetrieval |
list_id |
The lead list ID to retrieve custom fields for | 1005 |
Step 3: Sending the API Request
Method 1: Fetching Custom Fields via a Web Browser
Simply enter the following URL in your browser (replace credentials accordingly):
🔹 Press Enter, and the API should return all custom fields associated with the list.
Method 2: Fetching Custom Fields via cURL (Command Line)
For developers, cURL is a convenient tool for making API requests. Use the following command:
🔹 This will return a list of all custom fields for the specified list.
Method 3: Fetching Custom Fields 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 showing all custom fields for the specified list:
Breaking Down the Response
| Field Value | Meaning |
|---|---|
1005 |
List ID |
company_name |
Custom field name |
TEXT |
Field type (TEXT, NUMBER, DATE, etc.) |
Company Name |
Field label shown to agents |
1 |
Field order (defines display sequence) |
Y |
Required status (Y for required, N for optional) |
50 |
Maximum character length |
Default Inc. |
Default value (if any) |
Y |
Active status (Y for active, N for inactive) |
Step 5: Handling Errors & Troubleshooting
If something goes wrong, VICIdial will return an error message instead of the custom field data.
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: LIST ID NOT FOUND |
The list ID does not exist | Ensure list_id is correct |
ERROR: NO FUNCTION SPECIFIED |
Missing function parameter | Ensure function=list_custom_fields is included |
Conclusion
The list_custom_fields API function is an essential tool for retrieving custom field definitions in VICIdial. Whether you’re integrating with a CRM, validating custom field data, or optimizing agent workflows, this API provides quick and accurate access to critical lead list information.
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
