Changing list settings with update_list

Lists change all the time: you move one to a different campaign, switch it off for the night, reset it to call from the top again, or clear it out completely. The update_list function does all of that over HTTP. It edits the row in the vicidial_lists table and, with a couple of flags, can reset or delete the list and its leads.

What update_list covers

This is the edit-side companion to add_list. You point it at an existing Lead list by its ID and send the settings you want to change: the Campaign it belongs to, its active flag, the caller ID, the script, and more. It runs through the Non-Agent API, the administrative HTTP endpoint. There is also a handy insert_if_not_found flag: set it to Y and if the list ID does not exist yet, the call quietly hands off to add_list and creates it.

Permissions

The API user must have user_level set to 8 or higher and "modify lists" enabled, the same permission add_list needs. This call is part of the Non-agent API set, so a leftover source label and your API credentials are all you need beyond the list ID.

Required fields

• list_id — all numbers, 2 to 14 digits
• source — a description of what originated the call, maximum 20 characters

Note that source is a required field here, not just a label of convenience. For more on it, see the VICIdial API source parameter.

The settings flags

• reset_list — Y or N, resets the Called-Since-Last-Reset flag on every lead in the list
• delete_list — Y or N, removes the list from vicidial_lists
• delete_leads — Y or N, deletes all leads carrying this list_id

Setting reset_list to Y performs a List reset so the dialer treats every lead as fresh again. Be careful with delete_leads: it removes the lead records, not just the list shell, and these tables do not roll back partial changes.

Example calls

Rename a list:

http://your-server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=update_list&list_id=1101&list_name=Updated+test+API+list

Switch a list off:

http://your-server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=update_list&list_id=1101&active=N

Reset a list so it dials from the top again:

http://your-server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=update_list&list_id=1102&reset_list=Y

Move a list to a different campaign:

http://your-server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=update_list&list_id=1102&campaign_id=ASTRICON

How update_list decides what to do

flowchart TD
  A[Call update_list] --> B{User level 8 plus modify lists?}
  B -- no --> C[ERROR no permission]
  B -- yes --> D{list_id and source present?}
  D -- no --> E[ERROR must use all required fields]
  D -- yes --> F{List exists?}
  F -- no --> G{insert_if_not_found equals Y?}
  G -- yes --> H[Hand off to add_list]
  G -- no --> I[ERROR list does not exist]
  F -- yes --> J{Any updates defined?}
  J -- no --> K[NOTICE no updates defined]
  J -- yes --> L[Apply changes]

Responses to watch for

• ERROR: update_list USER DOES NOT HAVE PERMISSION TO UPDATE LISTS - 6666
• ERROR: update_list LIST DOES NOT EXIST - 6666|1000
• NOTICE: update_list LIST DOES NOT EXIST, SENDING TO add_list FUNCTION - 6666|1000
• ERROR: update_list CAMPAIGN DOES NOT EXIST, THIS IS AN OPTIONAL FIELD - 6666|TESTCIMP
• NOTICE: update_list NO UPDATES DEFINED - 6666|

The NOTICE about no updates means the list exists and your credentials are fine, but you did not send a single editable field, so nothing changed. The "sending to add_list" notice is what you see when insert_if_not_found created the list for you.

Related reading

If the list does not exist yet, start with creating a calling list with add_list. Wired into a nightly job, update_list keeps your campaigns clean: deactivate finished lists, reset the ones that recycle, and remove stale data without touching the admin screen. A VICIfast box is API-ready in under 40 seconds. See our pricing to get started.