Automate tasks · API boundaries

Choose a VICIdial API and verify one read-only request

Choose the exact function, create a protected local credential file and compare a user_details response with a synthetic Admin record.

Start the guide

By Vicigeek Editorial DeskStep-by-step guide6 minute readUpdated November 6, 2026

01 / 06

1. Choose by the exact operation

Find the function in the reference shipped with your installed revision. The table gives starting points, not blanket permission for all functions on either endpoint. Read functions can have different account requirements.

Agent endpoint: /agc/api.php
Non-Agent endpoint: /vicidial/non_agent_api.php
Installed reference: Ask the installation owner for AGENT_API.txt and NON-AGENT_API.txt from the deployed revision; record the API build with the exercise

Function choices and permission boundariesScroll sideways to compare columns
Job	Endpoint / function	Context and effect
Inspect one synthetic user	Non-Agent / user_details	Caller level ≥7 and View Reports; installation API restrictions also apply. Reads a user record.
Count calls eligible for an agent	Agent / calls_in_queue_count	Authorized logged-in agent context and DISPLAY value. Reads eligible queued calls, not hopper inventory.
Add a lead	Non-Agent / add_lead	Documented level ≥8 and Modify Leads permission. Writes data; outside this exercise.
Pause a logged-in agent	Agent / external_pause	Agent API permission and appropriate session state. Changes live session; outside this exercise.

You should seeThis walkthrough selects Non-Agent user_details. It uses no logged-in agent, lead or call.

02 / 06

2. Rehearse the complete example without a server

Download the Python script and fictional response CSV into one local directory. Open a terminal in that directory. The script uses only the Python 3 standard library; no package installation is required. Read the downloaded source before running it.

The CSV is a made-up response with the documented five-column shape. It is not a screenshot or capture from the lab. The offline check proves parser behavior against a fixture, not server access.

Before you use it: Download both named files to the current directory. This command makes no network request.

python3 user-details.py validate \  --response user-details-fictional.csv \  --target vgtest01

Evidence · Author-provided captured transcript

Captured demo response · Capture date is documented with the article evidence.. Any filtering, hidden values or test-only data are identified in the capture label. Select Replay transcript to read the recorded output.

One matching user_details record (compare every field with Admin):

user: 'vgtest01'

full_name: 'Fictional API target'

user_group: 'LABGROUP'

user_level: '1'

active: 'N'

This read does not verify write permissions, an agent session, or call handling.

Success looks like: The script prints the five fictional fields for vgtest01, including User Level 1 and Active N.
Stop if: If Python is unavailable, install it through your workstation’s approved process. A malformed response or a different target is rejected.

Expected fictional record for the offline exerciseScroll sideways to compare columns
Field	Fictional value
user	vgtest01
full_name	Fictional API target
user_group	LABGROUP
user_level	1
active	N

You should seeThe fixture parses only when its header, single record and target agree. The value of Active N belongs to the synthetic target; it is not an instruction to disable an API account.

Complete read-only request script (Python)

Fictional response fixture (CSV)

Full setup, run and failure instructions (TXT)

03 / 06

3. Confirm the live account and target before sending anything

With the installation owner, open Users → Show Users and inspect the dedicated API account. For user_details the official reference requires User Level 7 or higher and View Reports enabled. Also check the installation’s API access and API Allowed Functions controls for this exact function; do not widen access merely to silence an error.

Open the existing synthetic target separately and record its saved five fields privately. The API caller and the requested target are separate roles. No target is created by the script. If you cannot inspect a suitable existing target or obtain narrowly approved access, stop at the offline exercise and hand the prerequisite to the owner.

Record the installed API build and the matching user_details reference section with the owner. Confirm CSV and header=YES are supported.
Obtain the approved direct HTTPS Non-Agent endpoint with a certificate trusted by the workstation. Do not use a browser URL carrying user or pass query parameters.
Reopen the synthetic target’s saved Admin record. Record User, Full Name, User Group, User Level and Active for the independent comparison.

Native API Allowed Functions list with user_details visible and unselected on the synthetic API account. — Saved native permission row from the synthetic lab account, November 6, 2026, 21:59–22:06 UTC; Admin 2.14-969a, SVN 4037.
Capture details
Only the listbox was scrolled; no value was changed or submitted. The separate user_details request was denied. This is not a successful API response.

You should seeThe account owner has confirmed function access and the target record exists. A permission screenshot alone does not establish a successful request.

04 / 06

4. Create the protected credential file

Run prepare in your local download directory. Enter the approved full endpoint, dedicated API username, existing synthetic target username and password at the prompts. The password prompt is hidden. Do not substitute the fictional target unless your administrator actually created that target.

The script creates ~/.config/vicigeek-api/credentials.json as your mode-0600 file under a mode-0700 directory. It refuses to overwrite an existing credential file or use a shared credential directory. No network request is sent by prepare.

Endpoint input: https://YOUR-APPROVED-HOST/vicidial/non_agent_api.phpReplace the whole host with the certificate-matching hostname supplied by the owner; no query string or URL credentials.
Local file contents: endpoint, user, target and passThe script serializes the prompt values as JSON; no manual password escaping is required.

Before you use it: Use the Linux/macOS workstation that will make the request; collect the approved endpoint/account/target first.

python3 user-details.py prepare

Reader-run example · not executed for this guide

This example has no recorded result here. Follow its preparation, expected result and stop conditions before using it.

Success looks like: The script reports that a private credential file was created. The password was entered at the prompt, not placed in shell history.
Stop if: If the file exists, inspect it privately or use a new --credentials path for BOTH prepare and read. Never paste it into a support ticket or repository.

You should seeYou have one private file for this specific read. File creation has not authenticated the account or contacted VICIdial.

05 / 06

5. Send one read and inspect its actual result

Run read once. The script sends an HTTPS form POST with function=user_details, agent_user set to your synthetic target, stage=csv, header=YES and source=vicigeek-read. Credentials are loaded from the private file and sent in the request body. It does not follow redirects, retry, bypass TLS or call a write function.

The response is accepted only with the exact documented header, one record, the requested username, numeric User Level and Y/N Active value. HTTP 200, a version response or the absence of ERROR is insufficient. A returned row is still subject to the independent check below.

Observed lab boundary, November 6, 2026: a separate read-only user_details request using the existing synthetic API account returned HTTP 200 with “ERROR: auth USER DOES NOT HAVE PERMISSION TO USE THIS FUNCTION”. The account had API access, level 8 and View Reports, but user_details was absent from its allowed functions. Permissions were not changed. This verifies the rejection branch, not a successful read or execution of the downloadable Python helper against the server.

Before you use it: Complete the permission/target checks and prepare step. Keep the terminal private because the successful response displays the chosen synthetic record.

python3 user-details.py read

Reader-run example · not executed for this guide

This example has no recorded result here. Follow its preparation, expected result and stop conditions before using it.

Success looks like: The five returned fields match the separately reopened Admin target. The script reports that write permissions and call handling were not tested.
Stop if: Use the failure table. Stop on any rejected or unexpected result rather than changing the request to a write or bypassing TLS.

Interpret the result and choose the next actionScroll sideways to compare columns
Observed result	Meaning	Next action
Network/TLS/timeout failure	No accepted API result	Check endpoint, DNS, reachability and certificate trust with the owner
HTTP error or redirect	Direct API response not obtained	Confirm the exact HTTPS script path; the client does not forward credentials through redirects
Authentication or permission rejection	Caller is not accepted for this request	Have the account owner check credentials and function-specific restrictions
Target user not found	The requested synthetic record was not returned	Reopen Users and compare the exact target ID
Wrong header, extra row or different user	Response fails this function contract	Compare installed documentation and keep the result unaccepted
One matching five-field record	Bounded read returned the expected target	Compare all five values with Admin before marking complete

You should seeRecord completion only after all five values match independently. A successful read says nothing about lead writes or a logged-in agent session.

06 / 06

6. Finish with a bounded evidence record

Record the installed build, test time/timezone, function, response class and whether the independent five-field comparison passed. Keep credentials and raw account records out of screenshots or shared logs.

If unresolved, hand the account owner the failure category and the prerequisite that could not be checked. After the exercise, follow the credential policy for retaining or removing the exact local file and revoking temporary API access. Removing the file does not revoke the server account.

Use Test a VICIdial Agent API request for a separate agent-session task and Check VICIdial Non-Agent API access for other documented reads. A future write needs its own before/after state, retry reconciliation and recovery procedure; this read example is not a general success parser.

You should seeThe end state is either a verified read of one synthetic user or a specific unresolved transport, access, target or response-contract problem.

Checks and sources

What was checked

The current instructional body is owned by the practical data/integrations guide; it supplies a complete downloadable read-only script and a fictional parser fixture.
The fictional response/parser exercise was checked locally. A separate real lab request on November 6 returned HTTP 200 with a user_details permission rejection; its native permission row is shown. Neither a successful live read nor an on-server test of the downloadable helper is claimed.
Official API behavior was reviewed November 6, 2026. Each installation still requires its own matching reference, account permissions and independent target comparison.

Primary references

Sources

VICIdial Agent API referenceVICIdial Group · accessed November 6, 2026
VICIdial Non-Agent API referenceVICIdial Group · accessed November 6, 2026
Python urllib.request documentationPython Software Foundation · accessed November 6, 2026