How to create a calling list with the add_list API

Before a single number gets dialed, it has to live in a list. A list is the container that holds leads and ties them to a campaign. You can create one by hand in the admin screen, but if you load fresh data on a schedule it is far easier to script it. The add_list function creates a new list over HTTP and lets you set its campaign, caller ID, and more in the same call.

What a list is

A Lead list groups Lead records under a single list ID and points them at a Campaign. When the dialer is running, leads from the active lists feed into the Hopper, the short queue of numbers that are next to be called. So creating a list is step one of getting data into the dialer. This call runs through the Non-Agent API, the administrative HTTP endpoint.

Permissions

The API user must have user_level set to 8 or higher and "modify lists" enabled. Note this is a different permission than the phone calls use, so check that the "modify lists" box is ticked on your API account. If you want to copy custom fields during creation, the user also needs "Custom Fields Modify" enabled.

Required fields

• list_id — 2 to 14 digits, the unique ID for the new list
• list_name — 2 to 30 characters
• campaign_id — 2 to 8 characters, must be a valid campaign

Useful optional fields

Everything past the three required fields is optional. A few worth knowing:

• active — Y or N, defaults to N so a fresh list does not dial until you turn it on
• outbound_cid — 6 to 20 digits, the caller ID for this list
• script — 1 to 10 characters, must be a valid script
• reset_time — valid 4-digit groups of 24-hour time, e.g. 0900-1700-2359
• custom_fields_copy — a valid list ID whose custom fields should be copied here

The reset_time field controls automatic list resets. A List reset clears the called flag on every lead so the list can be dialed again from the top. The custom_copy_method field decides how copied fields merge, and APPEND is the only fully safe choice since it never deletes existing data.

An example call

The simplest version needs only the three required fields:

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

A fuller one sets caller ID, a script, and an answering-machine message:

http://your-server/vicidial/non_agent_api.php?source=test&function=add_list&user=6666&pass=1234&list_id=1101&list_name=Test+API+list&campaign_id=TESTCAMP&active=N&outbound_cid=7275551212&script=DEMOSCRIPT&am_message=8304&drop_inbound_group=SALESLINE

On success you get:

SUCCESS: add_list LIST HAS BEEN ADDED - 6666|1101|TESTCAMP

How the function validates input

flowchart TD
  A[Call add_list] --> B{User level 8 plus modify lists?}
  B -- no --> C[ERROR no permission]
  B -- yes --> D{Required fields present?}
  D -- no --> E[ERROR must use all required fields]
  D -- yes --> F{Campaign exists?}
  F -- no --> G[ERROR campaign does not exist]
  F -- yes --> H{list_id already used?}
  H -- yes --> I[ERROR list already exists]
  H -- no --> J[SUCCESS list has been added]

Errors to expect

• ERROR: add_list USER DOES NOT HAVE PERMISSION TO ADD LISTS - 6666|0
• ERROR: add_list CAMPAIGN DOES NOT EXIST - 6666|TESTCIMP
• ERROR: add_list LIST ALREADY EXISTS - 6666|1101
• ERROR: add_list SCRIPT DOES NOT EXIST, THIS IS AN OPTIONAL FIELD - 6666|TESTSCRIPT

The "optional field" errors are worth reading carefully: the list itself was not created because one of your optional values is wrong, so fix the value and resend. For a deeper look at parsing these strings, see how to read VICIdial API responses.

Next steps

Once the list exists, you load leads into it with add_lead and change its settings later with update_list. To change a list after creating it, see changing list settings with update_list. A VICIfast server is provisioned and API-ready in under 40 seconds, so you can script your list loading the same day. See our pricing to get one running.