How to create an inbound DID with the add_did API

A DID (Direct Inward Dialing number) is the phone number your carrier hands to VICIdial when an inbound call arrives. add_did creates one of these entries over HTTP and tells the dialer where to send the call. If you're provisioning numbers in bulk or wiring a new carrier, scripting add_did beats clicking through the admin screen for every number.

Permissions and required fields

The API user must have a user_level of 8 or higher with "Modify DIDs" enabled. Two fields are required:

• did_pattern - 2 to 50 characters, the number to match. Special characters must be URL-encoded; a plus sign goes in as %2B.
• source - a short label (max 20 characters) naming the caller for the logs.

First time on this endpoint? Read how to call the non-agent API for the basics of the request.

Routing the call

The field that decides where the inbound call lands is did_route - the DID route. It must be one of EXTEN, VOICEMAIL, AGENT, PHONE, IN_GROUP, CALLMENU or VMAIL_NO_INST. The most common choice is IN_GROUP, which drops the caller into an inbound queue. record_call (Y, N or Y_QUEUESTOP) controls recording.

When did_route is IN_GROUP, a set of group-specific fields kicks in:

• group - a valid Ingroup group_id to send the call to.
• call_handle_method - how the call is handled (CID, CIDLOOKUP, CLOSER), default CID.
• agent_search_method - LO (load-balanced overflow), LB (load-balanced) or SO (server-only), default LB.
• list_id, entry_list_id, campaign_id and phone_code - for tying inbound leads to a Campaign, with defaults of 999, 0, blank and 1.

For EXTEN and similar routes you'd instead set extension, exten_context, voicemail_ext or phone_extension. did_description (6 to 50 characters) and active (Y/N) apply to every route.

The inbound path

flowchart LR
  Caller --> Carrier
  Carrier --> DID
  DID --> Route{did_route}
  Route -->|IN_GROUP| Ingroup
  Route -->|EXTEN| Extension
  Ingroup --> Agent
  Extension --> Agent

Example calls

Add a simple active DID with a plus-sign pattern:

http://your-server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=add_did&did_pattern=%2B1727555112&did_description=Updated+test+API+DID&active=Y

Add a DID routed to an in-group with recording and full options:

http://your-server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=add_did&did_pattern=7275553331&did_description=Testing+DID&active=N&did_route=EXTEN&record_call=Y_QUEUESTOP&extension=8300&exten_context=notdefault&voicemail_ext=8301&phone_extension=55000&server_ip=192.168.198.5&group=TEST_IN2&filter_clean_cid_number=R10

Success and error responses

A clean add returns:

SUCCESS: add_did DID HAS BEEN ADDED - 6666|1101

The errors name the field that's wrong:

• ERROR: add_did USER DOES NOT HAVE PERMISSION TO ADD DIDS - 6666
• ERROR: add_did DID ALREADY EXISTS - 6666|1000
• ERROR: add_did DID ROUTE IS NOT VALID, THIS IS AN OPTIONAL FIELD - 6666|12
• ERROR: add_did GROUP ID MUST BE A VALID INBOUND GROUP IN THE SYSTEM, THIS IS AN OPTIONAL FIELD - 6666|test

If you need many similar numbers at once, copy_did clones an existing DID's settings onto a comma-separated batch of new patterns - less typing than calling add_did for each one.

Where it fits

add_did is one of the inbound-side functions of the Non-agent API. Once the DID (direct inward dialing) exists and points at the right destination, calls flow to agents with no further setup. For the full list of functions, read the VICIdial API and AGI overview.

VICIfast provisions a working box - API and inbound DID handling ready - in under 40 seconds. See what each plan includes on the pricing page.