SysAid REST API Guide
- 12 May 2025
- Print
- PDF
SysAid REST API Guide
- Updated on 12 May 2025
- Print
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback!
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
🚀 Try out the New SysAid Developer Site (Beta)Want to explore our latest API experience? Join the beta for early access to the new SysAid Developer Site.
Get hands-on with the new:
User API
Service Record API
Group APIs
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.
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.
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 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 list of users in SysAid, according to a 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 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). 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. | |
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 returns 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 service record | |
Delete Service Request Link | DELETE /sr/{id}/link | Delete a link from service record | |
Service Record Attachments | |||
Add Service Request Attachment | POST /sr/{id}/attachment | Add an attachment to service record | |
Delete Service Request Attachment | DELETE /sr/{id}/attachment | Delete an attachment from service record | |
Service Record Activities | |||
Add Service Request Activity | POST /sr/{id}/activity | Add an activity to service record | |
Delete Service Request Activity | DELETE /sr/{id}/activity | Delete an activity from 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 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 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 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, returns only CI types with barcode support (if 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 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 to 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 array of translated keys according to the account location. | |
Get RB Translated Keys With Given Location | POST /rb/{locale} | Get 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 given user. The method @pathparam can be: unlock/reset. | |
Unlock Account | POST ps/unlock/ | Unlock user on verifying his answers. | |
Reset Password | POST ps/reset/ | Reset user’s password on verifying his answers. | |
Update Password | POST ps/reset/update | Update user’s password manual 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 |
.png)