SysAid Developers is live!
🚀 We've listened to your feedback and are excited to announce the official launch of the SysAid Developers site!
Get full access to our modern API experience and start building today with:
User API
Service Record API
Group APIs
💡 Why switch?Unlike these static articles, the new Developers site is fully interactive, meaning you can:
Run API calls directly in the browser
Explore live, working examples
Access new capabilities like creating and updating users via API
Enjoy a significantly smoother, faster integration experience
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
The REST API is supported by SysAid versions 15.4 and up
This guide is for Web Developers/IT Professional programmers and assumes an 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 settings.
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 that 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 list of comma-separated values representing the field names you want 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.
Command Name | Command | Description | More Details |
|---|---|---|---|
Authenticate a user on the SysAid server | POST/login | Checks that the user is an administrator and that they have permissions to access the mobile app |
Important!
Upon a successful login, the API consumer needs to retrieve the JSESSIONID cookie from the Response Header and submit it in all subsequent API Request Headers.
For security reasons, each session expires after 24 hours.
Please make sure to log in again before the session expires.
Please note:
For Cloud accounts:
Subsequent API Calls for SysAid Cloud Accounts need to include:
An Additional Cookie named SERVERID
The Additional Cookie's value, which is returned from the Login response
Users
Command Name | Command | Description | More Details |
|---|---|---|---|
Get Users List | GET/users?view={view_name}&fields={field1,field2...}&type={type} &offset={offset}&limit={limit} | Get a list of users in SysAid | |
Get User | GET/users/{id}?view={view_name}&fields={field1,field2...} | Get information on the specified user | |
Search Users | GET/users/search?query={query_string}&view={view_name}&fields={field1,field2...}&type={type} &offset={offset}&limit={limit} &sort={field1,field2...}&dir={dir} | Get a list of users in SysAid, according to the search criteria | |
Get User's Photo | GET /users/{id}/photo | Downloads the specified user's photo | |
Upload User's Photo | POST/users/{id}/photo | uploads the specified user's photo | |
Get User Permissions | GET/users/{id}/permission | Get user permissions | |
Get A User's Permission | GET/users/{id}/permission/{permissionId} | Check a specific user's permission |
Filters
Command Name | Command | Description | More Details |
|---|---|---|---|
Get Filters List | GET/filters?view={view_name}&fields={field1,field2..}&offset={offset}&limit={limit} | Get list of available filters and their values. | |
Get Filter | GET/filters/{id}?view={view_name}&offset={offset}&limit={limit} | Returns the information and available values for the specified filter |
Service Requests
Command Name | Command |
| More Details |
|---|---|---|---|
Get Service Request List | GET/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). The 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 the view & fields parameters. If none are specified, all SR fields are returned. | |
Get Service Request | GET/sr/{id}?view={view_name}&fields={field1,field2...} | Returns the information for the specified service record. | |
Search Service Requests | GET/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. | |
Update Service Request | PUT/sr/{id} | Update a service record | |
Count Service Requests | GET/sr/count?{filter1}={filter1_value}&{filter2}={filter2_value}.. | Returns the number of SR’s that are compatible with the provided filters. | |
Close Service Request | PUT/sr/{id}/close | Close a service record. Sets the service record status to the default close status, as defined in the Help Desk settings. | |
Get Service Request Template | GET/sr/template?view={view_name}&fields={field1,field2..}&type={sr_type}&template={template_id} | Get a new service record template | |
Create Service Request | POST/sr?view={view_name}&type={sr_type}&template={template_id} | Create a new service record and return the newly created service record. | |
Delete Service Request | DELETE/sr?ids={id1,id2….} | Delete one or more service records | |
Service Record Links | |||
Add Service Request Link | POST /sr/{id}/link | Add a link to the service record | |
Delete Service Request Link | DELETE /sr/{id}/link | Delete a link from the service record | |
Service Record Attachments | |||
Add Service Request Attachment | POST /sr/{id}/attachment | Add an attachment to the service record | |
Delete Service Request Attachment | DELETE /sr/{id}/attachment | Delete an attachment from the service record | |
Service Record Activities | |||
Add Service Request Activity | POST /sr/{id}/activity | Add an activity to the service record | |
Delete Service Request Activity | DELETE /sr/{id}/activity | Delete an activity from the service record | |
Service Record Messages | |||
Send Message From Service Request | POST /sr/{id}/message?method={method} | Send a message from a service record | |
Action Item
Command Name | Command | Description | More Details |
|---|---|---|---|
Get Action Items | GET/action_item?view={view_name}&fields={field1,field2..}&type={type}&archive={archive}&ids={id1,id2..}& | Get the list of action items in SysAid | |
Count Action Items | GET/action_item/count?view={view_name}&fields={field1,field2..}&type={type}& | Count action items | |
Approve Action Items | PUT/action_item/{id}/approve | Approve an action items | |
Reject Action Items | PUT/action_item/{id}/reject | Reject action items | |
Complete Action Items | PUT/action_item/{id}/complete | Complete action items | |
Reopen Action Items | PUT/action_item/{id}/reopen | Reopen action items |
Assets
Command Name | Command | Description | More Details |
|---|---|---|---|
Get Assets List | GET/asset?view={view_name}&fields={field1,field2...}&type={type} &offset={offset}&limit={limit} | Get the list of assets in SysAid | |
Get Asset | GET/asset/{id}?view={view_name}&fields={field1,field2...} | Get information on the specified asset | |
Search Asset | GET/asset/search?query={search_criteria}&view={view_name}&fields={field1,field2...}&offset={offset}&limit={limit} | Get a list of assets in SysAid that matched the search criteria |
Lists
Command Name | Command | Description | More Details |
|---|---|---|---|
Get All Lists | GET/list?entity={entity}&fields={field1,fields2..}&offset={offset}&limit={limit} | Get all available lists and their values. | |
Get List | GET/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. |
Add-Ons
| Command Name | Command | Description | More Details |
|---|---|---|---|
| List Add-On Application | GET/addons | Get a list of all available add-ons. | More Details |
| Get Add-On Parameters | GET/addons/{addon name} | Returns the full information about an add-on with all of its parameters. | More Details |
| UpdateAdd-On Parameters | PUT/addon/{addon name} | Update an add-on's parameters. | More Details |
| Test Add-On Connection | PUT/addon/{addon name}/testConnection | Test an add-on's parameters. | More Details |
| Refresh Add-On List | GET/addons/refresh | Immediately refresh the list of add-ons. | More Details |
CIs
Command Name | Command | Description | More Details |
|---|---|---|---|
Get CI List/Form | GET/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. | |
Update CI | PUT/ci/{id} | Update a CI | |
Get CI Types | GET/ci/type?supportBarcode={true/false} | Returns the available CI types. If the barcode flag is requested, it returns only CI types with barcode support (if the add-on is available). | |
Get CI View | GET/ci/view/{ciTypeId}?view={view_name} | Returns the fields contained in the specified view. | |
Get CI Relation Types | GET /ci/relationtypes | Returns all the valid CI relation types defined in the SysAid database and their ID numbers. | |
Get CI Relation | GET /ci/relation | An API to retrieve all the destination CIs and their relation types, which are associated with a given CI ID. | |
Create CI Records | POST/ci | Create a CI | |
Create CI Relations | POST /ci/{ciId}/relation | API for creating one or more relations for a given CI ID. | |
Delete CI Relations | DELETE /ci/{ciId}/relation | API for deleting one or more relations for a given Ci ID. |
Resource Bundle (RB)
Command Name | Command | Description | More Details |
|---|---|---|---|
Get RB Translated Keys | POST /rb | Get an array of translated keys according to the account location. | |
Get RB Translated Keys With Given Location | POST /rb/{locale} | Get an array of translated keys according to the given location. |
Password Services
Command Name | Command | Description | More Details |
|---|---|---|---|
Get LDAP Domains | GET /ps/domain | Get LDAP domains. | |
Get Password Services Permission | GET /ps/permission | Get Password Services permissions. | |
Get Security Question | POST ps/{method}/question | Get Security Questions for the given user. The method @pathparam can be: unlock/reset. | |
Unlock Account | POST ps/unlock/ | Unlock the user by verifying their answers. | |
Reset Password | POST ps/reset/ | Reset the user’s password on verifying his answers. | |
Update Password | POST ps/reset/update | Update the user’s password manually on verifying his token. |
Appendix A: Field Types
| Field Type | Description |
|---|---|
| text | A textual value |
| numeric | A numeric value |
| boolean | Boolean value - can be either 0/1, or true/false |
| date | A 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. |
| list | A list of values. The full list of values can be retrieved using the /list/{id} api call. |
| nested | The value is an item in a nested list. Currently used for category levels. |
| object | The value is an object with sub values. |
| custom | TBD... |
Appendix B: Lists
The available lists are fetched by entity types.
For example, if you want to retrieve all available lists in the Service Record form, you can send the following API call:
/list?entity=sr
The available lists are:
| List Type | Description |
|---|---|
| sr | Service record related lists |
| asset | Asset related lists |
| user | User related lists |
| ci | CI related lists |
| company | Company related lists |
| action_item | Action item related lists |
| project | Service record Sub Tabs lists |
| task | Task related lists |
| catalog | Catalog related lists |
| software | Software related lists |
| sr_activity | Service Record activity related lists |
| supplier | Supplier related lists |
| task_activity | Task activity related lists |
| user_groups | User Group related lists |