Users & Agents Endpoints

Users & Agents

---

Users

GET /Users

Summary: List of Users

Description: Returns multiple Users. Requires authentication.

Query Parameters:

Name	Type	Description
activeinactive	string	Two comma-separated values: first sets includeactive, second sets includeinactive
advanced_search	string	Advanced search filter
allapprovers	boolean	Adds an OR condition to show all Users that are approvers
approvers_only	boolean	Include only users that are an approver
asset_id	integer	Filter by Users assigned to a particular asset
client_id	integer	Filter by Users belonging to a particular client
contract_id	integer	Filter by Users assigned to a particular device application type
count	integer	When not using pagination, the number of results to return
department_id	integer	Filter Users belonging to a particular department
exclude_agents	boolean	Exclude users that are also an agent
exclude_defaultsiteusers	boolean	Exclude default site users
exclude_generaluser	boolean	Exclude general users
idonly	boolean	Returns only the ID field (not compatible with Pagination)
includeactive	boolean	Include users that are active
includebillinginfo	boolean	Include billing information
include_custom_fields	string	Comma-separated list of Custom Field IDs to include
includeinactive	boolean	Include users that are inactive
includename	boolean	Include name field
includenonserviceaccount	boolean	Include users that are a non-service account
includenotes	boolean	Include user notes
includeserviceaccount	boolean	Include users that are a service account
integration_type	string	Filter by integration: okta or azure
is_followers	boolean	Filter followers
is3cxcall	boolean	3CX call filter
lastupdatefromdate	boolean	Include lastupdatefromdate field
lastupdatetodate	boolean	Include lastupdatetodate field
licence_id	integer	Filter by licence ID
listagentuserfirst	boolean	Order users that are also agents first
myallcustomers	boolean	Include all customers
myarea	boolean	Include only Users that belong to your area
mydepartment	boolean	Include only Users that belong to your department
mysite	boolean	Include only Users that belong to your site
mysitecontact	boolean	Include only Users that belong to your site contact
mytoplevel	boolean	Include only Users that belong to your top level
opp_id	integer	Filter by Users assigned to a particular opportunity
order	string	Field name to order by (first)
order2	string	Field name to order by (second)
order3	string	Field name to order by (third)
order4	string	Field name to order by (fourth)
order5	string	Field name to order by (fifth)
orderdesc	boolean	Order descending on first order field
orderdesc2	boolean	Order descending on second order field
orderdesc3	boolean	Order descending on third order field
orderdesc4	boolean	Order descending on fourth order field
orderdesc5	boolean	Order descending on fifth order field
organisation_id	integer	Filter by Users belonging to a particular organisation
page_no	integer	Page number when using pagination
page_size	integer	Page size when using pagination
pageinate	boolean	Whether to use pagination
role	integer	Filter by role ID
search	string	Filter by Users matching the search string
search_phonenumbers	boolean	Filter by Users with a matching phone number
site_id	integer	Filter by Users belonging to a particular site
supplier_id	integer	Filter by Users belonging to the specified supplier
tickettype_id	integer	Filter by ticket type
toplevel_id	integer	Filter by Users belonging to a particular top level
linked_to_user_id	integer	Filter by Users linked to the specified User ID

Response: 200 OK — Array of Users_View objects

---

POST /Users

Summary: Create User(s)

Request Body: Array of Users objects

Response: 201 Created — Users object

---

GET /Users/{id}

Summary: Get one User

Description: Returns a single User instance. Requires authentication.

Path Parameters:

Name	Type	Required	Description
id	integer	Yes	User ID

Query Parameters:

Name	Type	Description
client_id	integer	Filter by the specified client
client_override	integer	Client override
domain	string	Filter on site permissions — opps defaults to user opportunities
includeactivity	boolean	Include site ticket activity
includebillinginfo	boolean	Include billing information
includedetails	boolean	Include extra objects
includepopups	boolean	Include customer pop-ups
includeusersassets	boolean	Include user assets
issetup	boolean	Setup mode flag
opp_id	integer	Filter by User assigned to a particular opportunity
site_id	integer	Filter by the specified site
site_override	integer	Site override
supplier_id	integer	Filter by the specified supplier
tickettype_id	integer	Filter by ticket type
username	string	Filter by the specified username

Response: 200 OK — Users object

---

DELETE /Users/{id}

Summary: Delete a User

Path Parameters:

Name	Type	Required	Description
id	integer	Yes	User ID

Response: 200 OK

---

GET /Users/me

Summary: Get the currently authenticated User

Response: 200 OK — Users object

---

POST /Users/prefs

Summary: Update User Preferences

Request Body: Array of UserPrefs objects

Response: 200 OK

---

Agent (Uname)

Note: The HaloPSA API uses "Uname" as the internal schema name for Agent objects.

GET /Agent

Summary: List of Agents

Description: Returns multiple Agents. Requires authentication.

Query Parameters:

Name	Type	Description
activeinactive	string	Two comma-separated values: first sets includeactive, second sets includeinactive
appointmentscreen	boolean	Appointment screen filter
basic_fields_only	boolean	Reduces the number of fields returned
can_edit_only	boolean	Filter on Agents you have permission to edit
client_id	integer	Filter by Agents belonging to a particular client
clientidoverride	string	Client ID override
department_id	integer	Filter by Agents belonging to a particular department
departments	string	Comma-separated department filter
domain	string	Filter on Agent permissions: opps, prjs, reqs
exchangecalendars	boolean	Filter on Agents that have exchange calendars synced
exclude_membership_info	boolean	Remove team and department membership information from response
excludeAgent	integer	Exclude agent with this ID
forcequalmatch	boolean	Force qualification match
include_membership_info	boolean	Always include team and department membership information
includeapiagents	boolean	Include API agents
includedisabled	string	Include Agents that are inactive
includeenabled	string	Include Agents that are active
includenamedcount	boolean	Include count of the number of Agents
includeroles	boolean	Include Agent roles
includestatus	boolean	Include Agent status
includeunassigned	string	Include the unassigned Agent
is_agent_cache	boolean	Special behaviour for Agent app Agent Cache build
integration_type	string	Filter on Agents that belong to an integration — okta
linemanagedonly	boolean	Filter on Agents that have a line manager
linkingagents	boolean	Linking agents filter
loadcache	boolean	Load from cache
onlinestatuses	string	Comma-separated online status filter
order	string	Field name to order by (first)
order2	string	Field name to order by (second)
order3	string	Field name to order by (third)
order4	string	Field name to order by (fourth)
order5	string	Field name to order by (fifth)
orderdesc	boolean	Order descending on first order field
orderdesc2	boolean	Order descending on second order field
orderdesc3	boolean	Order descending on third order field
orderdesc4	boolean	Order descending on fourth order field
orderdesc5	boolean	Order descending on fifth order field
page_no	integer	Page number when using pagination
page_size	integer	Page size when using pagination
pageinate	boolean	Whether to use pagination
qualifications	string	Comma-separated qualification filter
reassign	boolean	Filter on Agents that can assign to Agents in sections they are not a member of
remoteagents	boolean	Filter on Agent invite permissions
remoteagenttype	string	Remote agent type: beyondtrust or logmein
role	string	Filter by Agents with a particular role (pass int as string)
search	string	Filter by Agents with a matching name, email, or telephone number
shiftagentsonly	boolean	Shift agents only
showall	boolean	Override org restrictions for main search (admin only)
showcounts	boolean	Include Agents ticket counts
team	string	Filter by Agents within a particular team
team_id	integer	Filter by Agents within a particular team ID
teams	string	Comma-separated team filter
thisAgentOnly	boolean	Only include your agent
ticketarea_id	integer	For showcounts — ticket area filter
tickettype_id	integer	Filter by Agents that have access to particular ticket types
view_id	integer	For showcounts — ticket view filter
withemail	boolean	Filter on Agents that have an email

Response: 200 OK

---

POST /Agent

Summary: Create Agent(s)

Request Body: Array of Uname objects

Response: 200 OK

---

GET /Agent/{id}

Summary: Get one Agent

Description: Returns a single Agent instance. Requires authentication.

Path Parameters:

Name	Type	Required	Description
id	integer	Yes	Agent ID

Query Parameters:

Name	Type	Description
clientidoverride	string	Client ID override
get_htmldesigner_signature	boolean	Include HTML designer signature
getholidayallowance	boolean	Include holiday allowance
includedetails	boolean	Include extra objects
isagentconfig	boolean	Agent config mode
loadcache	boolean	Load from cache

Response: 200 OK

---

DELETE /Agent/{id}

Summary: Delete an Agent

Path Parameters:

Name	Type	Required	Description
id	integer	Yes	Agent ID

Response: 200 OK

---

GET /Agent/me

Summary: Get the currently authenticated Agent

Response: 200 OK

---

POST /Agent/ClearCache

Summary: Clear the Agent cache

Response: 200 OK

---

GET /AgentImage/{id}

Summary: Get Agent profile image

Description: Returns a single Agent image. Requires authentication.

Path Parameters:

Name	Type	Required	Description
id	string	Yes	Agent ID

Query Parameters:

Name	Type	Description
clientidoverride	string	Client ID override
get_htmldesigner_signature	boolean	Include HTML designer signature
getholidayallowance	boolean	Include holiday allowance
includedetails	boolean	Include extra objects
isagentconfig	boolean	Agent config mode
loadcache	boolean	Load from cache

Response: 200 OK

---

AgentEventSubscription (UnameEventSubscription)

GET /AgentEventSubscription

Summary: List Agent Event Subscriptions

Response: 200 OK

---

POST /AgentEventSubscription

Summary: Create Agent Event Subscription(s)

Request Body: Array of UnameEventSubscription objects

Response: 200 OK

---

GET /AgentEventSubscription/{id}

Path Parameters:

Name	Type	Required	Description
id	integer	Yes	Subscription ID

Response: 200 OK

---

DELETE /AgentEventSubscription/{id}

Path Parameters:

Name	Type	Required	Description
id	integer	Yes	Subscription ID

Response: 200 OK

---

Notification (UnameNotification)

GET /Notification

Summary: List of Notifications

Description: Returns multiple Notifications. Requires authentication.

Query Parameters:

Name	Type	Description
agent_id	integer	Filter by agent ID
restrictto_agent_id	integer	Restrict to a specific agent
role_id	string	Filter by role ID
showall	boolean	Show all notifications
type	integer	Filter by notification type
webhook_id	string	Filter by webhook ID

Response: 200 OK

---

POST /Notification

Summary: Create Notification(s)

Request Body: Array of UnameNotification objects

Response: 200 OK

---

GET /Notification/{id}

Summary: Get one Notification

Description: Returns a single Notification instance. Requires authentication.

Path Parameters:

Name	Type	Required	Description
id	integer	Yes	Notification ID

Query Parameters:

Name	Type	Description
includedetails	boolean	Include extra details

Response: 200 OK

---

DELETE /Notification/{id}

Path Parameters:

Name	Type	Required	Description
id	integer	Yes	Notification ID

Response: 200 OK

---

AgentPresenceRule (UnamePresenceRule)

GET /AgentPresenceRule

Summary: List Agent Presence Rules

Response: 200 OK

---

AgentPresenceSubscription (UnamePresenceSubscription)

GET /AgentPresenceSubscription

Summary: List Agent Presence Subscriptions

Response: 200 OK

---

POST /AgentPresenceSubscription

Summary: Create Agent Presence Subscription(s)

Request Body: Array of UnamePresenceSubscription objects

Response: 200 OK

---

GET /AgentPresenceSubscription/{id}

Path Parameters:

Name	Type	Required	Description
id	integer	Yes	Subscription ID

Response: 200 OK

---

DELETE /AgentPresenceSubscription/{id}

Path Parameters:

Name	Type	Required	Description
id	integer	Yes	Subscription ID

Response: 200 OK

---

UserChange

GET /UserChange

Summary: List of UserChange records

Description: Returns multiple UserChange records. Requires authentication.

Query Parameters:

Name	Type	Description
change_date	string	Filter by change date
count	integer	Number of results to return
exclude_generaluser	boolean	Exclude general users
idonly	boolean	Return only IDs
order	string	Field name to order by (first)
order2	string	Field name to order by (second)
order3	string	Field name to order by (third)
order4	string	Field name to order by (fourth)
order5	string	Field name to order by (fifth)
orderdesc	boolean	Order descending on first order field
orderdesc2	boolean	Order descending on second order field
orderdesc3	boolean	Order descending on third order field
orderdesc4	boolean	Order descending on fourth order field
orderdesc5	boolean	Order descending on fifth order field
page_no	integer	Page number when using pagination
page_size	integer	Page size when using pagination
pageinate	boolean	Whether to use pagination

Response: 200 OK

---

UserRoles

GET /UserRoles

Summary: List User Roles

Response: 200 OK

---

POST /UserRoles

Summary: Create User Role(s)

Request Body: Array of UserRoles objects

Response: 200 OK

---

GET /UserRoles/{id}

Summary: Get one UserRole

Description: Returns a single UserRole instance. Requires authentication.

Path Parameters:

Name	Type	Required	Description
id	integer	Yes	UserRole ID

Query Parameters:

Name	Type	Description
includedetails	boolean	Include extra details

Response: 200 OK

---

DELETE /UserRoles/{id}

Path Parameters:

Name	Type	Required	Description
id	integer	Yes	UserRole ID

Response: 200 OK

---

OnlineStatus

GET /OnlineStatus

Summary: Get Agent Online Status

Query Parameters:

Name	Type	Description
TechID	integer	Agent/tech ID
LastOnlineDate	string (date-time)	Last online date filter
IsOnline	boolean	Whether the agent is online
LastOnline	string	Last online string value
agent_status	integer	Agent status code
status_overidden	boolean	Whether status is overridden
fetch_all	boolean	Fetch all statuses
is_logout	boolean	Whether agent is logged out
command	string	Command to execute
last_active	string (date-time)	Last active timestamp
is_idle	boolean	Whether agent is idle
idle_warn	boolean	Idle warning flag

Response: 200 OK

---

POST /OnlineStatus

Summary: Update Online Status

Request Body: Array of OnlineStatus objects

Response: 200 OK

---

AgentCheckIn

GET /AgentCheckIn

Summary: List of AgentCheckIn records

Description: Returns multiple AgentCheckIn records. Requires authentication.

Query Parameters:

Name	Type	Description
agent_id	integer	Filter by agent ID
start_date	string	Filter by start date
end_date	string	Filter by end date

Response: 200 OK

---

POST /AgentCheckIn

Summary: Create AgentCheckIn record(s)

Request Body: Array of AgentCheckIn objects

Response: 200 OK

---

GET /AgentCheckIn/{id}

Summary: Get one AgentCheckIn

Description: Returns a single AgentCheckIn instance. Requires authentication.

Path Parameters:

Name	Type	Required	Description
id	integer	Yes	CheckIn ID

Query Parameters:

Name	Type	Description
includedetails	boolean	Include extra details

Response: 200 OK

---

TeamImage

GET /TeamImage/{id}

Summary: Get Team profile image

Path Parameters:

Name	Type	Required	Description
id	string	Yes	Team ID

Response: 200 OK

---

LoginToken

POST /LoginToken

Summary: Create a Login Token

Request Body: LoginToken object

Response: 200 OK

---

AuthInfo

GET /AuthInfo

Summary: Get authentication information

Response: 200 OK

---