Reading a list's details with list_info

When you want to know the state of a single lead list without opening the admin screen, list_info is the call to reach for. It returns a list's name, the campaign it belongs to, whether it's active, a few dates, and optionally a count of how many leads sit in it. It's read-only, so it's safe to poll from a dashboard or a cron job.

What you need first

list_info lives in the non_agent_api.php endpoint. It is part of VICIdial's Non-agent API — the server-to-server side of the API (application programming interface), as opposed to the agent-facing functions. The API user you authenticate with must have a user_level of 8 or higher and the "modify lists" permission enabled, or the call returns a permission error.

If you haven't made one of these calls before, start with how to call the non-agent API, which walks through the base URL, the user/pass pair, and the source parameter.

Required and optional fields

Two fields are mandatory:

• list_id — all numbers, 2 to 14 digits, the ID of the Lead list you want.
• source — a short label (max 20 characters) describing what made the call, so it shows up in logs.

A few optional toggles change what you get back. Set leads_counts=Y to append a total lead count and a NEW-status count. Set dialable_count=Y to use the campaign's settings and return how many leads are dialable right now. header=YES adds a header row, and stage sets the output format (csv, tab, json, or the default pipe).

An example call

http://your-server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=list_info&list_id=1101&leads_counts=Y&header=YES

A success response does not print the word SUCCESS. It just dumps the row. With leads_counts off you get a pipe-delimited line like this:

1101|performance list|TESTCAMP|Y|2019-09-02 08:52:50|2019-11-07 10:12:12|2099-12-31|0|

With leads_counts=Y, two more columns land on the end — the total count and the new-leads count:

1101|performance list|TESTCAMP|Y|2019-09-02 08:52:50|2019-11-07 10:12:12|2099-12-31|0|59896|3

Errors you'll hit

Every error line starts with ERROR and names the function, so they're easy to grep for:

• ERROR: list_info USER DOES NOT HAVE PERMISSION TO MODIFY LISTS - 6666 — the API user is missing the user_level 8 / modify-lists requirement.
• ERROR: list_info YOU MUST USE ALL REQUIRED FIELDS - 6666|1 — you left out list_id or source.
• ERROR: list_info NOT AN ALLOWED LIST ID - 98762 — the list_id is outside what this user may touch.
• ERROR: list_info LIST DOES NOT EXIST - 98762 — no list by that ID.

Because every response is one predictable line, parsing is trivial — split on the pipe and you're done. If you want a refresher on reading these strings cleanly, see how to read VICIdial API responses.

How the call flows

flowchart LR
  Caller --> Endpoint
  Endpoint --> AuthCheck
  AuthCheck --> Permission
  Permission --> ListLookup
  ListLookup --> Counts
  Counts --> Response

Where it fits

list_info pairs well with the write functions. A common pattern is to call list_info on a schedule, watch the new-leads count, and trigger a reload of your Campaign when the list runs low. Read the full picture of VICIdial's API surface in the VICIdial API and AGI overview.

Every VICIfast box ships with this API enabled and a server that's online in under 40 seconds, so you can script against it the moment you provision. Compare what's included on each plan on the pricing page.