Cloning a DID with copy_did

When you buy a block of new inbound numbers from your carrier, every one of them usually needs the exact same routing as a number you already have working. Retyping that setup in the admin screen for each new DID (direct inward dialing) is slow and error-prone. The copy_did function copies the routing from one inbound DID onto one or more brand-new ones in a single request.

A DID (Direct Inward Dialing number) is the phone number your callers dial to reach a campaign or in-group. This call lives in the Non-Agent API, which you reach over plain HTTP, no agent session required. For the wider picture, start with the VICIdial API and AGI overview.

What you need to send

There are three required fields:

• source_did_pattern — the existing DID you are copying from, 2 to 50 characters, and it must already be a valid DID in the system. URL-encode special characters: a plus sign goes in as %2B.
• new_dids — one or more new numbers to create, 2 to 2000 characters, separated by commas for multiple. Same URL-encoding rule applies.
• source — a short description (max 20 characters) of what made the call, so it shows up in the logs.

There is one optional field, did_description (6 to 50 characters). Leave it blank and the new numbers inherit the source DID's description. Every routing detail behind that source DID, including its DID route and whether calls hit an Ingroup, comes along for the ride.

Permission requirement

The API user must have user_level set to 8 or higher and "Modify DIDs" enabled on their account. Without it you get a flat refusal instead of any change.

Example call

Clone the routing of 7275551114 onto three new numbers:

http://your-server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=copy_did&source_did_pattern=7275551114&new_dids=7275553338,7275553337,7275553336

How a clone flows

flowchart LR
  SourceDID[Source DID 7275551114] --> CopyDID[copy_did call]
  CopyDID --> Route[Routing copied]
  Route --> NewDID1[New DID 7275553338]
  Route --> NewDID2[New DID 7275553337]
  Route --> NewDID3[New DID 7275553336]
  NewDID1 --> InGroup[Same in-group]
  NewDID2 --> InGroup
  NewDID3 --> InGroup

Reading the response

Because you can copy several DIDs at once, you get a line per attempted number plus a final summary. A good run ends with:

SUCCESS: copy_did DIDS HAVE BEEN ADDED - 6666|1000|1|0

Per-number notices look like NOTICE: copy_did DID HAS BEEN ADDED, while a number that already exists returns NOTICE: copy_did DID ALREADY EXISTS. If nothing landed you get ERROR: copy_did NO DIDS ADDED. The common stop-points are ERROR: copy_did USER DOES NOT HAVE PERMISSION TO ADD DIDS (fix the user level) and ERROR: copy_did NOT AN ALLOWED DID (the source DID is wrong or missing). Learning to parse these strings is covered in reading VICIdial API responses.

After you clone

copy_did sets up identical routing, which is usually what you want. If one of the new numbers needs a different target, follow up with update_did to change just that one. Both calls together let you stand up a whole new number block from a script in seconds.

On a VICIfast box the API is enabled and ready the moment your server comes up, in under 40 seconds, so you can script DID provisioning from day one. See our plans to get a server.