NAV

SimpleHelp Integration API

Version 1.0

The SimpleHelp API is a web-based HTTP API that clients can use to query state in the SimpleHelp server and modify certain configuration settings. The API is REST-like. Each HTTP request contains all the data required to complete that request.

The SimpleHelp API endpoint is:

https://host:port/api/v1/api_token/query

where:

  • host - the hostname of your SimpleHelp server
  • port - the port to connect on
  • api_token - a server-specific API token that can be generated in the Administration tab of the Technician Console
  • query - the query to process on the server

Each API request to the API endpoint may optionally include POST data sent from the client to the server. The server will then respond with an HTTP return code and some return data. The post data and return data are JSON formatted.

API Errors and Return Codes

SimpleHelp uses HTTP return codes to indicate whether a request was successful or not. Return codes can be split into three groups:

  • 200s - Success
  • 400s - Failure to process the requested query given the post data and API token
  • 500s - Server failure.

Certain API calls, and API failures, will return an API response with details about whether the call succeeded and some reason for a failure.

API Response Object

X X
success
Boolean
true if the request was successful, and false otherwise.
reason
String
if success is false, a short description why the request failed.

Technician Queries

Technician queries manage the set of technicians configured in the SimpleHelp server. A Technician Object contains attributes specific to each technician account.

Technician Object

X X
uniqueID
integer
An internal unique identifier for this technician.
displayName
String
The technician’s display name.
username
String
The technician’s username, which must be unique.
emailAddress
String
An email address for this technician.
isAnonymous
Boolean
true if this is an account that has been created by the SimpleHelp server after an anonymous group-based login.
allowLocallyAuthenticatedLogins
Boolean
true if this technician can login using their account password.
enabled
Boolean
true if this technician’s account is currently enabled.
appProfilesUser
Boolean
true if this is an account created specifically for preconfigured applications.
groupIDs
Integer Array
An integer array of Technician Group IDs indicating which groups this technician is a member of

List Technicians

/technicians/list

Request the list of technician accounts from the server

curl [SERVER]/technicians/list \ 
  -X POST \
  -H "Content-Type: application/json" 

Return a JSON array of Technician Objects detailing all technician accounts configured in the SimpleHelp server.

Response

X X
Technician Object Array A JSON array of Technician Objects representing the technician accounts in the server.

Create a New Technician

/technicians/new

Create a technician account

curl [SERVER]/technicians/new \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{technician: {username: "testuser", emailAddress:"testuser@simple-help.com}}'

Create a new technician account in the SimpleHelp server.

POST Data Attributes

X X
technician
Technician Object
A JSON Technician Object detailing the account to create.

Response Data

X X
API Response Object A response indicating success or failure.

Retrieve a Technician

/technicians/get

Retrieve a technician account by username

curl [SERVER]/technicians/get \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{username: "testuser"}'

Retrieve a technician account by uniqueID or by username.

POST Data Attributes

X X
uniqueID
Integer
If specified lookup a technician by this uniqueID.
username
String
If specified lookup a technician by this username.
technician
Technician Object
If specified lookup a technician using the username attribute of this technician object.

Response Data

X X
Technician Object A technician object representing this technician account.

Update a Technician

/technicians/set

Set the display name for a technician

curl [SERVER]/technicians/set \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{technician: {username: "testuser", displayName: "New Name"}}'

Update one or more technician account attributes.

POST Data Attributes

X X
uniqueID
Integer
If specified update the technician account with this uniqueID.
username
String
If specified lookup a technician by this username.
technician
Technician Object
A technician object with one or more attributes that will be set for this technician account.
If the uniqueID is not specified update the technician account using the username attribute of this technician object.

Response Data

X X
API Response Object A response indicating success or failure.

Remove a Technician

/technicians/remove

Remove a technician account

curl [SERVER]/technicians/remove \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{username: "testuser"}'

Remove a technician by uniqueID or by username.

POST Data Attributes

X X
uniqueID
Integer
If specified remove a technician with this uniqueID.
username
String
If specified lookup a technician by this username.
technician
Technician Object
If specified remove a technician using the username attribute of this technician object.

Response Data

X X
API Response Object A response indicating success or failure.

Set a Technician Password

/technicians/password/set

Set a password to abcd1234

curl [SERVER]/technicians/password/set \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{username: "testuser", password:"abcd1234"}'

Set the password of a technician account.

POST Data Attributes

X X
uniqueID
Integer
If specified set the password for a technician with this uniqueID.
username
String
If specified lookup a technician by this username.
technician
Technician Object
If specified set the password for a technician using the username attribute of this technician object.
password
String
The new password to set.

Response Data

X X
API Response Object A response indicating success or failure.

Reset a Technician TOTP Key

/technicians/totp/remove

Remove an OTP key for a technician

curl [SERVER]/technicians/totp/remove \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{username: "testuser"}'

Remove the TOTP key for a technician account. Technicians will be prompted to reconfigured their app-based authentication on next login.

POST Data Attributes

X X
uniqueID
Integer
If specified remove the TOTP key for a technician with this uniqueID.
username
String
If specified lookup a technician by this username.
technician
Technician Object
If specified remove the TOTP key for a technician using the username attribute of this technician object.

Response Data

X X
API Response Object A response indicating success or failure.

Technician Group Queries

Technician Group queries can be used to manage the set of Technician Groups in the SimpleHelp server. The follow JSON object details the attributes in a Technician Group Object.

Technician Group Object

X X
uniqueID
Integer
An internal unique identifier for this technician group.
name
String
The group name.
allowAnonymousLogins
Boolean
true if this group allows logins of technicians with no SimpleHelp technician account.
max_groupShSessions
Integer
The maximum number of support sessions this group can use.
max_groupSgSessions
Integer
The maximum number of access sessions this group can use.
max_userShSessions
Integer
The maximum number of support sessions a technician in this group can use.
max_userShSessions
Integer
The maximum number of access sessions a technician in this group can use.
maxFileSize
Long
The maximum file size that can be transferred in bytes.
requestAccessTimeout
Long
The timeout in milliseconds for request access requests. A timeout of 0 means no timeout.
groupSpecificHostname
String
The server hostname specific to users of this group.
defaultSgServiceName
String
The default remote access service name for users of this group.
videoPassword
String
The password required for recordings creating by users in this group.
sessionSpeedLimitKbps
Integer
The bandwidth limit imposed on technicians in this group. A limit of 0 means no limit.
fpsDelay
Long
The frame per second delay, in milliseconds, imposed on users in this group. The resulting frames per second can be calculated as 1000/fpsDelay.
ldapSettings
LDAP Settings Object
A LDAP Settings Object describing the LDAP authentication settings for this group.
mfaSettings
MFA Settings Object
A MFA Settings Object describing the configured group multifactor authentication.
passwordSettings
Password Settings Object
A Password Settings Object describing whether group password authentication is permitted.

LDAP Settings Object

X X
enabled
Boolean
Set to true if LDAP authentication is enabled.
advanced
Boolean
Set to true if advanced LDAP settings are specified.
baseDN
String
The baseDN to use when querying the LDAP server.
filter
String
The advanced search filter to use when querying the LDAP server.
memberOfGroups
String Array
The directory groups that members of this Technician Group will be authenticated with.

MFA Settings Object

X X
email
Boolean
Set to true if email-based multifactor authentication is enabled.
app
Boolean
Set to true if app-based multifactor authentication is enabled.
emailCodeLength
Integer
The length of the authentication code sent to users.
emailSubject
String
The template email subject that is sent to users when email-based multifactor authentication is required.
emailBody
String
The template email body that is sent to users when email-based multifactor authentication is required.
rememberMachine
Boolean
Set to true if technicians are allowed to prevent future multifactor requests once authenticated.

List Groups

/groups/list

Return all the Technician Groups

curl [SERVER]/groups/list \ 
  -X POST \
  -H "Content-Type: application/json"

Return a JSON array of Technician Group Objects detailing all technician groups configured in the SimpleHelp server.

Response Data

X X
Technician Group Object Array A JSON array of Technician Group Objects representing the groups in the server.

Create a Technician Group

/groups/new

Create a new group called TechGroup

curl [SERVER]/groups/new \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{group: {name: "TechGroup"}}'

Create a new Technician Group in the SimpleHelp server.

POST Data Attributes

X X
group
Technician Group Object
A JSON Technician Group Object detailing the group to create.

Response Data

X X
API Response Object A response indicating success or failure.

Retrieving a Technician Group

/groups/get

Retrieve a group by name

curl [SERVER]/groups/get \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{group: {name: "TechGroup"}}'

Retrieve the details of a Technician Group by uniqueID or by group name.

POST Data Attributes

X X
uniqueID
Integer
If specified retrieve details of the group with this uniqueID.
group
Technician Group Object
If specified lookup a group using the name attribute of this Technician Group object.

Response Data

X X
Technician Group Object A technician group object representing this group.

Updating a Technician Group

/groups/set

Set the name of a group with ID 1234

curl [SERVER]/groups/get \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{uniqueID: 1234, group: {name: "TechGroup"}}'

Update one or more group attributes.

POST Data Attributes

X X
uniqueID
Integer
If specified set the attributes on the group with this uniqueID.
group
Technician Group Object
A technician group object with one or more attributes that will be set for this group.
If the uniqueID is not specified update the group using the name attribute of this technician group object.

Response Data

X X
API Response Object A response indicating success or failure.

Removing a Technician Group

/groups/remove

Remove the technician group with ID 1234

curl [SERVER]/groups/remove \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{uniqueID: 1234}'

Remove a group by unique ID or by group name.

POST Data Attributes

X X
uniqueID
Integer
If specified set the attributes on the group with this uniqueID.
group
Technician Group Object
If specified lookup a group using the name attribute of this Technician Group object.

Response Data

X X
API Response Object A response indicating success or failure.

Setting a Group Password

/groups/password/set

Set the Technician Group password

curl [SERVER]/groups/password/set \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{uniqueID: 1234, password: "abcd1234"}'

Set the password for this technician group.

POST Data Attributes

X X
uniqueID
Integer
If specified lookup a group by this uniqueID.
group
Technician Group Object
If specified lookup a group using the name attribute of this Technician Group object.
password
String
The new password to set.

Response Data

X X
API Response Object A response indicating success or failure.

Fetching Group Permissions

/groups/permissions/get

Retrieve the permissions for group with ID 1234

curl [SERVER]/groups/permissions/get \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{uniqueID: 1234}'

Retrieve the permissions for a particular Technician Group.

POST Data Attributes

X X
uniqueID
Integer
If specified fetch the permissions for the group with this uniqueID.
group
Technician Group Object
If specified lookup a group using the name attribute of this Technician Group object and retrieve the permissions for this group.

Response Data

X X
Map (String > Boolean) Permissions are returned as a Map of permissions names associated with Boolean values.

Setting Group Permissions

/groups/permissions/set

Set the canRunTools permission to true for group with ID 1234

curl [SERVER]/groups/permissions/set \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{group: {uniqueID: 1234, permissions: {canRunTools: true}}}'

Set one or more permissions for a particular Technician Group.

POST Data Attributes

X X
uniqueID
Integer
If specified fetch the permissions for the group with this uniqueID.
group
Technician Group Object
If specified lookup a group using the name attribute of this Technician Group object and set the permissions for this group. The permissions are specified as permissions within group.

Machine Queries

Machine queries allow a client to query the remote access service list, and to retrieve certain monitoring and hardware information stored in the server. Services are represented in the API using Machine Objects.

Machine Object

X X
machineID
String
A unique identifier for a machine.
online
Boolean
true if the machine is currently online.
groups
String Array
An array of group names representing the group that this machine is in.
name
String
The name of this machine.
state
String
One of In Use, Not In Use, Headless or Unknown.
protocol
String
The current polling protocol.
lastRegistrationTime
Long
The timestamp of the last time this machine registered with the server, in milliseconds.
sessionCount
Integer
The number of active sessions.
monitoringEnabled
Boolean
true if this machine is currently monitoring.
os
String
The remote machine operating system.
hostname
String
The remote machine hostname.
wanIP
String
The remote machine WAN IP address.
ipAddresses
Network Adapter Object Array
An array of Network Adapter Objects describing the local LAN adapters.

Network Adapter Object

X X
ip
String
The LAN IP address for this adapter.
mac
String
The MAC address for this adapter.
name
String
The name of this adapter.

Listing Machines

/machines/list

Return a list of all machines registering with the server

curl [SERVER]/machines/list \ 
  -X POST \
  -H "Content-Type: application/json"

Return a JSON array of Machine Objects detailing all remote access services that are represented in the SimpleHelp server.

Response Data

X X
Machine Object Array A JSON array of Machine Objects representing services that have registered with the server.

Get Machine Details

/machines/get

Retrieve machine details by machine ID

curl [SERVER]/machines/get \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{machineID: "SG_1234"}'

Fetch a Machine Object for a particular machine or set of machines.

POST Data Attributes

X X
machineID
String
The machine ID of the machine for which details should be fetched.
machineIDs
String Array
The machine IDs of the machines for which details should be fetched.

Response Data

X X
Machine Object Array A JSON array of Machine Objects representing the details of the requested machines.

Change Machine Settings

/machines/set

Rename a machine

curl [SERVER]/machines/set \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{machineID: "SG_1234", name: "New Name"}'

Change settings for one or more remote machines.

POST Data Attributes

X X
machineID
String
The machine ID of the machine for which details should be fetched.
machineIDs
String Array
The machine IDs of the machines for which details should be fetched.
monitor
Boolean
Enable or disable monitoring for the specified machines (v5.2.12 or later).

Response Data

X X
API Response Object A response indicating success or failure.

Get Machine Hardware Details

/machines/hardware/get

Retrieve the hardware information for a machine

curl [SERVER]/machines/hardware/get \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{machineID: "SG_1234"}'

Returns an array of Machine Hardware Objects containing hardware details about the requested machines. Hardware details are detailed across multiple objects, each of which is outlined below.

Hardware Object

X X
machineID
String
The machine ID of the machine that his hardware is collected from.
totalMemory
Long
The total memory, in bytes.
modelName
String
The model name of this machine.
modelIdentifier
String
This model identifier of this machine.
manufacturer
String
The manufacturer of this machine.
serial
String
The serial number of this machine.
eccMemory
Boolean
true if this machine is using ECC memory.
memory
Memory Object Array
An array of Memory Objects detailing the installed memory.
disks
Disk Object Array
An array of Disk Objects detailing the disks in this machine.
processors
Process Object Array
An array of Processor Objects detailing the processors in this machine.

Memory Object

X X
capacity
Long
The memory capacity in bytes.
type
String
The type of memory, such as DDR3.
speedHz
Long
The speed of the memory, in Hz.
status
String
The system produced status of this memory.
manufacturer
String
The manufacturer of this memory.

Disk Object

X X
disk
String
The disk identifier used by the operating system.
deviceName
String
The name of this disk.
mediaName
String
The name of the disk media.
capacity
Long
The capacity of the disk, in bytes.
type
String
The type of disk, such as SSD.
protocol
String
The protocol of the disk.
internal
Boolean
true if this is an internal disk.

Processor Config

X X
name
String
The name of this processor.
speedHz
String
The speed of this processor in Hz.
cores
Integer
The number of cores.
is64bit
Boolean
true if this is a 64bit processor.

POST Data Attributes

X X
machineID
String
The machine ID of the remote access machine to be queried.
machineIDs
String Array
A string array of machine IDs of the remote access services to be queried.

Response Data

X X
Machine Object Array An array of Hardware Objects containing hardware details for the provided machine IDs.

Get Machine Monitoring Details

/machines/monitoring/get

Fetch the latest monitoring information for a machine

curl [SERVER]/machines/monitoring/get \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{machineID: "SG_1234"}'

Returns an array of Machine Monitoring Objects containing monitoring data retrieved from the specified machines.

POST Data Attributes

X X
machineID
String
The machine ID of the service to be queried.
machineIDs
String Array
A string array of machine IDs of the services to be queried.

Response Data

X X
Machine Monitoring Object Array An array of Monitoring Objects containing monitoring details for the provided machine IDs.

Machine Monitoring Object

X X
machineID
String
The machine ID of the machine that this monitoring data is collected from.
cpuLoadAverages
Integer Array
The last collected CPU load averages.
memoryLoadAverages
Integer Array
The last collected memory load averages.
is64bit
Boolean
true if this is a 64bit machine.
os
String
The operating system name and version.
hostname
String
The hostname of this machine.
wanIP
String
The public WAN IP of this machine.
lastRestarted
Long
The timestamp in milliseconds when this service was last restarted.
disks
Disk Monitoring Array
An array of Disk Monitoring objects.
cpuOffenders
CPU Offender Array
An array of CPU Offender Objects detailing processors that are using the majoring of the CPU.
networkAdapters
Network Adapter Object Array
An array of Network Adapter objects detailing the network interfaces on this machine.

Disk Monitoring Object

X X
name
String
The name of the disk.
usedPercentage
Double
The percentage of disk space used.

CPU Offenders Object

X X
name
String
The name of the offending process.
usedPercentage
Double
The percentage of CPU used.

Fetch Machine Notes

/machines/notes/get

Fetch the notes associated with a machine

curl [SERVER]/machines/notes/get \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{machineID: "SG_1234"}'

Fetch the notes and warning text associated with one or more machines.

POST Data Attributes

X X
machineID
String
The machine ID of the machine for which notes should be fetched.
machineIDs
String Array
The machine IDs of the machines for which notes should be fetched.

Response Data

X X
Notes Response Array An array of Notes Response objects.

Notes Response Object

X X
machineID
String
The machine ID of a machine.
notes
String
The notes associated with this machine.
warnings
String
The warning text associated with this machine.

Setting Machine Notes

/machines/notes/set

Set the notes and warning text for a machine

curl [SERVER]/machines/notes/set \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{machineID: "SG_1234", notes: "Some notes", warning: "A warning"}'

Set the notes and warning text associated with a machine.

POST Data Attributes

X X
machineID
String
The machine ID of the machine for which notes should be set.
notes
String
The notes to be associated with this machine.
warnings
String
The warning text to be associated with this machine.

Response Data

X X
API Response Object A response indicating success or failure.

Fetching Machine Properties

/machines/properties/get

Fetch the machine properties associated with a machine

curl [SERVER]/machines/properties/get \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{machineID: "SG_1234"}'

Fetch the properties associated with one or more machines.

POST Data Attributes

X X
machineID
String
The machine ID of the machine to query.
machineIDs
String Array
The machine IDs of the machines to query.
includeInherited
Boolean
Set to true to include properties inherited from ancestor machine groups.
key
String
If specified, the key of the property to fetch. If absent, all properties will be returned.

Response Data

X X
Machine Properties Object Array An array of Machine Properties Objects, one for each machine requested.

Machine Properties Object

X X
machineID
String
The machine ID of the machine to query.
properties
Machine Property Object Array
An array of Machine Property Objects.

Machine Property Object

X X
key
String
The key of the machine property.
value
String
The value of the machine property.

Setting Machine Properties

/machines/properties/set

Set a property "License":"License Value" for a machine

curl [SERVER]/machines/properties/set \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{machineID: "SG_1234", key: "License", value: "License Value"}'

Set a key=value property for one or more machines.

POST Data Attributes

X X
machineID
String
The machine ID of the machine to query.
key
String
The key of the machine property.
value
String
The value of the machine property.

Response Data

X X
API Response Object A response indicating success or failure.

Removing Machine Properties

/machines/properties/remove

Remove a property "License" for a machine

curl [SERVER]/machines/properties/remove \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{machineID: "SG_1234", key: "License"}'

Remove Machine Properties from one or more machines.

POST Data Attributes

X X
machineID
String
The machine ID of the machine to remove a property from.
key
String
The key of the machine property to remove.

Response Data

X X
API Response Object A response indicating success or failure.

Fetching Machine Group Properties

/machinegroups/properties/get

Fetch the machine group properties for the group 'London' with parent group 'United Kingdom'.

curl [SERVER]/machinegroups/properties/get \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{groups: ["United Kingdon", "London"], includeInherited: true}'

Fetch the group properties associated with a machine group, and optionally return properties inherited from ancestor groups.

POST Data Attributes

X X
groups
String Array
An array of group names identifying a path in the group hierarchy
includeInherited
Boolean
Set to true to include properties inherited from ancestor machine groups.

Response Data

X X
String Array If no key is specified, a string array containing all the keys for this group's properties.
String If a key is specified, the value associated with this key.

Setting Machine Group Properties

/machinegroups/properties/set

Set the machine group property 'exampleKey'='exampleValue' for the group 'London' with parent group 'United Kingdom'.

curl [SERVER]/machinegroups/properties/get \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{groups: ["United Kingdon", "London"], key: "exampleKey", value: "exampleValue"}'

Set a key value pair associated with a machine group.

POST Data Attributes

X X
groups
String Array
An array of group names identifying a path in the group hierarchy
key
String
The key of the machine group property to set.
value
String
The value of the machine group property to set.

Response Data

X X
API Response Object A response indicating success or failure.

Server Queries

Server Queries are general purpose requests that allow you to manage technician restrictions and request a configuration backup.

Retrieve Technician Restrictions

/server/tech-restrictions/get

Retrieve technician IP restrictions

curl [SERVER]/server/tech-restrictions/get \ 
  -X POST \
  -H "Content-Type: application/json"

Retrieve the current set of IP restrictions, each expressed as a regular expression.

Response Data

X X
String Array A String Array with each string representing a single technician restriction, which restricts the source network that technicians are able to log in from.

Adding New Technician Restrictions

/server/tech-restrictions/new

Add IP 1.2.3.4 as an IP restriction

curl [SERVER]/server/tech-restrictions/new \ 
  -X POST \
  -H "Content-Type: application/json"
  -d "{restrictions: ['1.2.3.4']}"

Add IP restrictions to the current set of restrictions, with each expressed as a regular expression.

POST Data Attributes

X X
restrictions
String Array
A String Array with each string representing a single technician restriction that will be added.

Response Data

X X
API Response Object A response indicating success or failure.

Removing Technician Restrictions

/server/tech-restrictions/remove

Remove IP 1.2.3.4 as an IP restriction

curl [SERVER]/server/tech-restrictions/remove \ 
  -X POST \
  -H "Content-Type: application/json"
  -d "{restrictions: ['1.2.3.4']}"

Remove IP restrictions from the current set of restrictions, with each expressed as a regular expression.

POST Data Attributes

X X
restrictions
String Array
A String Array with each string representing a single technician restriction that will be removed.

Response Data

X X
API Response Object A response indicating success or failure.

Request a Configuration Backup

/server/backup-config

A request that will cause the SimpleHelp server to save a timestamped backup of the configuration file to configuration/backups/api in the SimpleHelp server installation directory.

Response Data

X X
API Response Object A response indicating success or failure.

Fetch the Server Hostname

/server/hostname/get

Retrieve the hostname

curl [SERVER]/server/hostname/get \ 
  -X POST \
  -H "Content-Type: application/json"

Retrieve the hostname for this SimpleHelp server, as configured in the Network Settings section of the Administration tab.

Response Data

X X
String The currently configured hostname

Set the Server Hostname

/server/hostname/set

Set the hostname for this server to 'simplehelp.server.com'

curl [SERVER]/server/hostname/get \ 
  -X POST \
  -H "Content-Type: application/json"
  -d "{hostname: 'simplehelp.server.com'}"

Set the server's hostname, as configured in the Network Settings section of the Administration tab.

Response Data

X X
API Response Object A response indicating success or failure.

History Queries

Query the server’s history repository to retrieve details of previous sessions. History results are serialised in a JSON History Object.

History Object

X X
sessionID
String
The unique session ID of this session.
type
String
The type of session. One of Access, Support or Presentation.
technicianName
String
The display name of the technician who started the session.
technicianUsername
String
The username of the technician who started the session.
start
Long
The start time of this session, in milliseconds.
duration
Long
The duration of this session, in milliseconds.
lastModified
Long
The time that this session was last updated, in milliseconds.
hasRecording
Boolean
true if this session has a synchronised recording.
chat
String
A copy of the chat transcript.
comments
String
A copy of the technician comments.
mode
String
The initial session mode. One of “Mobile”, “File Transfer”, “Diagnostics”, “App Tunnel”, “VNC” or “Terminal”.
appTunnelTarget
String
The app tunnel configuration (if this is an App Tunnel session).
machine
Machine Object
A description of the remote machine connected to (for access sessions).
customer
Customer Object
A description of the customer connected to (for support sessions).

Customer Object

X X
customerID
String
The unique customer ID for this customer.
timeInQueue
Long
The time the customer spent waiting in the queue, in milliseconds.
username
String
The customer’s local operating system username.
country
String
The customer’s detected country.
domain
String
The domain that the customer used to access the SimpleHelp server.
url
String
The URL that the customer used to access the SimpleHelp server.
os
String
The customer’s operating system.
hostname
String
The customer’s local machine hostname.
wanIP
String
The detected WAN IP address from where the customer connected.
ipAddresses
String Array
The local LAN IP addresses configured on the customer’s machine.
details
Map (String > String)
The customer details entered when first initiating a session. Keys are the labels specified, and values are the customer entered details.

Listing Historical Sessions

/history/list

Retrieve the last 100 sessions in the history

curl [SERVER]/history/list \ 
  -X POST \
  -H "Content-Type: application/json"
  -d "{maxResults: 100}"

Retrieve details of historical sessions.

POST Data Attributes

X X
rangeStart
Long
Return sessions that started at, or after, the specified time in milliseconds.
rangeEnd
Long
Return sessions that started before the specified time in milliseconds.
rangeLastModified
Boolean
Set to true to return sessions where rangeStart and rangeEnd restrict the last modified time of the session rather than the start time.
maxResults
Integer
The maximum results to return. The default is 50.
textFilter
String
Include sessions that match the specified text filter.
technicianNameFilters
String Array
Include sessions where the technician names match one or more of the specified filters.
groupFilters
Integer Array
Include sessions where the technicians are in groups with the attached group ID photos.
machineIDFilters
String Array
Include sessions to machines with the specified machine IDs.
includeSupportSessions
Boolean
Set to true to include remote support sessions. The default is true.
includeAccessSessions
Boolean
Set to true to include remote access sessions. The default is true.
includePresentationSessions
Boolean
Set to true to include presentation sessions. The default is true.
searchUntilSessionID
String
Return results until the specified session ID is encountered.

Response Data

X X
History Object Array The list of history objects returned by the query.

Alerts Queries

Retrieve the monitoring alerts.

Alert Object

X X
name
String
The alert name.
active
Boolean
true if the alert is currently enabled, false otherwise.
triggered
Boolean
true if the alert is currently triggered, false otherwise.
triggeredMachineIDs
String Array
An array of machine IDs of triggered machines.
reason
String
A more complete reason about why the alert triggered.
shortReason
String
A short reason about why the alert triggered.
lastReportMS
Long
The timestamp that this alert last reported its state.
stateAgeMS
Long
The duration, in milliseconds, that this alert has been in the current state.
severity
String
One of information, severe, critical and warning.

Listing Alerts

/alerts/list

Retrieve the alerts

curl [SERVER]/alerts/list \ 
  -X POST \
  -H "Content-Type: application/json"

Retrieve details of historical sessions.

Response Data

X X
Alert Object The list of alerts objects returned by the query.

Session Queries

Retrieve the list of active support or access sessions, or query the waiting session queue.

Support Session Queries

Query the server for customer initiated support sessions that are in the waiting queue, or currently in session.

Support Session Object

X X
customer
Customer Object
The customer details for this support session.
technicianDisplayName
String
The technician's name.
technicianUsername
String
The technician's username.
technicianID
Integer
The technician's unique account ID.
sessionID
String
The a unique session ID for this session.
elapsedTime
Long
The session duration, in milliseconds.
startTime
Long
The start time of the session, in milliseconds.

Listing Queued Sessions

/support/queue/list

Retrieve the list of sessions in the waiting queue

curl [SERVER]/support/queue/list \ 
  -X POST \
  -H "Content-Type: application/json"

Retrieve the list of sessions in the waiting queue

Response Data

X X
Support Session Object Array An array of Support Session objects.

Listing Active Support Sessions

/support/sessions/list

Retrieve the list of active support sessions

curl [SERVER]/support/sessions/list \ 
  -X POST \
  -H "Content-Type: application/json"

Response Data

X X
Support Session Object Array An array of Support Session objects.

Access Session Queries

Query the server for access sessions that are currently in session.

Access Session Object

X X
machine
Machine Object
The machine details for this access session.
technicianDisplayName
String
The technician's name.
technicianUsername
String
The technician's username.
technicianID
Integer
The technician's unique account ID.
sessionID
String
The a unique session ID for this session.
elapsedTime
Long
The session duration, in milliseconds.
startTime
Long
The start time of the session, in milliseconds.

Listing Active Access Sessions

/access/sessions/list

Retrieve the list of active access sessions

curl [SERVER]/access/sessions/list \ 
  -X POST \
  -H "Content-Type: application/json"

Retrieve the list of active access sessions. These are sessions initiated to remote access services in the Access tab.

Response Data

X X
Access Session Object Array An array of Access Session objects.