SysAid REST API Guide
  • 30 Apr 2023
  • 7 Minutes to read
  • Dark
    Light
  • PDF

SysAid REST API Guide

  • Dark
    Light
  • PDF

Article Summary

Introduction

SysAid is a robust IT management system that was designed to meet all of your needs as an IT department. The SysAid REST API was designed to help you meet two specific needs:

  • Display, store, and process help desk data in a way that is best for your organization
  • Interface SysAid with third party applications

The REST API is supported by SysAid versions 15.4 and up.


This guide was written for Web Developers/IT Professional programmers and assumes advanced understanding of computer protocols to best utilize the APIs to your organisations advantage. This document assumes knowledge of how to program REST API calls using your programming language and selected technology in your System Environment setting.

Request Limits

To allow for maintenance of high uptime with good performance, and added self-sufficiency in meeting the increasing demands for usage - without the need for assistance from the SysAid Customer Care team - the following request limits apply when using SysAid's REST API.

  • A maximum of two API login requests will be allowed within a five minute period
  • Up to 1,000 other API requests will be allowed within a five minute period

If usage exceeds the framework, an HTTP 429 message appears, and you will be able to continue once that five-minute time period has passed.

Definitions

There are several definitions that you should be familiar with before you read the rest of this guide.

SysAid entity (object) A SysAid entity is anything in SysAid that has both a list page and a form page. Each SysAid entity is represented by a SysAid object. The API gives you access to the following SysAid entities: service records, assets, CIs, and users.

Endpoint

When you use the API, the endpoint should be appended to your account URL as in the following example:

https://www.johndoe.sysaid.com/api/v1/<api_url>

Common parameters

The following parameters are available in all or most of the API calls.

Offset

If you are retreiving a list of items, you can use the Offset parameter to set where on the list you should begin. For example, if you are retrieving a list of service records and there are 500 that match your criteria, but you are not interested in the first 100, you can set the Offset to 101 so the API returns service records 101 and up.

Limit
The maximum number of items to retrieve. For example, if your API call retrieves 1000 assets, you can set the limit to 300 so that only the first 300 assets (beginning from the defined offset, if specified) are retrieved.

View
A SysAid view which defines the available fields. Such views can be selected and set for lists in SysAid. You can create or customize views from the SysAid admin web interface.

Fields

Define a ist of comma seperated values representing the field names you wan to retrieve. If this parameter is set together with the View parameter, the API call returns both View fields and the fields specified in this parameter.

Info
Additional information fields.

JSON Samples

Throughout this guide sample JSON Input and Return values are displayed as in white box like the one below:

Sample JSON input - set sr status, assigned to, due date and add a note

{
  “info”: [{“key”:”due_date”, ”value”:1391756438000},
            {“key”:”status”, ”value”:2},
            {“key”:”notes”,”value”:[
            {“userName”:”sysaid”,”createDate”:1391756438000,”text”:”Note 123”}
             ]},
             {“responsibility”:66}]
}

Login

This Login call is for non-OAuth users.

Command NameCommandDescriptionMore Details
Authenticate a user in SysAid serverPOST/loginChecks both that the user is an administrator, and that he has permission to access the mobile app.More Details
Important

Upon a successful login, the API consumer needs to retrieve the JSESSIONID cookie from the Response Header and submit it in all consequent API Request Headers.

Due to security reasons, each session expires after 24 hours.
Please make sure to log in again before the session expires.

Note
For Cloud accounts:
Subsequent API Calls for SysAid Cloud Accounts, need to include an Additional Cookie named SERVERID & its value, which is returned from the Login response.



Users

Command NameCommandDescriptionMore Details
Get Users ListGET/users?view={view_name}&fields={field1,field2...}&type={type} &offset={offset}&limit={limit}Get list of users in SysAidMore Details
Get UserGET/users/{id}?view={view_name}&fields={field1,field2...}Get information on the specified userMore Details
Search UsersGET/users/search?query={query_string}&view={view_name}&fields={field1,field2...}&type={type} &offset={offset}&limit={limit} &sort={field1,field2...}&dir={dir}Get list of users in SysAid, according to a search criteriaMore Details
Get User's PhotoGET /users/{id}/photoDownloads the specified user's photoMore Details
Upload User's PhotoPOST/users/{id}/photouploads the specified user's photoMore Details
Get User PermissionsGET/users/{id}/permissionGet user permissionsMore Details
Get A User's PermissionGET/users/{id}/permission/{permissionId}Check a specific user permissionMore Details

Filters

Command NameCommandDescriptionMore Details
Get Filters ListGET/filters?view={view_name}&fields={field1,field2..}&offset={offset}&limit={limit}Get list of available filters and their values.More Details
Get FilterGET/filters/{id}?view={view_name}&offset={offset}&limit={limit}Returns the information and available values for the specified filterMore Details

Service Requests

Command NameCommand
Description
More Details
Get Service Request ListGET/sr?view={view_name}&fields={field1,field2..}&ids={id1,id2..}&type={type}&offset={offset}&limit={limit}&{filter1}={filter1_value}&{filter2}={filter2_value}..&sort={field}&dir={dir}...

Returns a list of available service records (SR).

Number of SRs to return can be controlled by offset, limit & type parameters.

Returned SRs can be filtered by filters (See Filter Service).

Each service record, Includes the fields according to view & fields parameters. If none specified, all SR fields are returned.

More Details
Get Service RequestGET/sr/{id}?view={view_name}&fields={field1,field2...}Returns the information for the specified service record.More Details
Search Service RequestsGET/sr/search?query={search_criteria}&view={view_name}&fields={field1,field2..}&type={type}&offset={offset}&limit={limit}&{filter1}={filter1_value}&{filter2}={filter2_value}..&sort={field}&dir={dir}...Returns a list of service records (SRs), that matched the search criteria.More Details
Update Service RequestPUT/sr/{id}Update a service recordMore Details
Count Service RequestsGET/sr/count?{filter1}={filter1_value}&{filter2}={filter2_value}..Returns the number of SR’s that are compatible with the provided filters.More Details
Close Service RequestPUT/sr/{id}/closeClose a service record. Sets the service record status to the default close status, as defined in the Help Desk settings.More Details
Get Service Request TemplateGET/sr/template?view={view_name}&fields={field1,field2..}&type={sr_type}&template={template_id}Get a new service record templateMore Details
Create Service RequestPOST/sr?view={view_name}&type={sr_type}&template={template_id}Create a new service record and returns the newly created service record.More Details
Delete Service RequestDELETE/sr?ids={id1,id2….}Delete one or more service recordsMore Details
Service Record Links
Add Service Request LinkPOST /sr/{id}/linkAdd a link to service recordMore Details
Delete Service Request LinkDELETE /sr/{id}/linkDelete a link from service recordMore Details
Service Record Attachments
Add Service Request AttachmentPOST /sr/{id}/attachmentAdd an attachment to service recordMore Details
Delete Service Request AttachmentDELETE /sr/{id}/attachmentDelete an attachment from service recordMore Details
Service Record Activities
Add Service Request ActivityPOST /sr/{id}/activityAdd an activity to service recordMore Details
Delete Service Request ActivityDELETE /sr/{id}/activityDelete an activity from service recordMore Details
Service Record Messages
Send Message From Service RequestPOST /sr/{id}/message?method={method}Send a message from a service recordMore Details

Action Item

Command NameCommandDescriptionMore Details
Get Action ItemsGET/action_item?view={view_name}&fields={field1,field2..}&type={type}&archive={archive}&ids={id1,id2..}&
staticFilterId={filter_id}&{filter1}={filter1_value}&{filter2}={filter2_value}..&
query={search_criteria}&offset={offset}&limit={limit}&sort={field}&dir={dir}...
Get list of action items in SysAidMore Details
Count Action ItemsGET/action_item/count?view={view_name}&fields={field1,field2..}&type={type}&
archive={archive}&ids={id1,id2..}&staticFilterId={filter_id}&{filter1}={filter1_value}&{filter2}={filter2_value}..&
query={search_criteria}
Count action itemsMore Details
Approve Action ItemsPUT/action_item/{id}/approveApprove an action itemsMore Details
Reject Action ItemsPUT/action_item/{id}/rejectReject action itemsMore Details
Complete Action ItemsPUT/action_item/{id}/completeComplete action itemsMore Details
Reopen Action ItemsPUT/action_item/{id}/reopenReopen action itemsMore Details

Assets

Command NameCommandDescriptionMore Details
Get Assets ListGET/asset?view={view_name}&fields={field1,field2...}&type={type} &offset={offset}&limit={limit}Get list of assets in SysAidMore Details
Get AssetGET/asset/{id}?view={view_name}&fields={field1,field2...}Get information on the specified assetMore Details
Search AssetGET/asset/search?query={search_criteria}&view={view_name}&fields={field1,field2...}&offset={offset}&limit={limit}Get list of assets in SysAid, that matched the search criteriaMore Details

Lists

Command NameCommandDescriptionMore Details
Get All ListsGET/list?entity={entity}&fields={field1,fields2..}&offset={offset}&limit={limit}Get all available lists and their values.More Details
Get ListGET/list/{id}?entity={entity}&entityId={entity_id}&entityType={entityType}&fields={field1,fields2..}&offset={offset}&limit={limit}&key={keyField}Returns the values of the specified list. Values may be filtered according to the entity (sr, asset etc) for which you populate the list values.More Details

Add-Ons

Command NameCommandDescriptionMore Details
List Add-On ApplicationGET/addonsGet a list of all available add-ons.More Details
Get Add-On ParametersGET/addons/{addon name}Returns the full information about an add-on with all of its parameters.More Details
UpdateAdd-On ParametersPUT/addon/{addon name}Update an add-on's parameters.More Details
Test Add-On ConnectionPUT/addon/{addon name}/testConnectionTest an add-on's parameters.More Details
Refresh Add-On ListGET/addons/refreshImmediately refresh the list of add-ons.More Details

CIs

Command NameCommandDescriptionMore Details
Get CI List/FormGET/ci?view={view_name}&fields={field1,field2..}&ids={id1,id2..}&offset={offset}&limit={limit}&{filter1}={filter1_value}&{filter2}={filter2_value}..&sort={field}&dir={dir}supportBarcode={true/false}...

Returns a list of CIs that can be filtered by the available filters.

The Number of CIs to return can be controlled by the Offset and Limit parameters.
Returned CIs can be filtered.
Each CI Includes the fields according to the View and Fields parameters. If none are specified, all CI fields are returned.

More Details
Update CIPUT/ci/{id}Update a CIMore Details
Get CI TypesGET/ci/type?supportBarcode={true/false}

Returns the available CI types.

If the barcode flag is requested, returns only CI types with barcode support (if add-on is available).
More Details
Get CI ViewGET/ci/view/{ciTypeId}?view={view_name}Returns the fields contained in the specified view.More Details
Get CI Relation TypesGET /ci/relationtypesReturns all the valid CI relation types defined in SysAid database and their ID numbers.More Details
Get CI Relation GET /ci/relationAn API to retrieve all the destination CIs and their relation types, which are associated to a given Ci Id.More Details
Create CI RelationsPOST /ci/{ciId}/relationAPI for creating one or more relations for a given CI ID.More Details
Delete CI RelationsDELETE /ci/{ciId}/relation

API for deleting one or more relations for a given Ci ID.

More Details

Resource Bundle (RB)

Command NameCommandDescriptionMore Details
Get RB Translated KeysPOST /rbGet array of translated keys according to the account location.More Details
Get RB Translated Keys With Given LocationPOST /rb/{locale}Get array of translated keys according to the given location.More Details

Password Services

Command NameCommandDescriptionMore Details
Get LDAP Domains

GET /ps/domain

Get LDAP domains.More Details
Get Password Services PermissionGET /ps/permissionGet Password Services permissions.More Details
Get Security QuestionPOST ps/{method}/question

Get Security Questions for given user.

The method @pathparam can be: unlock/reset.
More Details
Unlock AccountPOST ps/unlock/Unlock user on verifying his answers.More Details
Reset PasswordPOST ps/reset/Reset user’s password on verifying his answers.More Details
Update PasswordPOST ps/reset/updateUpdate user’s password manual on verifying his token.More Details

Appendix A: Field Types

   

Field TypeDescription
text

A textual value

numericA numeric value
booleanBoolean value - can be either 0/1, or true/false
dateA date value. Returned as milliseconds in UTC/GMT (since January 1, 1970). The valueCaption is the formatted date representation, according to date display configuration in SysAid.
listA list of values. The full list of values can be retrieved using the /list/{id} api call.
nestedThe value is an item in a nested list. Currently used for category levels.
objectThe value is an object with sub values.
customTBD...

Appendix B: Lists

The available lists are fetched by entity types.
For example, if you want to retreive all available lists in the Service Record form, you can send the following API call:
/list?entity=sr

The available lists are:

List TypeDescription
srService record related lists
assetAsset related lists
userUser related lists
ciCI related lists
companyCompany related lists
action_itemAction item related lists
projectService record Sub Tabs lists
taskTask related lists
catalogCatalog related lists
softwareSoftware related lists
sr_activityService Record activity related lists
supplierSupplier related lists
task_activityTask activity related lists
user_groupsUser Group related lists



Was this article helpful?