Managing Direct Inward Dialing (DID) numbers is crucial for inbound call routing, customer segmentation, and campaign management in a call center. VICIdial, a leading open-source call center solution, provides an efficient way to duplicate an existing DID configuration using the copy_did API.
Instead of manually setting up new DID entries for similar configurations, administrators can use this API to copy an existing DID and modify the new entry as needed. This saves time, reduces errors, and improves efficiency in handling large-scale inbound DID operations.
Why Use the copy_did API?
✅ Quickly duplicate existing DID settings
✅ Automate inbound DID management
✅ Reduce errors and configuration time
✅ Ensure consistency across multiple DID entries
✅ Integrate DID provisioning with external telephony systems
In this tutorial, we will cover:
🔹 How the copy_did 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 copy_did API efficiently
Let’s get started! 🚀
Understanding the copy_did API Function
The copy_did API enables users to create a duplicate DID entry based on an existing DID configuration. This allows rapid setup of multiple DID numbers with similar settings, avoiding the need for repetitive manual configurations.
What Information Does the copy_did API Require?
✔ Source DID Pattern – The DID number being copied
✔ New DID Pattern – The new DID number being created
✔ DID Active Status – Whether the new DID should be active (Y) or inactive (N)
Common Use Cases for copy_did API
🔹 Duplicating DIDs for different geographic locations
🔹 Creating multiple inbound numbers for similar call routing setups
🔹 Automating bulk DID provisioning for inbound call centers
🔹 Ensuring consistency across multiple inbound lines
🔹 Simplifying large-scale inbound call routing management
Step 1: Prerequisites for Using the API
Before using the copy_did API, ensure you have:
✅ VICIdial installed and configured
✅ An API-enabled user account with administrative permissions**
✅ A valid DID number that exists in VICIdial (source DID)
✅ A new DID number to be created (target DID)
✅ 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 copy_didto the **Allowed API Functions** (or set toALL`)
7️⃣ Click Save Changes
Now, your user is authorized to copy DID entries dynamically 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 copy_did API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (copy_did) |
copy_did |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | DIDCopy |
did_pattern |
The existing DID number to copy | 18001234567 |
new_did_pattern |
The new DID number to create | 18002223333 |
did_active |
Enable (Y) or disable (N) the new DID |
Y |
Step 3: Sending the API Request
Method 1: Copying a DID via a Web Browser
Simply enter the following URL in your browser (replace credentials accordingly):
🔹 Press Enter, and the API should create the new DID entry.
Method 2: Copying a DID via cURL (Command Line)
For developers, cURL is a convenient tool for making API requests. Use the following command:
🔹 This will return a success message confirming the DID copy.
Method 3: Copying a DID via Postman
1️⃣ Open Postman
2️⃣ Set the request type to GET
3️⃣ Enter the API URL
4️⃣ Click Send
5️⃣ The response should confirm that the DID has been copied
Step 4: Understanding API Responses
If the request is successful, VICIdial returns a response confirming the DID was copied:
Breaking Down the Response
| Response Value | Meaning |
|---|---|
SUCCESS |
The request was processed successfully |
18001234567 -> 18002223333 |
Indicates that the existing DID was copied to a new DID |
DID Copied Successfully |
Confirmation message |
Step 5: Handling Errors & Troubleshooting
If something goes wrong, VICIdial will return an error message instead of a 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: DID PATTERN NOT FOUND |
The source DID does not exist | Ensure did_pattern is correct |
ERROR: NEW DID ALREADY EXISTS |
The target DID is already in VICIdial | Choose a unique new_did_pattern |
ERROR: NO FUNCTION SPECIFIED |
Missing function parameter | Ensure function=copy_did is included |
Step 6: Best Practices for Using the copy_did API
✅ Use this API for bulk provisioning of similar DIDs
✅ Ensure the new DID number is unique before copying
✅ Automate inbound call routing updates after copying DIDs
✅ Restrict API access to authorized users to prevent unintended changes
✅ Monitor DID usage reports to avoid duplicate configurations
Conclusion
The copy_did API function is an essential tool for quickly duplicating DID entries in VICIdial. Whether you’re expanding inbound call handling, automating DID provisioning, or ensuring consistency across multiple campaigns, this API provides a fast and efficient way to manage inbound numbers dynamically.
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
