Changing a DID's routing with update_did
Edit an inbound DID's description, routing target, recording flag, and more from a single API call with update_did.

Inbound routing changes all the time. A campaign closes, a new Ingroup opens, you turn recording on for compliance. Instead of opening the admin screen each time, the update_did function edits a single existing inbound DID (direct inward dialing) (the number callers dial) straight from an API call.
It updates the row in the inbound DID table for a number that already exists. This is a sibling of the copy_did call: copy_did creates new numbers, update_did fixes the ones you already have. The VICIdial API and AGI overview sets the broader context.
Required vs editable fields
Only two fields are required:
- did_pattern - the DID to edit, 2 to 50 characters, must be a valid DID in the system. URL-encode special characters (a plus sign becomes %2B).
- source - a short description of what triggered the call (max 20 characters).
Everything else is an editable field you include only if you want to change it. The useful ones:
- did_description - 6 to 50 characters.
- active - Y or N, to turn the number on or off.
- did_route - one of EXTEN, VOICEMAIL, AGENT, PHONE, IN_GROUP, CALLMENU, or VMAIL_NO_INST. This is the routing target.
- record_call - Y, N, or Y_QUEUESTOP.
When the route is IN_GROUP there are extra fields for the in-group's group id, call handle method, agent search method, list id, and campaign id. There is also delete_did (Y or N, default N) if you want to remove the DID entirely. The DID route value decides which of those extras matter.
Permission requirement
Same gate as copy_did: the API user needs user_level 8 or higher and "Modify DIDs" enabled. Deleting a DID needs the delete permission on top of that. Permission tiers across the whole API are explained in API user level permissions.
Example call
Re-point a DID at an extension, turn it off, and set recording:
http://your-server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=update_did&did_pattern=7275553331&did_description=Testing+DID&active=N&did_route=EXTEN&record_call=Y_QUEUESTOP&extension=8300&exten_context=notdefault
How update_did decides what to change
flowchart TD
Call[update_did call] --> CheckPerm{user_level 8 plus Modify DIDs}
CheckPerm -- no --> Deny[Permission error]
CheckPerm -- yes --> CheckDID{DID exists}
CheckDID -- no --> NotExist[DID DOES NOT EXIST]
CheckDID -- yes --> Apply[Apply editable fields]
Apply --> Route{did_route is IN_GROUP}
Route -- yes --> Group[Use group and list settings]
Route -- no --> Done[Update saved]
Group --> DoneReading the response
The common failures are clear. ERROR: update_did USER DOES NOT HAVE PERMISSION TO UPDATE DIDS means the user level or flag is wrong. ERROR: update_did DID DOES NOT EXIST means the did_pattern points at nothing. Each optional field validates separately, so a bad route returns ERROR: update_did DID ROUTE IS NOT VALID, THIS IS AN OPTIONAL FIELD, and a bad active value returns ERROR: update_did ACTIVE MUST BE Y OR N, THIS IS AN OPTIONAL FIELD. Fix the named field and resend.
Pair update_did with copy_did and you can manage a whole inbound DID inventory from a script with no clicking. On a VICIfast server the API is live as soon as the box provisions, in under 40 seconds. See our plans to start.
Related from VICIfast
- Bring your own SIP carrierCarrier templates, a dial prefix per trunk, failover routes and a real test call.
- The SIP trunking guideChoosing carriers, routing, and what breaks in production.
- AI call analysis on your recordingsA transcript, summary, sentiment, quality score and red flags per recording.
- Bring your own server - $29/moYour VPS or on-prem hardware; we install and manage VICIdial over SSH.
About VICIfast
We run VICIdial servers for call centres, so you don’t have to. You get the dialer set up, secured and kept running — we handle the server, the updates and the backups. Bring your own phone carrier at no markup, or use VICIfast Voice, our own US calling and numbers, from $0.0085 a minute. From $49 a month per server.
Questions? Call +1 636 556 0022 and talk to someone who runs dialers.
Citing this article
VICIfast Engineering. “Changing a DID's routing with update_did”. VICIfast LLC, June 28, 2026. Retrieved from https://vicifast.com/blog/use-update-did-api
Have questions?
Related posts
You might be interested in
VICIfast newsletter
Liked this? Get the next one in your inbox.
We ship the kind of stuff you just read - concrete, numbers-first, no drip. One email when a new post goes live. Unsubscribe in one click.
Comments
No comments yet - be the first.







