Moving a lead back from the archive with lead_dearchive

Months ago someone moved a batch of old leads to the archive to keep the active dialing table fast. Now a customer from that batch calls back, or you decide a campaign is worth a second pass, and you need one of those leads dialable again. The lead_dearchive function moves it back, one lead at a time, without any database surgery.

A Lead is a single contact record in VICIdial: a phone number plus a name and any other fields. When a lead sits in the archive table, the dialer cannot reach it. This call from the Non-agent API, the back-office set that acts on the database rather than on a live agent, copies one archived lead back into the active list.

The two fields it needs

This is one of the simplest calls in the whole API (application programming interface). You send just two required fields beyond user and pass:

• source - a short label, up to 20 characters, naming what triggered the call.
• lead_id - the ID of the archived lead you want back.

Here is the full call:

curl "http://server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=lead_dearchive&lead_id=274071"

On success the response begins with SUCCESS and echoes the lead ID. The lead is now in the active table and can be dialed again, the same way any other active record can.

The lead_id field itself accepts a wide range, 16 to 40 characters in the spec, which covers the long composite IDs some systems generate as well as plain numeric ones. Whatever form your IDs take, pass the value exactly as it appears in your archive export so the lookup matches on the first try.

How VICIdial decides what to do

flowchart TD
  A[lead_dearchive with lead_id] --> B{User has permission}
  B -->|No| C[ERROR no permission]
  B -->|Yes| D{Lead in archive table}
  D -->|No archived lead| E[ERROR archived lead not found]
  D -->|Already active| F[ERROR non-archived lead found]
  D -->|Yes| G[Copy lead to active list]
  G --> H[SUCCESS lead de-archived]

When to reach for it

Think of lead_dearchive as the counterpart to archiving during Lead recycling, the practice of re-dialing older records once your fresh data thins out. It pulls a single record back into the active Lead list so the dialer can pick it up again on the next pass.

Because the call works on one lead at a time, it suits event-driven use better than bulk reactivation. The classic case is a callback: a customer you parked in the archive months ago dials back in, your system spots their number, and you de-archive their record on the fly so the agent sees full history instead of a blank slate. For reactivating a whole campaign's worth of old data, you would loop this call per lead or work at the list level instead.

Once a lead is back in the active table, you will often want to adjust its status or other fields before dialing. That is a separate call - see our guide to update_lead for the editable fields.

For the full map of every back-office call, start with the VICIdial API and AGI overview. If you would rather skip running the server yourself, VICIfast gives you a managed VICIdial box with this API ready to call - see our plans to get a box in under 40 seconds.