Deleting and resetting leads with update_lead options

Sometimes editing a lead is not enough. You need it gone, or you need the dialer to call it again from scratch. The same update_lead function from the Non-Agent API handles both, through a few extra options (Application Programming Interface) Non-agent API.

A lead is one calling record: a phone number and the data on it Lead. These options change the record's lifecycle rather than its contents, so they deserve a careful hand.

Deleting a lead

Pass delete_lead=Y and the matched record is removed from the vicidial_list table. If you also send custom_fields=Y, the custom field data tied to the lead goes with it. Add delete_cf_data=Y on its own to clear just the custom field values and reset the lead's entry list, leaving the main record in place.

curl "https://your-server/vicidial/non_agent_api.php?source=mycrm&user=6666&pass=1234&function=update_lead&lead_id=27&delete_lead=Y"

A successful delete returns the phone number, your API user, the list ID, the lead ID, and the offset:

SUCCESS: update_lead LEAD HAS BEEN DELETED - 7275551111|6666|999|193716|-4

Resetting a lead to dial again

Resetting is the gentler cousin of deleting. reset_lead=Y clears the called-since-last-reset flag on the lead, which is the marker that tells a campaign it has already touched this record. This is the same idea behind a list reset, where you make a whole list dialable again List reset. Once the flag is cleared, the campaign can pick the lead up on its next pass Campaign.

You can also nudge a lead's attempt count with called_count, an editable field holding the number of dialing attempts. Resetting the flag and adjusting that count together is a clean way to fold an old record back into rotation, which is a manual form of lead recycling, re-dialing records that did not connect the first time Lead recycling.

flowchart TD
  A[update_lead matched] --> B{Which option?}
  B -- delete_lead=Y --> C[Remove lead row]
  B -- delete_cf_data=Y --> D[Clear custom data only]
  B -- reset_lead=Y --> E[Clear called flag]
  E --> F[Campaign can dial again]
  C --> G[Lead gone permanently]

There are matching hopper options too: add_to_hopper=Y and remove_from_hopper=Y push a lead into or pull it out of the hopper, the short queue of leads waiting to be dialed next Hopper. A reset followed by an add-to-hopper gets a record back on the line quickly.

There is also a callback cleanup path. Passing callback=REMOVE deletes a scheduled callback entry tied to the lead, the saved appointment that tells VICIdial to ring this person back at a set time Scheduled callback. That is handy when a customer cancels: you pull the callback without touching the rest of the record, so the lead stays in your data but no longer rings an agent at the wrong moment.

Order matters when you combine options. A delete is final, so it overrides everything else in the same call; there is no point setting a status or a hopper flag alongside delete_lead=Y. For a reset, the safe pattern is to clear the flag and adjust the count, then queue the lead with the hopper flag. Keeping delete, reset, and edit as distinct intents makes your automation easier to reason about later, and easier to recover from when something goes sideways.

If you have not used the call before, start with how to change a lead with update_lead. For where it sits among all the API and AGI functions, read the VICIdial API and AGI overview.

Clean lifecycle control over your leads keeps your lists tidy and your dial rates honest. Every VICIfast plan hands you an API-ready dialer in under a minute, so you can script deletes and resets the day you go live.