SysAid REST API Guide

The SysAid REST API was designed to help:

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

This guide is for Web Developers/IT Professional programmers and assumes advanced understanding of computer protocols to best utilize the APIs to your organization's 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

The following request limits apply when using SysAid's REST API to ensure high uptime, good performance, and increased self-sufficiency in meeting growing usage demands, without requiring assistance from the SysAid Customer Care team:

• 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 retrieving 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 in a 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.

Users

Filters

Service Requests

Action Item

Assets

Lists

Add-Ons

CIs

Resource Bundle (RB)

Password Services

Appendix A: Field Types

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: