API user levels and permissions explained

You wrote a clean VICIdial API call, the URL looks right, and the only thing that comes back is a permission error. Nothing is broken — the user account simply is not allowed to run that function. Permissions in the Non-agent API come down to two things: a user level and a handful of access checkboxes. Get both right and the call goes through; miss either and you get turned away with no data at all.

What user_level means

Every VICIdial user has a user_level, a number from 1 to 9. A plain Agent sits low on that scale; an administrator sits at 9. Each API function names a minimum level it requires. Read-only sound and music lookups want level 7 or higher. Reporting functions such as listing campaigns want level 8 or higher. The numbers are not random — the more a function can read or change, the higher the level it asks for.

To make that concrete: pulling a list of audio files from the audio store requires level 7. Listing every campaign on the system requires level 8. Bulk-inserting leads into the Hopper requires level 8 as well. So a single API user set to level 7 could do the sound lookup but would be turned away from the campaign list.

If your user's level is below what a function asks for, you get a line like this and nothing else. The number after the dash is often the user level the account actually has, which is a quick way to confirm the cause:

ERROR: campaigns_list USER DOES NOT HAVE PERMISSION TO GET CAMPAIGN INFO - 6666|0

Level alone is not enough

A high level opens the door, but many functions also check a named permission on the account. Listing campaigns needs level 8 and the user's view reports box ticked. Looking up which campaigns an agent can join needs level 8 plus both view reports and modify users. Bulk-loading the Hopper needs modify campaigns turned on as well as level 8. The two requirements stack: you must clear the level bar and have the right box ticked, not one or the other.

How a call is judged

flowchart TD
    A[API call arrives] --> B{User is API enabled?}
    B -->|No| E[ERROR no permission]
    B -->|Yes| C{user_level high enough?}
    C -->|No| E
    C -->|Yes| D{Required checkbox ticked?}
    D -->|No| E
    D -->|Yes| F[Function runs]

Practical advice: do not hand your scripts an administrator account just to get past these checks. Make a dedicated API user, set its user_level to the lowest number every function you use will accept, and tick only the boxes those functions need. That way a leaked credential cannot do more than the script ever could. The same idea drives securing the VICIdial API.

For where these permission checks sit in the full API (application programming interface) picture, read the VICIdial API and AGI overview. On managed VICIfast servers you can spin up a scoped API user in the admin screen in minutes — see the pricing page.