Reading an agent's settings with user_details

Your CRM needs to know whether login 1234 is still an active account, what user group it belongs to, and what level it is. You do not want to write a database query and you do not want to open the admin screen. You just want to ask VICIdial. The user_details function answers exactly that question.

user_details is a read-only call in the Non-agent API (the back-office HTTP interface served by non_agent_api.php that manages records instead of driving live calls). It displays information about one user account and changes nothing. Think of it as the lookup that confirms what a settings change should be, or proves what it was.

Permissions and fields

The API user must have a user level of 7 or higher and the "view reports" permission enabled. That is a lower bar than the write calls, which makes sense: reading is safer than editing. Two fields matter. source is a short label (up to 20 characters) describing what made the call, and agent_user is the login you want to look up. Both are required.

Two optional settings shape the output. stage picks the format: csv, tab, json, or the default pipe. header set to YES prepends a row of column names, which is handy the first time you parse the result.

curl "http://server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=user_details&agent_user=1234&stage=csv&header=YES"

What comes back

A successful call does not print the word SUCCESS. It just returns the record. With a header and csv format you get:

user,full_name,user_group,user_level,active
11111,test user,ADMIN,6,Y

Five fields, and each is worth knowing. user is the login of the Agent (the person who handles calls). full_name is the display name. user_group is the User group (the permission bucket that decides which campaigns and reports the account can see). user_level is the 1-to-9 permission tier, and active is Y or N for whether the account can log in at all.

How the lookup resolves

flowchart TD
    A[Call user_details with agent_user] --> B{API user level 7 and view reports}
    B -- No --> C[Permission error]
    B -- Yes --> D{User found}
    D -- No --> E[USER NOT FOUND]
    D -- Yes --> F[Return user full_name user_group user_level active]

The errors are short and specific. USER DOES NOT HAVE PERMISSION TO GET USER DETAILS means the API account is missing the level or the report permission. INVALID SEARCH PARAMETERS means you left out a required field. USER NOT FOUND means the login does not exist. Match on the exact text rather than guessing, the way the VICIdial API and AGI overview recommends.

A common pattern is to call user_details right after you copy an account. The copy_user guide walks through cloning a template user; user_details is how you confirm the clone landed in the right group at the right level before anyone tries to log in.

It is a small call, but it is the one you lean on every time a script needs to check before it writes. Every VICIfast server has the API (application programming interface) (application programming interface, the URL contract your scripts call) enabled out of the box, so you can run this lookup on day one. See what each plan includes on our pricing page.