How to update many leads at once with batch_update_lead

You need to move a few hundred leads to a different list, or stamp the same status on a whole batch. Firing one update_lead call per record works, but it is slow and noisy. The batch_update_lead function from the Non-Agent API does the whole group in one shot (Application Programming Interface) Non-agent API.

The idea is simple. You hand it a comma-separated list of lead IDs and one set of field values, and it writes those same values onto every matching lead. A lead is a single calling record, a phone number plus its data Lead. The trade-off for speed is that you apply identical changes to all of them.

The shape of the call

Two things are required: source, your short call label, and lead_ids, the comma-separated IDs (numbers only). Then you add the editable fields you want set. Here we move two leads into list 138 using list_id_field:

curl "https://your-server/vicidial/non_agent_api.php?source=mycrm&user=6666&pass=1234&function=batch_update_lead&lead_ids=2345,2346&list_id_field=138"

A clean run returns your API user, the count of leads updated, and the IDs that changed:

SUCCESS: batch_update_lead LEADS HAVE BEEN UPDATED - 6666|2|2345,2346

The editable fields cover the usual record data: name, address, email, status Status (lead status), vendor_lead_code Vendor lead code, and the list_id_field that decides which lead list each record belongs to Lead list. You can also set reset_lead=Y to clear the called flag across the batch.

How the batch flows

sequenceDiagram
  participant App as Your App
  participant API as non_agent_api.php
  participant DB as vicidial_list
  App->>API: batch_update_lead lead_ids + values
  API->>DB: find which lead_ids exist
  DB-->>API: matching leads
  API->>DB: UPDATE all matched at once
  API-->>App: SUCCESS count + lead_ids

Two more guards. records caps how many leads the call will touch, defaulting to 100 (the most recently created), so a huge ID list will not run away on you. And list_exists_check=Y makes the call error out instead of moving leads into a list_id_field that does not exist on the system yet.

Think about which fields make sense to set in bulk. Moving leads between lists, stamping a shared status, or tagging a group with the same source identifier all fit, because the value really is the same for every record. Anything that should differ per lead, like a name or an email, does not belong in a batch call, since one value would overwrite all of them. For per-record edits, the single-lead update is the right tool.

Read the error lines carefully, because a batch can fail as a whole. NO LEADS FOUND means none of your IDs matched, so nothing changed. NOT AN ALLOWED LIST ID means the API user is not permitted to write into the target list. And the permission error appears the moment the user lacks modify_leads or a high enough user level. None of these partially apply the change, so a clean success line is your signal that the whole set went through.

If you only need to change one record, the single-lead version is simpler; see how to change a lead with update_lead. For where batch updates sit among the full set of functions, read the VICIdial API and AGI overview.

Bulk changes are where the API saves you real hours instead of minutes. Every VICIfast plan gives you an API-ready VICIdial box in under a minute, ready for your first batch_update_lead run.