Listing your campaigns with campaigns_list

campaigns_list gives you a roll-call of every campaign on the system in a single read-only call. It's the quickest way for a script to discover what campaigns exist, what dialing method each one uses, and what dial prefixes they're set to — without scraping the admin screen or querying the database directly.

What you need

Unlike the write functions, campaigns_list reads stats, so the API user needs a user_level of 8 or higher with "view reports" enabled. Only one field is required:

• source — a short label (max 20 characters) naming what made the call, for the logs.

Optionally, pass campaign_id (2 to 8 characters) to narrow the result to a single Campaign; leave it off to list them all. The stage field picks the format (csv, tab, json, or the default pipe), and header=YES adds a column header row.

If you're new to this endpoint, how to call the non-agent API covers the base URL and the user/pass pair.

Example calls

List every campaign:

http://your-server/vicidial/non_agent_api.php?source=test&function=campaigns_list&user=6666&pass=1234

List one campaign as CSV:

http://your-server/vicidial/non_agent_api.php?source=test&function=campaigns_list&campaign_id=TESTCAMP&user=6666&pass=1234&stage=csv

What comes back

A success response doesn't print SUCCESS — it prints one row per campaign. In default pipe format the columns are campaign_id, campaign_name, active, user_group, dial_method, dial_level, lead_order, dial_statuses, dial_timeout, dial_prefix, manual_dial_prefix and three_way_dial_prefix:

TESTCAMP|Test Campaign|Y|---ALL---|INBOUND_MAN|1|DOWN|PDROP DROP B NEW|65|9|9|9

That single line tells you a lot: the Dial method is INBOUND_MAN, the Dial level is 1, leads dial DOWN, and the Dial prefix is 9 (with separate prefixes for manual dials and 3-way transfers, all 9 here). Splitting on the pipe gives you a clean record per campaign.

Errors

• ERROR: campaigns_list USER DOES NOT HAVE PERMISSION TO GET CAMPAIGN INFO - 6666|0 — the API user lacks user_level 8 / view-reports.
• ERROR: campaigns_list THIS USER HAS NO VIEWABLE CAMPAIGNS - 6666 — the user has no campaigns in scope.

For more on parsing these strings reliably, see how to read VICIdial API responses.

How a list call flows

flowchart LR
  Script --> Endpoint
  Endpoint --> AuthCheck
  AuthCheck --> ViewReports
  ViewReports --> CampaignScan
  CampaignScan --> Format[stage format]
  Format --> Rows[One row per campaign]

Putting it to work

A common pattern is to call campaigns_list first to discover the IDs, then loop and call a write function on each. For example, list every campaign and then pause the inactive ones with update_campaign. For the full set of functions across the Non-agent API, read the VICIdial API and AGI overview.

Every VICIfast box ships online in under 40 seconds with this API enabled out of the box. Compare plans on the pricing page.