# Bulk-adding DIDs to VICIdial: 300 numbers in two seconds

> Adding 200 DIDs one at a time through the VICIdial API took 40.5 seconds. Copying 300 from one template DID took 1.9. The replies, limits and traps.

URL: https://trustane.com/guides/vicidial-bulk-add-dids-api
By Trustane. Published 2026-11-05.

> **To the point**
> To load a block of inbound numbers, build and test one template DID, then clone it with the API function `copy_did`. It was about thirty times faster than `add_did` in our test, and every copy comes out configured the same.
>
> - `add_did`, one number per request: 200 numbers in 40.5 seconds.
> - `copy_did`, 100 numbers per request: 300 numbers in 1.9 seconds.
> - A new DID took a call two seconds after the API replied, with no reload.
> - The final reply line can say SUCCESS when a number was skipped, so count the lines.

## The three functions

The Non-Agent API has `add_did`, `copy_did` (it "adds new Inbound DID entries to the system, copied from an existing DID entry") and `update_did`. Deleting is `update_did` with `delete_did=Y`. There is no API function for carriers. `copy_did` is recent: the changelog lists it in July 2024. Ask your server what it runs:

```
https://YOUR-SERVER/vicidial/non_agent_api.php?function=version
```

Both builds we tested (2.14-206 and 2.14-210) had all three.

![Bar chart of time per number: add_did about 200 ms, copy_did about 6 ms](https://trustane.com/media/f6d447391b572fae-1600x512.webp "Time per number on one scratch server, one run of each")

## What the API user needs

The documentation asks for user level 8 or higher and the Modify DIDs permission. On our servers two more things applied: API access enabled on the user, and the function in the user's allowed API functions. Make a dedicated user with only those, limited to the three functions.

## Copy in batches

Create one DID in the admin screen with everything set: route, in-group or call menu, recording. Dial it and confirm where it lands. Every copy inherits it, so this is the only number you set by hand. Use one template per destination.

Required fields:

- `source_did_pattern`: 2 to 50 characters, a DID that exists.
- `new_dids`: 2 to 2000 characters, comma separated.
- `source`: a label for the caller, 20 characters at most.

The 2,000 character cap sets the batch size. We sent 100 ten-digit numbers (1,099 characters); about 180 fit.

```
https://YOUR-SERVER/vicidial/non_agent_api.php?source=didload&user=APIUSER&pass=APIPASS&function=copy_did&source_did_pattern=5550100001&new_dids=5552000001,5552000002
```

> **The password sits in the URL**
> The documentation's examples put the password in the query string, and a query string is written to the web server's access log. Treat that log as a file that contains the password, and give the API user the least permission the job allows.

## Read every reply line

One line comes back per number. The fields after the user are the new number, the template and the new DID's ID.

```
NOTICE: copy_did DID HAS BEEN ADDED - APIUSER|5552000001|5550100001|203|1
```

The trap is a mixed batch. We sent one existing number and one new one:

```
NOTICE: copy_did DID ALREADY EXISTS - APIUSER|5551000001
NOTICE: copy_did DID HAS BEEN ADDED - APIUSER|5553000006|5550100001|505|1
SUCCESS: copy_did DIDS HAVE BEEN ADDED - APIUSER|5550100001|1|1
```

The last line says SUCCESS, yet one of two was skipped. We read the last two fields as added and not added. Do not test for the word. Count the `HAS BEEN ADDED` lines against what you sent, and keep every raw reply. A missing template returns `ERROR: copy_did SOURCE DID DOES NOT EXIST`.

![Checklist of reply lines and what each means for a bulk DID load](https://trustane.com/media/c8352989910f799c-1600x678.webp "What to do with each kind of reply")

## Call three numbers

The API returned at 49.6 seconds past the minute and an inbound call to the new number was logged at 51, routed correctly. DIDs are looked up in the database at call time, which is why no reload is needed. Call the first, middle and last number, then check the log:

```sql
SELECT call_date, extension, did_id, did_route, channel
FROM vicidial_did_log
WHERE call_date >= CURDATE()
ORDER BY call_date DESC LIMIT 20;
```

The `channel` column shows which trunk delivered the call, a better record of carrier than the DID's carrier description field.

## Replies that are not what you expect

- **A plus sign is accepted and can never ring.** The inbound context is `exten => _X.,1,AGI(agi-DID_route.agi)`, and `_X.` matches digits only. Store numbers exactly as the carrier sends them. The `extension` column in `vicidial_did_log` shows what arrives.
- **Wrong length gives a misleading error.** A 1-character or 51-character pattern returned `YOU MUST USE ALL REQUIRED FIELDS`. Nothing was missing; 2 to 50 is the rule.
- **Descriptions under six characters are refused.** "Sales" is five. Leave the field out and the template's is used.
- **Bad targets are caught.** A nonexistent route, in-group or call menu is refused before a DID points at nothing.
- **Deleting is one at a time.** `update_did` takes one pattern, so removing 300 is 300 requests.
- **Copies are snapshots.** Change the template next month and nothing else changes. If a block may move together, route it all to one in-group or call menu.

Use `add_did` when each number needs its own settings, such as a number per client. At about 200 ms a number it still beats the form.

## How we tested

One scratch cloud server, Ubuntu, Asterisk 22, API 2.14-210. All 200 `add_did` calls and all 300 copies succeeded. We did not record the network distance, so absolute times will not transfer. We did not test a `new_dids` value at the 2,000 limit, or parallel batches.

## Questions people ask

### How many numbers fit in one copy_did request?

The limit is 2,000 characters in `new_dids`. Ten-digit numbers with commas fit about 180.

### Why did a call reach a new number without a reload?

The dialplan matches `_X.` and looks the DID up in the database when the call arrives.

## Next steps

1. Call `version` and confirm `copy_did` exists.
2. Create an API user with Modify DIDs only.
3. Test a template per destination, then send batches of 100 and count the added lines.

The carrier must deliver calls first: see [PJSIP carrier setup](https://trustane.com/guides/vicidial-pjsip-carrier-setup-asterisk-22). If the menu behind a number plays silence, read [audio upload and conversion](https://trustane.com/guides/vicidial-audio-upload-conversion). Moving numbers from another host? We load DIDs as part of a [migration](https://trustane.com/migrate), or [order a server](https://trustane.com/order).

VICIdial is a trademark of its owner. Trustane is an independent hosting provider.
