VICIDIAL READ-ONLY API EXAMPLE — 2026-11-06
Python 3 on Linux/macOS. Standard library only. Read the script before running.
Download user-details.py and user-details-fictional.csv into one local directory.

Offline rehearsal (no credentials/network):
python3 user-details.py validate --response user-details-fictional.csv --target vgtest01
Expected: five fields for the fictional target, level 1, active N. This fixture is not a captured server response.

Live prerequisites: an approved HTTPS lab endpoint with a trusted certificate, its installed Non-Agent API reference, a dedicated API account authorized only for this exercise, and an existing synthetic target visible in Admin. The official user_details function requires caller user_level >=7 and View Reports enabled; the owner must also review the installation's API access and allowed-function restrictions. Do not enable broad access to overcome a rejection.
In Users -> Show Users, open the synthetic target and record its User, Full Name, User Group, User Level and Active values privately.

Prepare a new protected credential file:
python3 user-details.py prepare
The prompts collect endpoint, API username, synthetic target username and a hidden password. The script creates ~/.config/vicigeek-api/credentials.json with mode 0600 under a directory with mode 0700. It refuses to overwrite an existing credential file. The endpoint must end in /vicidial/non_agent_api.php and contain no credentials, query or fragment. No network request occurs during prepare.
To keep multiple reviewed configurations use --credentials /your/private/directory/credentials.json with BOTH prepare and read. Directory must be owned by you and private. Do not store it in a repository, web root, screenshot or shared folder.

Send one read-only request:
python3 user-details.py read
It posts function=user_details, agent_user=your synthetic target, stage=csv, header=YES and source=vicigeek-read. Credentials are read from the private file and sent in the HTTPS request body. There is no retry, redirect following or TLS bypass. Transport timeout is 20 seconds; the single-record response is limited to 64 KiB.
Success requires exactly the expected five-column CSV header, one row, the requested username, a numeric user level and Y/N active value. Compare ALL five fields with the separately reopened Admin record. HTTP 200 or a version response is insufficient. A matching read does not establish access to any write function or agent operation.

Failure: DNS/TLS/timeout -> endpoint or network owner; HTTP/redirect -> confirm direct API path; authentication/permission -> account owner; missing target -> check synthetic ID; unexpected schema/extra row -> compare installed documentation and keep result unaccepted. Do not print or submit raw response bodies from real accounts.

After the exercise, retain the credential file only under your credential policy or remove the exact file you created and ask the account owner to revoke/rotate temporary access. Removing a local file does not revoke the server account. This example does not create accounts or mutate VICIdial.