How to change an existing lead with the update_lead API

A customer's last name was misspelled, or their status changed in your own system, and you need VICIdial to match. Rather than open the admin screen, you can patch the record over HTTP with update_lead, part of the Non-Agent API (Application Programming Interface) Non-agent API.

Where add_lead inserts a new record, update_lead changes one that already exists. A lead is a single calling record, a phone number plus the data attached to it Lead. The call edits the row in the vicidial_list table and, if you ask, the custom fields with it.

Finding the right lead first

Before it can change anything, the call has to find the record. You have three ways to match. The simplest is lead_id, VICIdial's own row number. You can also match on vendor_lead_code, your outside identifier for the record Vendor lead code, or on phone_number. The search_method setting picks which of these to try, and you can combine them, for example search_method=LEAD_ID_VENDOR_LEAD_CODE.

The search_location setting controls how far to look: LIST stays inside one lead list, the named bucket of records a campaign dials Lead list; CAMPAIGN spans every list in that campaign, the outbound job dialing them Campaign; and SYSTEM searches everything, which is the default.

Match, then write

sequenceDiagram
  participant App as Your App
  participant API as non_agent_api.php
  participant DB as vicidial_list
  App->>API: update_lead match field + new values
  API->>DB: find lead by search_method
  DB-->>API: matching lead_id
  API->>DB: UPDATE changed fields
  API-->>App: SUCCESS lead has been updated

Once it has a match, you pass the fields you want changed. To change a last name on lead 27:

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

A clean run returns one line with your API user and the lead ID that changed:

SUCCESS: update_lead LEAD HAS BEEN UPDATED - 6666|193716

You can update most lead fields this way: name, address, email, status, and the disposition-style status value Status (lead status). To set a field to empty rather than skip it, pass the literal --BLANK--, as in &province=--BLANK--. Avoid apostrophes, quotes, and ampersands in your values.

There is a handy safety move: no_update=Y runs the search but changes nothing, so you can confirm a lead exists before you write. And insert_if_not_found=Y will add the lead as new when no match turns up, which lets one call act as an upsert.

A couple of fields are worth calling out because their names differ from add_lead. To move a lead to a different list you use list_id_field, and to change which user owns the record you use user_field. The phone number itself is not editable unless you also pass update_phone_number=Y, which is a guard against changing the very value you might be matching on by accident.

The match response gives you more than a yes or no. When no_update=Y finds records, it prints the user, lead ID, vendor lead code, phone number, list ID, and entry list ID for each one, so you can confirm you are about to edit the right lead before you commit to a real write. That makes update_lead safe to wire into an automated sync, where you check first and write second.

The same call can also delete or reset records. For those options, see deleting and resetting leads with update_lead. For where update_lead fits among every API and AGI function, read the VICIdial API and AGI overview.

Keeping VICIdial in step with your source system is what makes the API worth wiring up. Every VICIfast plan ships an API-ready dialer in under a minute, so your first update_lead call can go out today.