SysAid REST API Details

12 Feb 2024

SysAid REST API Details

Updated on 12 Feb 2024

Article summary

Did you find this summary helpful?

Thank you for your feedback!

Parameters

Field	Description
account_id	The user’s account id. Example Value: cmdb
user_name	Required: The user’s name Example Value: sysaid
password	Required: The user’s password, url encoded (utf-8). Example Value: password123
mobile_app	Should be set to true for mobile app. Example Value: true
version	The app version
device	The device model
os	The OS type
os_version	The OS version
push_id	The id for push notifications

Returns
An access key, the SysAid version and the basic information of the logged-in user.

Sample JSON return value

{
“language”:”en”,
“sysaid_version”:””,
   “date_format”:”yyyymmdd hh:MM:ss”
   “user”: {
         “id”:”2”,
                  “name”:”ILIENT\Barby”,
                  “info”: [{“key”:”display_name”,”value”:”Barbara Straisend”},
                             {“key”:”email_address”, “value”:”barbara@gmail.com”},
                             {“key”:”building”, “value”:”1C”}]
              }
}

Return values definition

Field	Description
logged_in	Whether the user is authenticated to this app. true/false.
user_id	The user unique id
language	Returns the user’s default language, as defined in SysAid server
error_msg	Optional. An error message to display to the user in case of failure
sysaid_version	The SysAid server version

Important

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

Users

Get Users List

Get a list of users in SysAid.

Parameters

Field	Description
view	A SysAid view which defines the available fields (Mobile view is called 'Mobile').
fields	A list of fields to return, separated by commas. If sent together with the view parameter, returns both view's fields and the requested fields.
type	The user type to retrieve. Available values are: admin, user, and manager. Defaults to all user type.
offset	Retrieved users count is limited (see limit parameter). This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0. Zero base.
limit	The maximum number of users to retrieve per request. Defaults to 500 (configurable).

Returns
A list of users. For each user returns the user ID, user Name, and information as defined in the view and/or fields parameters. If none of them exist, return full user information.

Sample JSON return value

[
    {
“id”:”1”,
       “name”:”ILIENT\Johnny”,
       “info”: [{“key”:”display_name”,”value”:”John Doe”},
                  {“key”:”email_address”, “value”:”john@gmail.com”},
                  {“key”:”building”, “value”:”1A”}]
   },
   {
“id”:”2”,
       “name”:”ILIENT\Barby”,
       “info”: [{“key”:”display_name”,”value”:”Barbara Straisend”},
                  {“key”:”email_address”, “value”:”barbara@gmail.com”},
                  {“key”:”building”, “value”:”1C”}]
   }
]

Return values definition

Field	Description
Field	Description
id	The user id
name	The user name
info	User information fields

Get User

Get information on the specified user

Parameters

Field	Description
view	A SysAid view which defines the available fields (mobile view is called ‘Mobile’).
fields	List of fields to return, comma separated. If sent together with view parameter, returns both view's fields and the requested fields.

Returns
The user ID, user Name, and information as defined in the view and/or fields parameters. If none of them exist, return full user information.

Sample JSON return value for /users/1?view=Mobile

 {
  “id”:”1”,
   “name”:”ILIENT\Moshiko”,
   “info”: [{“key”:”display_name”,”value”:”Moshe Cohen”},
               {“key”:”first_name”,”value”:”Moshe”},
               {“key”:”last_name”,”value”:”Cohen”},
               {“key”:”phone”,”value”:”+972.3.6711554”},
               {“key”:”cell_phone”,”value”:”+972.54.5453525”},
               {“key”:”email_address”, “value”:”moshe@gmail.com”},
               {“key”:”cubic”, “value”:”38”}]
   }

Return values definition

Field	Description
id	The user id
name	The user name
info	User info fields, as defined in the User Form > Mobile Tab in SysAid.

Search Users

Get list of users in SysAid, according to a search criteria

Parameters

Field	Description
query	The search criteria (Required)
view	A SysAid view which defines the available fields (the mobile view is called ‘Mobile’).
fields	List of fields to return, comma separated. If sent together with view parameter, returns both view’s fields and the requested fields.
type	The users type to retrieve. Available values are: {admin, user, manager}. Defaults to all user types.
offset	Retrieved users count is limited (see limit parameter). This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0. Zero base.
limit	The maximum number of users to retrieve per request. Defaults to 500 (configurable).
sort	One or more fields to sort by, from the fields that were fetched by the request. Defaults to ‘calculated_user_name’ field/
dir	Sort order: ascending or descending. available values: asc/desc. Default is ‘asc’. Relevant only when sort parameter is sent.

Returns
A list of users that matched the search criteria. For each user returns the user ID, user Name, isAdmin, isSysAidAdmin, isManager, and information as defined in the view and/or fields parameters. If none of them exist, return full user info.

Sample JSON return value for /users/search?query=Jo&fields=display_name,email_address&limit=2

 [
{ “id”:”1”,
“name”:”ILIENT\Johnny”,
“isAdmin”: true,
“isSysAidAdmin”: false,
“isManager”: true,
“info”: [
{“key”:”display_name”,”keyCaption”:”Name”,
”value”:”John Doe”, ”valueCaption”:”John Doe”},
{“key”:”email_address”, ,”keyCaption”:”Email Address”,
“value”:”john@gmail.com”,
“valueCaption”:”john@gmail.com”},
{“key”:”building”,”keyCaption”:”Building”,
“value”:”1B”, ”valueCaption”:”1B”}]
},
{
“id”:”2”,
“name”:”ILIENT\Barby”,
“isAdmin”: true,
“isSysAidAdmin”: false,
“isManager”: true,
“info”: [
{“key”:”display_name”,”keyCaption”:”Name”,
”value”:”Barbara Straisend”, ”valueCaption”:”Barbara Straisend”},
{“key”:”email_address”, ,”keyCaption”:”Email Address”,
“value”:”barbara@gmail.com”, “valueCaption”:”barbara@gmail.com”},
{“key”:”building”,”keyCaption”:”Building”,
“value”:”1C”, ”valueCaption”:”1C”}]
}
]

Return values definition

Field	Description
id	The user id
name	The user name
isAdmin	Whether this user is an administrator
isSysAidAdmin	Whether this user is a SysAid administrator
isManager	Whether this user has manager permissions
info	User information fields array, according to requested fields (view/fields/all).
info.key	The id of the information field
info.keyCaption	The caption of the information field’s key
info.value	The field’s value.
info.valueCaption	The field’s value’s caption. A String representation of the value for display.

Upload user's photo

Uploads the specified user’s photo.

Payload:

Multiple data including the file

Parameters

Field	Description
file	Multiplart file part

Note

File size limit: 500KB

Get User Permissions

Get user permissions

Parameters

None

Returns
User’s full permissions set.

Sample JSON return value or /users/1/permission

{
    “id”:”1”,
    “name”:”ILIENT\Moshiko”,
    “permissions”: [{“key”:”userPermissionUserSelfService”,”value”:”false”},
                        {“key”:”userPermissionHelpDeskView”,“value”:”true”},
                        {“key”:”userPermissionHelpDeskChangeType”,“value”:”All”},
                        {“key”:”userPermissionCMDBViewType”,“value”:”All”},
                        {“key”:”userPermissionInventoryViewGroup”,“value”:”\”},
                         ….]
}

Return values definition

Field	Description
id	The user id
name	The user name
permissions	List of key-value pairs with all available permissions

Get a User's Permission

Check a specific user permission

Parameters

None

Returns
User’s permission for the requested permission id

Sample JSON return value for /users/1/permission/userPermissionUserSelfService

 {“key”:”userPermissionUserSelfService”,”value”:”false”}

Return values definition

Field	Description
key	The requested permission ID
value	The permission value

Filters

Get Filters List

Get list of available filters and their values.

Parameters

Field	Description
view	A SysAid view which defines the available filters. Defaults to SysAidMobile.
fields	List of filter fields to return. If not specified, returns all.
offset	Filter values count is limited (see limit parameter). This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0.
limit	The maximum number of filter values to retrieve per request. Defaults to 500 results (configurable).

Returns
A list of all filters. For each filter returns the fields requested in the fields parameter. If not specified, returns full filter information.

Sample JSON return value for /filters?p=SysAidMobile

[
  {
“id”:”status”,
“type”:”list”,
       “values”:[{“id”:”1”, “caption”:”closed”},
                    {“id”:”2”,“caption”:”awaiting”},
                    {“id”:”3”,“caption”:”reopened”}],
       “metadata”: {”limit”:”20”, “offset”:”0”,”total”:”3”}
  },
  {
“id”:”Priority”,
“type”:”list”,
       “values”:[{“id”:”1”, “caption”:”High”},
                    {“id”:”2”,“caption”:”Urgent”}],
       “metadata”: {”limit”:”20”, “offset”:”0”,”total”:”2”}
  },
  ...
]

Return values definition

Field	Description
id	The filter ID, as defined in SysAid DB. Always returned. No need to specify in the Fields list.
type	The data type of this filter. Available data types are: text, numeric, boolean, date, list, nested, custom.
values	Array of filter values.
values.id	The filter value’s ID
values.caption	The filter value’s caption
metadata	Additional metadata on the filter values. Available only when the values field is returned. See fields parameter.
metadata.limit	The maximum number of filter values per request
metadata.offset	The start index of filter values
metadata.total	The total number of filter values

Get Filter

Returns the information & available values for the specified filter.

Parameters

Field	Description
id	The filter ID (Required)
view	A SysAid view which defines the available fields and filters. Defaults to SysAidMobile.
offset	Filter values count is limited (see limit parameter). This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0.
limit	The maximum number of filter values to retrieve per request. Defaults to 500 results (configurable).

Returns
The filter information, according to the requested view.

Sample JSON return value for /filters/status?view=SysAidMobile

{
  “id”:”status”,
  “type”:”list”,
  “values”: [
    {“id”:”1”,“caption”:”Closed”},
    {“id”:”2”,“caption”:”Awaiting”}
    ],
 “metadata”: {”limit”:”20”, “offset”:”0”,”total”:”2”}
}

Return values definition

Field	Description
id	The filter ID, as defined in SysAid DB. Always returned. No need to specify in fields list.
type	The data type of this filter. Optional. Available data types are: text, numeric, boolean, date, list, nested, custom.
values	An array of filter values
values.id	The filter value’s id
values.caption	The filter value’s caption
metadata	Additional metadata on the filter values
metadata.limit	maximum number of filter values per request
metadata.offset	The start index of filter values
metadata.total	The total number of filter values

Service Requests

Get Service Request List

Returns a list of available service records (SRs). Number of SRs to return can be controlled by the Offset, Limit, and Type parameters. Returned SRs can be filtered by the available filters. Each service record, Includes the fields according to the View and Fields parameters. If none are specified, all SR fields are returned.

Parameters

Field	Description
view	A SysAid view which defines the available fields in the list. If view is not specified, check for the fields parameter. If none is specified, returns all fields.
fields	List of fields to return. If specified together with the view parameter, return all view's fields together with the specified fields parameter. If none specified, return all SR fields.
type	The requested service record type. Available values are {incident,request,problem,change,all}. Multiple values can be sent, comma-separated. I.e: …&type=incident,request. If not specified, it defaults to all views created on the incident list. Note: If the View in your SysAid App was created on the All list view, to access it from the APIs you must provide this parameter with the value 'all'.
offset	SR count is limited (see limit parameter). This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0.
limit	The maximum number of SRs to retrieve per request. Defaults to 500 results (configurable).
ids	The list of SR IDs to return, comma separated
archive	Whether to return archived SRs. Value can be 1 or 0
sort	One or more fields to sort by. Available fields are those that were fetched by the request.
dir	Sort order: ascending or descending. Available values: asc/desc. Default is ‘asc’. Relevant only when sort parameter is sent.
{filters}	List of key-value parameters with {filter.id} as the key. and {filter.values.id} as the value. I.e.: …&status=19&request_user=235. Multiple values can be sent, comma-separated. I.e.: …&status=4,5

Important

User-related fields return the user’s ID, for additional user information, call user service.
Dates should be sent as milliseconds in UTC/GMT (since January 1, 1970).
In case of a specific date match, send only this date. For example:
- Match a date: &due_date=1398935657000
If a range of dates or from/to is required, send a 2-objects array of dates. If one of them is not available, set to 0. For example:
- Between dates: &due_date=1398935657000,1399313657000
- From date: &due_date=1398935657000,0
- To date: &due_date=0,1399313657000

Returns
A list of service records. For each SR, it returns the SR ID, user permissions to update/delete/archive the SR, and information fields as defined in the view and/or fields parameters. If none of them exist, returns full user information.

Sample JSON return value for /sr?view=SysAidMobile&fields=type,computer_id&limit=2

[
{
 “id”:”5433”,
 “canUpdate”:”true”,
 “canDelete”:”false”,
 “canArchive”:”false’,
 “info”: [
   {“key”:”title”,”keyCaption”:”Title”,”value”:”basic Service Request”,
                                                 ”valueCaption”:”basic Service Request”},
   {“key”:”insert_time”,”keyCaption”:”Request Time”,“value”:”13975648000”,   
                                                      valueCaption”:”2014-04-01 11:46:48”},
   {“key”:”request_user”,”keyCaption”:”Request User”,  
                    “value”:”leo@law.com”,”valueCaption”:”Leonardo Gonzales”},
   {“key”:”description”,”keyCaption”:”Description”, “value”:”Prezados Amos”,  
                                                         “valueCaption”:”Prezados Amos”},
  {“key”:”type,”keyCaption”:”Service Record Type”, “value”:”1”,
                                                        “valueCaption”:”Service Request”},
    {“key”:”computer_id”,”keyCaption”:”Asset ID”,“value”:”none”,
                                                                      “valueCaption”:”none”}]
},
{
  “id”:”5669”,
  “canUpdate”:”true”,
  “canDelete”:”false”,
  “canArchive”:”false’,
  “info”: [
   {“key”:”title”,”keyCaption”:”Title”,”value”:”Relatório de ocorrência”,
                                               ”valueCaption”:”Relatório de ocorrência”},
   {“key”:”insert_time”,”keyCaption”:”Request Time”,“value”:”1392026000”,   
                                                     valueCaption”:”2013-05-28 11:12:50”},
   {“key”:”request_user”,”keyCaption”:”Request User”,  
                    “value”:”leo@law.com”,”valueCaption”:”Leonardo Gonzales”},
   {“key”:”description”,”keyCaption”:”Description”, “value”:”Relatório de
                              ocorrência”,“valueCaption”:”Relatório de ocorrência”},
   {“key”:”type,”keyCaption”:”Service Record Type”, “value”:”1”,
                                                        “valueCaption”:”Service Request”},
   {“key”:”computer_id”,”keyCaption”:”Asset ID”,“value”:”DELL-3PXZ15J”,
                                                            ”valueCaption”:”DELL-3PXZ15J”}]
 }
]

Return values definition

Field	Description
id	The user ID
canUpdate	Whether the user has permission to update this SR
canDelete	Whether the user has permission to delete this SR
canArchive	Whether the user has permission to archive this SR
info	User info fields. An array of key-value fields, representing the SR information
info.key	The ID of the info field
info.keyCaption	The caption of the info field’s key
info.value	The field’s value
info.valueCaption	The field’s value caption. A string representation of the value for display.

Get Service Request Form

Returns the information for the specified service record.

Parameters

Field	Description
id	The service record ID (Required)
view	A SysAid view (tab) which defines the available fields in the service record form
fields	List of fields to return, comma separated. If sent together with view parameter, returns both view’s fields and the requested fields.

Returns
The service record ID, user permissions to update/delete/archive the SR, and info fields according to the requested view and/or fields parameters. If none specified, return full service record information. Each info field contains metadata like: whether the field is mandatory, default value, is it editable etc.

Sample JSON return value for /sr/273?fields=type,archive,update_time,status

{
    “id”:”273”,
    “canUpdate”:”true”,
    “canDelete”:”false”,
    “canArchive”:”false’,
    “info”: [{“key”:”sr_type”,
                 ”keyCaption”:”Service Record Type”,
                 ”value”:”1”,    
                 ”valueCaption”:”Service Request”,
                 ”mandatory”:true,
                 ”editable”:true,
                 ”type”:”list”,
                 ”defaultValue”:null},
               {“key”:”archive”,
                 ”keyCaption”:”Archive”,
                 ”value”:0,
                 ”valueCaption”:”0”,
                 ”mandatory”:false,
                 ”editable”:true,
                 ”type”:”boolean”,
                 ”defaultValue”:0},
                  {“key”:”update_time”,
                    ”keyCaption”:”Modify Time”,
                    ”value”:1391756438000,
                    ”valueCaption”:”2014-05-22 11:09:44”,
                ”mandatory”:false,
                ”editable”:true,
                ”type”:”date”,
                ”defaultValue”:null},
              {“key”:”status”,
                ”keyCaption”:”Status”,
                ”value”:1,                                                                   
                ”valueCaption”:”New”,
                ”mandatory”:true,
                ”editable”:true,
                ”type”:”list”,
                 ”defaultValue”:”New”}
}

Return values definition

Field	Description
id	The service record ID
canUpdate	Whether the user has permission to update this SR
canDelete	Whether the user has permission to delete this SR
canArchive	Whether the user has permission to archive this SR
info	Service record info fields as defined in the SR Form view and/or fields requested, or all available fields if none specified.
info.key	The ID of the info field
info.keyCaption	The caption of the info field’s key
info.value	The field’s value
info.valueCaption	The field’s value caption. A String representation of the value for display.
info.mandatory	A boolean that specifies whether this field is mandatory
info.editable	A boolean that specifies whether this field is editable or read-only
info.defaultValue	The default value for this field if a specified value is not available (null)
info.type	The field’s type. See available field types in Appendix A.

Search Service Request

Returns a list of service requests (SR), that matched the search criteria. Number of SRs to return can be controlled by offset, limit, and type parameters. Returned SRs can be filtered by filters (See Filter Service). Each Service Request, includes the fields according to view and/or fields parameters. If none specified, all SR fields are returned.

Parameters

Field	Description
query	The search criteria.
view	A SysAid view (tab) which defines the available fields in the service record form
fields	List of fields to return. If specified together with the view parameter, return all view's fields together with the specified fields. If none specified, return all SR fields.
type	The service record type. Available values are {incident,request,problem,change,all}. If not specified, returns incident type.
offset	SR count is limited (see limit parameter). This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0.
limit	The maximum number of SRs to retrieve per request. Defaults to 500 results (configurable).
archive	Whether to return archived SRs. Value can be 1 or 0
sort	One or more fields to sort by. Available fields are those that were fetched by the request.
dir	Sort order: ascending or descending. Available values: asc/desc. Default is ‘asc’. Relevant only when sort parameter is sent.
{filters}	List of key-value parameters with {filter.id} as the key. and {filter.values.id} as the value. I.e.: …&status=19&request_user=235. Multiple values can be sent, comma-separated. I.e.: …&status=4,5

Important

User-related fields return the user’s ID, for additional user information, call user service.
Dates should be sent as milliseconds in UTC/GMT (since January 1, 1970).
In case of a specific date match, send only this date. For example:
- Match a date: &due_date=1398935657000
If a range of dates or from/to is required, send a 2-objects array of dates. If one of them is not available, set to 0. For example:
- Between dates: &due_date=1398935657000,1399313657000
- From date: &due_date=1398935657000,0
- To date: &due_date=0,1399313657000

Sample JSON /sr/search?query=54&view=SysAidMobile&limit=2

[
{
“id”:”5433”,
“canUpdate”:”true”,
“canDelete”:”false”,
“canArchive”:”false’,
“info”: [
{“key”:”title”,”keyCaption”:”Title”,”value”:”basic Service Request”, ”valueCaption”:”basic Service Request”},
{“key”:”insert_time”,”keyCaption”:”Request Time”,“value”:”13975648000”, valueCaption”:”2014-04-01 11:46:48”},
{“key”:”request_user”,”keyCaption”:”Request User”, “value”:”leo@law.com”,”valueCaption”:”Leonardo Gonzales”},
{“key”:”description”,”keyCaption”:”Description”, “value”:”Prezados Amos”, “valueCaption”:”Prezados Amos”},
{“key”:”sr_type,”keyCaption”:”Service Record Type”, “value”:”1”, “valueCaption”:”Service Request”}]
},
{
“id”:”5469”,
“canUpdate”:”true”,
“canDelete”:”false”,
“canArchive”:”false’,
“info”: [
{“key”:”title”,”keyCaption”:”Title”,”value”:”Relatório de ocorrência”, ”valueCaption”:”Relatório de ocorrência”},
{“key”:”insert_time”,”keyCaption”:”Request Time”,“value”:”1392026000”, valueCaption”:”2013-05-28 11:12:50”},
{“key”:”request_user”,”keyCaption”:”Request User”, “value”:”leo@law.com”,”valueCaption”:”Leonardo Gonzales”},
{“key”:”description”,”keyCaption”:”Description”, “value”:”Relatório de ocorrência”,“valueCaption”:”Relatório de ocorrência”},
{“key”:”sr_type,”keyCaption”:”Service Record Type”, “value”:”1”, “valueCaption”:”Service Request”}]
}
]

Return values definition

Field	Description
id	the user ID
canUpdate	Whether the user has permission to update this SR
canDelete	Whether the user has permission to delete this SR
canArchive	Whether the user has permission to archive this SR
info	Service record information fields as defined in the SR Form view and/or fields requested, or all available fields if none specified.
info.key	The ID of the info field
info.keyCaption	The caption of the info field’s key
info.value	The field’s value
info.valueCaption	The field’s value caption. A tring representation of the value for display.

Update Service Request

Update a service request

Parameters

Field	Description
id	The service record ID

Payload:
A JSON string representing the service cords with the updated fields only.

Field	Description
id	The service record ID
info	Service record information fields as defined in the SR Form view and/or fields requested, or all available fields if none specified.
info.key	The ID of the info field
info.value	The field’s value

Sample JSON input for/sr/273, update the status, add a note, change assigned to user & modify time

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

Special Service Record Information Fields

Field

Description

notes

An array of Note objects. Each Note object consists of:

{“userName”:<user_name>,”createDate”:<creation date milliseconds>,”text”:<text>}

due_date

Long milliseconds in UTC/GMT (since January 1, 1970). insert_time is a read only field.

problem_type

Updates all 3 levels of categories.

A concatenation of the categories, with underscore delimiter: <problem_type>_<problem_sub_type>_<third_level_category>.

To update category- send only <problem_type>

To update sub category - send both <problem_type>_<problem_sub_type>

To update all 3 levels, send

<problem_type>_<problem_sub_type>_<third_level_category>

The following object type fields can be modified through a different API call:

Messages
attachments
links
activities

Read-only fields: history, chats, department, CI relations, computer_name

Count Service Request

Returns the number of SRs that are compatible with the provided filters.

Parameters

Field	Description
{filters}	List of key-value parameters with {filter.id} as the key. and {filter.values.id} as the value. I.e.: …&status=19&request_user=235. Multiple values can be sent, comma-separated. I.e.: …&status=4,5

Returns

Sample JSON return value for**/sr/count?computer_id=1

{
"count": 128
}

Return values definition

Field	Description
count	Number of SRs that are compatible with the provided filters

Close Service Request

Close a service record. Sets the service record status to the default Close status, as defined in the Help Desk settings.

Parameters

Field	Description
id	The service record ID

Payload:
A JSON string representing the solution.

Field	Description
solution	The solution

Sample JSON input for /sr/6/close
{“solution”:”restart the computer…”}

Get Service Request Template

Get a new service record template.

Parameters

Field	Description
view	A SysAid view which defines the available fields in the form. If view is not specified, check for the fields parameter. If none is specified, returns all fields.
fields	List of fields to return. If specified together with the view parameter, return all view's fields together with the specified fields. If none are specified, return all SR fields.
type	The service record type. Available values are {incident,request,problem,change,all}. If not specified, returns incident type.
template	The service record template ID, according to SR type. Defaults to the first/default template.

Returns
The service record information, according to the requested view and/or fields parameters. If none are specified, return full service record information. Each information field contains metadata like: whether the field is mandatory, default value, is it editable, etc.

Sample JSON return value for /sr/template?type=incident&template=39

{
  “id”:”0”,
  “info”: [{“key”:”request_user”,
              ”keyCaption”:”Request user”,
                 ”value”:149,    
                 ”valueCaption”:”shani1”,
                 ”mandatory”:true,
                 ”editable”:true,
                 ”type”:”list”,
                 ”defaultValue”:””},
               {“key”:”impact”,
                 ”keyCaption”:”Impact”,
                 ”value”:”Low”,
                 ”valueCaption”:”Low”,
                 ”mandatory”:false,
                 ”editable”:true,
                 ”type”:”list”,
                 ”defaultValue”:null},
                  {“key”:”status”,
                    ”keyCaption”:”Status”,
                    ”value”:”New”,
                    ”valueCaption”:”New”,
                ”mandatory”:true,
                ”editable”:true,
                ”type”:”list”,
                ”defaultValue”:2},
              {“key”:”title”,
                ”keyCaption”:”Title”,
               ”value”:”Cannot connect to a Wi-Fi network”,                                                                   
                ”valueCaption”:”Cannot connect to a Wi-Fi network”,
                ”mandatory”:true,
                ”editable”:true,
                ”type”:”text”,
                 ”defaultValue”:””}]
}

Return values definition

Field	Description
id	0 represents a template/new service record
info	Service Record information fields as defined in the SR Form view and/or fields requested, or all available fields if none specified.
info.key	The ID of the info field
info.keyCaption	The caption of the info field’s key
info.value	The field’s value
info.valueCaption	The field’s value caption. A tring representation of the value for display.
info.mandatory	A boolean that specifies whether this field is mandatory
info.editable	A boolean that specifies whether this field is editable or read-only
info.defaultValue	The default value for this field if a specified value is not available (null)
info.type	The field’s type. See available field types in Appendix A.

Create Service Request

Create a new service record and returns the newly created service record.

Parameters

Field	Description
view	A SysAid view which defines the available fields in the form. If view is not specified, check for the fields parameter. If none is specified, returns all fields.
fields	List of fields to return. If specified together with the view parameter, return all view's fields together with the specified fields. If none are specified, return all SR fields.
type	The service record type. Available values are {incident,request,problem,change,all}. If not specified, returns incident type.
template	The service record template ID, according to SR type. Defaults to the first/default template.

Payload:
A JSON string representing the new service record.

Field	Description
info	Service record’s updated info fields. Each field contains a key-value pair.
info.key	The ID of the info field
info.value	The info field value

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”:”problem_type”,“value”:“UserWorkstation_PC_Password” }
            {“key”:”notes”,”value”:[
            {“userName”:”sysaid”,”createDate”:1391756438000,”text”:”Note 123”}
             ]},
             {“responsibility”:66}]
}

Special Service Record Information Fields

Field	Description
notes	An array of Note objects. Each Note object consists of: {“userName”:<user_name>,”createDate”:<creation date milliseconds>,”text”:<text>}
due_date	Long milliseconds in UTC/GMT (since January 1, 1970). insert_time is a read only field.
problem_type	Use this key to add all the categories in a single value. For example: “value”:Cat1_SubCat1_ThirdCat1”. For more information, see the input example above.

Returns
The new service record information, according to the requested view and/or fields parameters. If none is specified, return the full service records information. Each info field contains metadata like: whether the field is mandatory, default value, is it editable, etc.

Sample JSON return value for POST /sr?view=Mobile&type=incident&template=39

{
  “id”:”45”,
  “info”: [{“key”:”request_user”,
              ”keyCaption”:”Request user”,
                 ”value”:149,    
                 ”valueCaption”:”shani1”,
                 ”mandatory”:true,
                 ”editable”:true,
                 ”type”:”list”,
                 ”defaultValue”:””},
               {“key”:”impact”,
                 ”keyCaption”:”Impact”,
                 ”value”:”High”,
                 ”valueCaption”:”High”,
                 ”mandatory”:false,
                 ”editable”:true,
                 ”type”:”list”,
                 ”defaultValue”:null},
                  {“key”:”status”,
                    ”keyCaption”:”Status”,
                    ”value”:”New”,
                    ”valueCaption”:”New”,
                ”mandatory”:true,
                ”editable”:true,
                ”type”:”list”,
                ”defaultValue”:2},
              {“key”:”title”,
                ”keyCaption”:”Title”,
                ”value”:”Cannot connect to a Wi-Fi network”,                                                               
                ”valueCaption”:”Cannot connect to a Wi-Fi network”,
                ”mandatory”:true,
                ”editable”:true,
                ”type”:”text”,
                 ”defaultValue”:””}]
}

Return values definition

Field	Description
id	0 represents a template/new service record.
info	Service record info fields as defined in the SR Form view and/or fields requested, or all available fields if none specified.
info.key	The ID of the info field
info.keyCaption	The caption of the info field’s key
info.value	The field’s value.
info.valueCaption	The field’s value caption. A String representation of the value for display.
info.mandatory	A boolean that specifies whether this field is mandatory
info.editable	A boolean that specifies whether this field is editable or read-only
info.defaultValue	The default value for this field if a specified value is not available (null)
info.type	The field’s type. See available field types in Appendix A.

After the service record is created, the following Object type fields can be added to the new service record through their different API calls:

Messages
Attachments
Links
Activities

Delete Service Request

Delete one or more service records

Parameters

Field	Description
ids	A list of comma separated SR IDs to delete.

Add Service Request Link

Add a link to a service record

Parameters

Field	Description
id	The service record ID.

Payload
A JSON string representing the link.

Field	Description
name	The new link name.
link	The link URL.

Sample JSON input for /sr/6/link
{"name":"link2","link":"http://google.co.il"}

Delete Service Request Link

Delete a link from a service record.

Parameters

Field	Description
id	The service record id.

Payload
A JSON string representing the link name to delete

Field	Description
name	The deleted link name

Sample JSON input for /sr/6/link
{"name":"link2"}

Add Service Request Attachment

Add an attachment to a service record.

Parameters

Field	Description
id	The service record ID.

Payload
File Multipart/Form data.

Delete Service Request Attachment

Delete an attachment from a service record.

Parameters

Field	Description
id	The service record ID.

Payload
A JSON string representing the attachment file ID to delete.

Field	Description
fileId	The deleted attachment file ID.

Sample JSON input for /sr/6/attachment
{"fileId":"111934645_312638760"}

Add Service Request Activity

Add an activity to a service record.

Parameters

Field	Description
id	The service record ID.

Payload
A JSON string representing the new activity.

Field	Description
userId	The new activity’s user name.
fromTime	The activity's start time.
toTime	The activity's end time.
description	The description of the new activity.

Sample JSON input for /sr/6/activity
{"userId":"sysaid","fromTime":"1378501200000","toTime":"1378846800000","description":"This is an activity from API"}

The total time is automatically calculated.

Delete Service Request Activity

Delete an activity from service record

Parameters

Field	Description
id	The service record ID.

Payload
A JSON string representing the deleted activity ID.

Field	Description
id	The deleted activity ID.

Sample JSON input for /sr/6/activity
{"id":2}

Send Message From Service Request

Send a message from a Service Record form.

Parameters

Field	Description
id	The service record ID (Required)
method	The Send method. Can be email, SMS, broadcast, or IM (instant message). Defaults to email.
addAttachmentToSr	Whether to add message attachments to a service record. The value can be either true or false. The default is true.
addSrDetails	Whether to add the service record details to the message. The value can be either true or false. The default is true.

Payload
Multipart data including one or more files attached to the message, and a JSON string representing the new message.

Field	Description
file	Multipart file part. Can be one or more files to attach to the message.
message	A non-encoded JSON string representing the new message.
message.fromUserId	The sender user ID.
message.toUsers	The IDs of the users in the To field. A comma-separated string, with users IDs. If there's a group, the group ID should be surrounded by [ ]. I.e.: “1,23,22,45,[3],67”.
message.ccUsers	The IDs of the user in the CC field. A comma-separated string, with users IDs. If there's a group, the group ID should be surrounded by [ ]. I.e.: “1,23,22,45,[3],67”.
message.msgSubject	The message subject.
message.msgBody	The message body.

Sample JSON input for /sr/6/message

{"fromUserId":"124","toUsers":"1,140,123,124","ccUsers":"3,125,127,[11]","msgSubject":"This is a message from API","msgBody":"Hello Hello Hello ......."}

Note

If the list of To and/or CC users include invalid email addresses or addresses that belong to disabled users, these addresses are ignored and written to the logs as invalid. Other valid addresses will receive the mail.

Action Items

Get action items

Get a list of action items

Parameters

Field	Description
view	A SysAid view which defines the available fields. If view is not specified, check for the fields parameter. If none is specified, returns all fields.
fields	List of fields to return. Comma-separated. If sent together with the view parameter, return both view's fields together with the specified fields. If none is specified, return all SR fields.
type	The service record type. Available values are {incident,request,problem,change,all}. If not specified, returns incident type.
ids	A list of comma-separated SR IDs to return their action items.
{filters}	List of key-value parameters with {filter.id} as the key. and {filter.values.id} as the value. I.e.: …&status=19&request_user=235. Multiple values can be sent, comma-separated. I.e.: …&status=4,5 The Status filter can also be set to "active" to retrieve only active action items.
staticFilterId	The Static filter from the scoreboard.
archive	Whether to return archived action items. Values can be 1 or 0.
query	The search criteria
offset	Action items count is limited (see limit parameter). This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0. Zero based.
limit	The maximum number of action items to retrieve per request. Defaults to 500 (configurable).
sort	One or more fields to sort by, from the fields that were fetched by the request.
dir	Sort order: ascending or descending. Available values: asc/desc. Default is ‘asc’. Relevant only when sort parameter is sent.

Returns
A list of action item

Sample JSON return value

[{
“id”:”24”,
“tabName”:”1”,
“subTabName”:”2”,
“hasApproved”:”true”,
“hasEmptyRequred”:”false”
},
{
“id”:”25”,
“tabName”:”1”,
“subTabName”:”2”,
“hasApproved”:”false”,
“hasEmptyRequred”:”false”
}]

Count Action Items

Count action items

Parameters

Field	Description
view	A SysAid view which defines the available fields. If view not specified, check for fields parameter. If not specified, returns all fields.
fields	A list of fields to return. Comma separated. If sent together with the view parameter, it returns both view's fields and the requested fields. If not specified, returns all fields.
type	The requested service record type. Available values are {incident,request,problem,change,all}. If not specified, returns incident type. Multiple comma-separated values can be sent. I.e.: …&type=incident,request. If not specified, returns all.
ids	A list of comma-separated SR IDs to return their action items.
{filters}	List of key-value parameters with {filter.id} as the key. and {filter.values.id} as the value. I.e.: …&status=19&request_user=235. Multiple values can be sent, comma-separated. I.e.: …&status=4,5
staticFilterId	The Static filter from the scoreboard.
archive	Whether to return archived SRs. Values can be 1 or 0.
query	Search criteria

Returns
The number of action items.

Sample JSON return value

{
"count":24
   }

Approve Action Items

Approve action items

Parameters

Field	Description
id	The action item ID

Reject Action Items

Reject action items

Parameters

Field	Description
id	The action item ID.

Complete Action Items

Complete action items

Parameters

Field	Description
id	The action item ID.

Reopen Action Items

Reopen action items

Parameters

Field	Description
id	The action item ID.

Assets

Get Assets List

Get a list of assets in SysAid.

Parameters

Field	Description
view	A SysAid view which defines the available fields (Mobile view is called ‘SysAidMobileAssets’).
fields	List of fields to return. Comma-seperated. If sent together with the view parameter, return both view's fields together with the specified fields.
offset	Retrieved Assets count is limited (see limit parameter). This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0. Zero based.
limit	The maximum number of assets to retrieve per request. Defaults to 500 (configurable).

Returns
A list of assets. For each asset returns the asset ID, asset name, group name and information as defined in the view and/or fields parameters. If none of them exist, return full asset information.

Sample JSON return value for /asset?fields=computer_type,ip_address,serial&limit=2

[
    {
“id”:”497db453:147bee7ec09:-7ff2”,
       “name”:”ISA-VCHER-DW7”,
       “group”:”\”,
       “info”: [{“key”:”computer_type”,”key_caption”:”Type”,  
                    ”value”:”Workstation”,”value_caption”:”Workstation”},
                  {“key”:”ip_address”,”key_caption”:”IP Address”,  
                    “value”:”10.1.10.131”,“value_caption”:”10.1.10.131”},
                  {“key”:”serial”,“key_caption”:”Serial”,
                    “value”:”3PXZ15J”, “value_caption”:”3PXZ15J”}]
   },
   {
“id”:”9F38X-RDDTC-RHRXT-GX6XR-DDXRJ”,
       “name”:”VISTA-X64”,
       “group”:”\”,
       “info”: [{“key”:”computer_type”,”key_caption”:”Type”,  
                    ”value”:”Workstation”,”value_caption”:”Workstation”},
                  {“key”:”ip_address”,”key_caption”:”IP Address”,  
                    “value”:”10.1.10.30”,“value_caption”:”10.1.10.30”},
                  {“key”:”serial”,“key_caption”:”Serial”,
                    “value”:”4JS8L2J”, “value_caption”:”4JS8L2J”}]
   }
]

Return values definition

Field	Description
id	The asset ID
name	The asset name
group	The asset’s group name
info	Additional asset info fields
info.key	The ID of the info field
info.keyCaption	The caption of the info field’s key
info.value	The field’s value
info.valueCaption	The fields' values' caption. A String representation of the value for display.

Get Asset

Get information on the specified asset.

Parameters

Field	Description
view	Optional: A SysAid Asset Form view that defines the available fields.
fields	Optional: A list of fields to return. Comma separated. If sent together with the view parameter, it returns both view's fields and the requested fields.

Returns
The asset ID, asset name, group name, and information as defined in the view and/or fields parameters. If none of them exist, return full asset information.

Sample JSON return value for /asset/497db453:147bee7ec09:-7ff2?fields=computer_type,ip_address,serial

{
“id”:”497db453:147bee7ec09:-7ff2”,
       “name”:”ISA-VCHER-DW7”,
       “group”:”\”,
       “info”: [{“key”:”computer_type”,”key_caption”:”Type”,  
                    ”value”:”Workstation”,”value_caption”:”Workstation”},
                  {“key”:”ip_address”,”key_caption”:”IP Address”,  
                    “value”:”10.1.10.131”,“value_caption”:”10.1.10.131”},
                  {“key”:”serial”,“key_caption”:”Serial”,
                    “value”:”3PXZ15J”, “value_caption”:”3PXZ15J”}]
   }

Return values definition

Field	Description
id	The asset ID
name	The asset name
group	The asset’s group name
info	Additional asset info fields
info.key	The ID of the info field
info.keyCaption	The caption of the info field’s key
info.value	The field’s value
info.valueCaption	The fields' values' caption. A String representation of the value for display.

Search Asset

Get list of assets in SysAid, that matched the search criteria

Parameters

Field	Description
query	The search criteria (Required)
view	A SysAid Asset Form view that defines the available fields.
fields	A list of fields to return. Comma-separated. If sent together with the view parameter, it returns both view's fields and the requested fields.
offset	Retrieved Assets count is limited (see limit parameter). This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0. Zero based.
limit	The maximum number of assets to retrieve per request. Defaults to 500 (configurable).

Returns
A list of assets that match the search criteria. For each asset the command returns the asset ID, asset name, group name, and information as defined in the view and/or fields parameters. If none of them exist, return full asset info.

Sample JSON return value for /asset/search?query=DW7&fields=computer_type,ip_address,serial&limit=2

[
{
“id”:”497db453:147bee7ec09:-7ff2”,
“name”:”ISA-VCHER-DW7”,
“group”:”\”,
“info”: [{“key”:”computer_type”,”key_caption”:”Type”, ”value”:”Workstation”,”value_caption”:”Workstation”},
{“key”:”ip_address”,”key_caption”:”IP Address”, “value”:”10.1.10.131”,“value_caption”:”10.1.10.131”},
{“key”:”serial”,“key_caption”:”Serial”, “value”:”3PXZ15J”, “value_caption”:”3PXZ15J”}]
}
]

Return values definition

Field	Description
id	The asset ID
name	The asset name
group	The asset’s group name
info	Additional asset info fields
info.key	The ID of the info field
info.keyCaption	The caption of the info field’s key
info.value	The field’s value
info.valueCaption	The fields' values' caption. A String representation of the value for display.

Lists

Get All Lists

Get all available lists and their values.

Parameters

Field	Description
entity	A SysAid entity by which to retrieve the available lists. Defaults to SR. For a list of available entities, see Appendix B.
fields	A comma-separated list of fields to return. Available fields to return are: id (always returned), caption, and values.
offset	Retrieved values count is limited. This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0. Zero base.
limit	The maximum number of list values to retrieve per request. Defaults to 500 (configurable).

Returns
The available lists, including their values, per entity type. Defaults to SR.

Sample JSON return value for list?entity=sr

{
 { “id”:”location”,
    “caption”:”Location”,
    “values”: [{“id”:”1”,”caption”:”Loc1”},
                   {“id”:”2”,”caption”:”Loc2”}]
 },
{ “id”:”impact”,
    “caption”:”Impact”,
    “values”: [{“id”:”1”,”caption”:”Very High”},
                   {“id”:”2”,”caption”:”Low”}]
 },
{ “id”:”urgency”,
    “caption”:”Urgency”,
    “values”: [{“id”:”1”,”caption”:”Urgent”},
                   {“id”:”2”,”caption”:”Normal”}]
 },
{ “id”:”priority”,
    “caption”:”Priority”,
    “values”: [{“id”:”1”,”caption”:”Highest”},
                   {“id”:”2”,”caption”:”High”},
                   {“id”:”3”,”caption”:”Low”}]
 },
{ “id”:”change_category”,
    “caption”:”Classification”,
    “values”: [{“id”:”1”,”caption”:”Minor”},
                   {“id”:”2”,”caption”:”Significant”},
                   {“id”:”3”,”caption”:”Major”}]
 },
{ “id”:”survey_status”,
    “caption”:”Survey Status”,
    “values”: [{“id”:”1”,”caption”:”Not Sent”},
                   {“id”:”2”,”caption”:”Sent”}]
 },
{ “id”:”sr_type”,
    “caption”:”Service Record type”,
    “values”: [{“id”:”1”,”caption”:”Change”},
                   {“id”:”2”,”caption”:”Problem”},
                   {“id”:”3”,”caption”:”Incident”},
                   {“id”:”4”,”caption”:”Request”}]
 },
{ “id”:”responsibility”,
    “caption”:”Assigned to”,
    “values”: [{“id”:”3”,”caption”:”SysAid”},
                   {“id”:”124”,”caption”:”QA-LAB\Administrator”}]
 },
{ “id”:”status”,
    “caption”:”Status”,
    “values”: [{“id”:”1”,”caption”:”Open”},
                   {“id”:”2”,”caption”:”Closed”}]
 },
{ “id”:”company”,
    “caption”:”Company”,
    “values”: [{“id”:”1”,”caption”:”Company 1”},
                   {“id”:”2”,”caption”:”Company 2”}]
 },
{ “id”:”department”,
    “caption”:”Department”,
    “values”: [{“id”:”1”,”caption”:”IT”},
                   {“id”:”2”,”caption”:”R&D”}]
 },
{ “id”:”agreement”,
    “caption”:”Agreement”,
    “values”: [{“id”:”1”,”caption”:”DEFAULT SLA”},
                   {“id”:”2”,”caption”:”Agreement 2”}]
 },
{ “id”:”source”,
    “caption”:”Source”,
    “values”: [{“id”:”1”,”caption”:”Administrator Portal”},
                   {“id”:”2”,”caption”:”Agent”},
                   {“id”:”3”,”caption”:”Email”},
                   {“id”:”4”,”caption”:”Chat”}]
 },
{ “id”:”cust_list1”,
    “caption”:”SR Custom list 1”,
    “values”: [{“id”:”1”,”caption”:”Cust Val 1”},
                   {“id”:”2”,”caption”:”Cust Val 2”}]
 },
{ “id”:”cust_list2”,
    “caption”:”SR Custom list 2”,
    “values”: [{“id”:”1”,”caption”:”Cust Val 3”},
                   {“id”:”2”,”caption”:”Cust Val 4”}]
 },
}

Return values definition

Field	Description
id	The list ID
caption	The list caption
values	An array of list values
values.id	The ID of the value item
values.caption	The caption of the value item

Get List

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.

Parameters

Field	Description
entity	A SysAid entity by which to retrieve the available lists. Defaults to SR. For a list of available entities, see Appendix B.
entityId	The entity's ID. For example, in SR Form lists, send the SR ID to populate additional filters on the lists. e.g. the responsibility list may be filtered by the admin group of the SR.
fields	A comma-separated list of fields to return. Available fields to return are: id (always returned), caption, and values.
offset	Retrieved values count is limited. This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0. Zero base.
limit	The maximum number of list values to retrieve per request. Defaults to 500 (configurable).
entityType	Numeric. for example: in sr entity, send the sr_type id, for ci entity, send the ci type id ( e.g. for getting the list of CI sub types).
key	Relevant for users/groups related fields. Defines whether to use the id or the name as the key for each value in the result. Available values are “name” or “id”. Defaults to id.

Returns
The available lists, including their values, per entity type. Defaults to SR.

Sample JSON return value for list/responsibility?entity=sr&entityid=6

{ “id”:”priority”,
“caption”:”Priority”,
“values”: [{“id”:”1”,”caption”:”Highest”},
{“id”:”2”,”caption”:”High”},
{“id”:”3”,”caption”:”Low”}]
}

Return values definition

Field	Description
id	The list ID
caption	The list caption
values	An array of list values
values.id	The ID of the value item
values.caption	The caption of the value item

Add-ons

List application add-ons

Get a list of all available add-ons.

Parameters

This API doesn’t receive any parameters.

Returns
Return a list of available add-ons.

Sample JSON return value for add-ons

[
 {
   "name": "sage",
   "title": "Sage ERP X3",
    "description": "The Sage Identity Management System(AIMS) Ticketing Integration app allows AIMS to create, update and automate",
   "logoFileName": "images/bomgarLogo.png",
   "version": 1,
   "addonType": "Remote Control",
   "link": "http://www.sysaid.com/doc/installSage.html",
   "linkText": "Sage installation instructions",
   "active": false,
   “implemented”: true,
   “params”: null
 },
 {....}
]

Return values definition

Field	Description
name	The name of the add-on
title	The title of the add-on
description	A short description of the add-on
logoFileName	A relative URL to a small logo image of the add-on
version	The add-on version
addonType	A string representing the add-on category/group
link	Link for getting more information about this add-on
linkText	Optional: A text to be displayed to the user when the above link is displayed.
active	Is this add-on active (true/false)?
implemented	Is this add-on have a packed implementation? (add-ons that are not implemented are delivered through the PS)
params	Always null when receiving a list of add-ons

Get add-on parameters

Returns the full information about an addon with all it’s parameters.

Parameters

Field	Description
add-on name	The name of the add-on

Returns
The add-on with all its parameters.

Sample JSON return value for /addons/bomgar

{
   "name": "bomgar",
   "title": "Bomgar",
   "description": "Bomgar i a provider of secure remote support solutions that enable technology professionals",
   "logoFileName": "addons/bomgar/images/bomgarLogo.png",
   "version": 1,
   "addonType": "Remote Control",
   "link": "https://www.sysaid.com/tools/third-party-integrations",
   "linkText": "",
   "active": true,
   "implemented": true,
   "params": [
       {
           "name": "bomgar_url",
           "description": "Bomgar RC integraton URL",
           "value": "https://sysaid.bomgar.com",
           "type": "text",
           "mandatory": true,
           "editable": true,
           "encrypted": false
       },
       {
           "name": "bomgar_user_name",
           "description": "Bomgar User Name",
           "value": “MyBomgarUserName”,
           "type": "text",
           "mandatory": true,
           "editable": true,
           "encrypted": false
       },
       {
           "name": "bomgar_password",
           "description": "Bomgar Password",
           "value": “MyPassword”,
           "type": "text",
           "mandatory": true,
           "editable": true,
           "encrypted": true
       }
   ]
}

Return values definition

Field	Description
name	The name of the add-on
title	The title of the add-on
description	A short description of the add-on
logoFileName	A relative URL to a small logo image of the addon
version	The version of the add-on
adonType	A string representing the add-on category/group
link	Link for getting more information about this add-on
linkText	A text that needs to be displayed to the user when the above link is displayed (Optional)
active	Is this add-on active (true/false)?
implemented	Does this add-on have a packed implementation (add-ons that are not implemented are delivered through the PS)?
params	An array list of parameters
params.name	The name of the parameter
params.description	A description of the parameter
params.value	The value of the parameter
params.type	The parameter type
params.mandatory	Is this a mandatory parameter?
params.editable	Can the user edit the value of this parameter?
params.encrypted	Should the display of this parameter value act like a password field (show to the user starts instead of real value)

Update add-on parameters

Update an add-on parameters

Parameters

Field	Description
addon name	The name of the add-on

Payload:

A JSON string representing the add-on parameters with the update values. The list below will contain only the fields that can be updated. Any changes to other fields are ignored.

Field	Description
active	Is this addon active (true/false)
params.value	The updated parameter value

Sample JSON input /addon/bomgar, update the user name and password fields

{
   "name": "bomgar",
   "active": true,
   "params": [
       {
           "name": "bomgar_url",
           "value": "https://sysaid.bomgar.com",
       },
       {
           "name": "bomgar_user_name",
           "value": "MyUserName",
       },
       {
           "name": "bomgar_password",
           "value": "MyPassword",
       }
   ]

Returns
New http header with success message or error text.

Test add-on connection

Test the add-on parameters.

Parameters

Field	Description
addon name	The name of the addon

Payload
A JSON string representing the add-on parameters to test. The list below will contain only the fields that can be checked. Any changes to other fields are ignored.

Field	Description
active	Is this add-on active (true/false)
params.value	The updated parameter value

Sample JSON input /addon/bomgar/testConnection, test the parameters for bomgar addon

{
   "name": "bomgar",
   "active": true,
   "params": [
       {
           "name": "bomgar_url",
           "value": "https://sysaid.bomgar.com",
       },
       

           "name": "bomgar_user_name",
           "value": "MyUserName",
       },
       {
           "name": "bomgar_password",
           "value": "MyPassword",
       }
   ]
}

Returns
New http header with success message or error text.

Refresh Add-ons List

Refresh the addons list immediately.

Parameters

None

Returns
Upon successful refresh return a message and a success status.

CIs

Create CI

Create a CI

Payload

A JSON string representing the CI with the updated fields only.


info	CI’s updated information fields. An array of key-value fields
info.key	The id of the information field
info.value	The field's value

Sample JSON post params for POST/ci

{
   "info": [
            {"key":"ci_name","value":"Test CI from api 1"},
            {"key":"ci_type", "value":"69"},
            {"key":"company", "value":"3"},
            {"key":"ci_cust_text_1","value":"test short text entry"},
            {"key":"ci_cust_date_1", "value":"1636282614000"}
            ]
}

Get CI List/Form

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.

Parameters

Field	Description
view	A SysAid view which defines the available fields in the list. If view is not specified, check for the fields parameter. If none is specified, returns all fields.
fields	List of fields to return. If specified together with the view parameret, return all view's fields together with the specified fields. If none are specified, return all CI fields.
offset	CI count is limited (see limit parameter). This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0.
limit	The maximum number of CIs to retrieve per request. Defaults to 500 results (configurable under serverConf>apiConf>maxChunkSize).
ids	The list of CI IDs to return, comma separated.
sort	One or more fields to sort by, from the fields that were fetched by the request.
dir	Sort order: ascending or descending. Available values: asc/desc. Default is ‘asc’. Relevant only when sort parameter is sent.
{filters}	List of key-value parameters with {filter.id} as the key. and {filter.values.id} as the value. I.e.: …&status=19&request_user=235. Multiple values can be sent, comma-separated. I.e.: …&status=4,5
supportBarcode	Flag to indicate that the CI supports barcodes.

Important

User-related fields return the user’s ID, for additional user information, call user service.
Dates should be sent as milliseconds in UTC/GMT (since January 1, 1970).
In case of a specific date match, send only this date. For example:
- Match a date: &due_date=1398935657000
If a range of dates or from/to is required, send a 2-objects array of dates. If one of them is not available, set to 0. For example:
- Between dates: &due_date=1398935657000,1399313657000
- From date: &due_date=1398935657000,0
- To date: &due_date=0,1399313657000

Returns
A list of CIs. For each CI, an ID is returned with the info fields defined in the view and/or fields parameters. If no fields are specified, it returns the full CI information.

Sample JSON return value for /ci/barcode?view=SysAidMobile&fields=ci_name,location&limit=2

[
{
 “id”:”5433”,
…….
 }
]

Return values definition

Field	Description
id	The user ID
info	CI fields. An array of key-value fields, representing the CI information
info.key	The ID of the info field
info.keyCaption	The caption of the info field’s key
info.value	The field’s value
info.valueCaption	The field value’s caption. A string representation of the value for display.
info.mandatory	A boolean that specifies whether this field is mandatory
info.editable	A boolean that specifies whether this field is editable or read only
info.defaultValue	The default value for this field is not available (null)
info.type	The field’s type. See available field types in Appendix A.

Update CI

Update a CI.

Parameters

Field	Description
id	The CI ID

Payload
A JSON string representing the CI with the updated fields only.

Field	Description
Field	Description
id	The user ID
info	CI’s updated info fields. An array of key-value fields.
info.key	The id of the info field
info.value	The field’s value

Sample JSON input /ci/273, update the status, change owner & accept date

{
  “id”:”273”,
  “info”: [{“key”:”accept_date”, ”value”:1391756438000},
            {“key”:”status”, ”value”:2},
             {“owner”:”sysaid”}]
}

Get CI Types

Returns the available CI types.
If the barcode flag is requested, returns only CI types with barcode support (if the add-on is available).

Parameters

Field	Description
barcode	Whether to retrieve only CI types with barcode support. Available options: true/false.

Returns
A list of CI types. Each type includes its ID, name, description, and whether the type is predefined.

Sample JSON return value for ci/type

[
    {
“id”:”53”,
       “name”:”Administrator”,
       “description”:””,
       “predefined”: “true”
   },
    {
“id”:”1”,
       “name”:”Asset”,
       “description”:”System Asset
                         (Workstation,Server,Laptop,Printer,PDA,Other)”,
       “predefined”: “true”
   },
    {
“id”:”6”,
       “name”:”Business Process”,
       “description”:””,
       “predefined”: “false”
   },
    {
“id”:”7”,
       “name”:”Catalog”,
       “description”:”System Asset Catalog”,
       “predefined”: “true”
   },
    {
“id”:”52”,
       “name”:”End User”,
       “description”:””,
       “predefined”: “true”
   }
]

Return values definition

Field	Description
id	The CI type ID
name	The CI type name
descriptions	The CI type description
predefined	Whether the CI type is predefined

Get CI View

Returns the fields contained in the specified view.

Parameters

Field	Description
view	The name of the view to retrieve. A combination of view name and CI type id will determine the fields that will be returned.

Returns
A list of fields with the requested view.

Note

The returned list always contains the ID field. If the ID field is a part of the view, it appears in its correct place. If it isn’t a part of the view then it appears at the end of the list.

Sample JSON return value for /ci/view/180?view=barcode_book

[
   {
       "key": "ci_type",
       "value": null,
       "mandatory": false,
       "editable": false,
       "type": "list",
       "defaultValue": null,
       "displayOrder": 1,
       "keyCaption": "CI Type",
       "valueCaption": null
   },
   {
       "key": "owner",
       "value": null,
       "mandatory": false,
       "editable": true,
       "type": "list",
       "defaultValue": null,
       "displayOrder": 2,
       "keyCaption": "Owner",
       "valueCaption": null
   },
    {

     ………
    },
   {
       "key": "id",
       "value": null,
       "mandatory": false,
       "editable": true,
       "type": "numeric",
       "defaultValue": null,
       "displayOrder": 14,
       "keyCaption": "#",
       "valueCaption": null
   }
]

Return values definition

Field	Description
key	The ID of the info field
keyCaption	The caption of the info field’s key
value	The field’s value
valueCaption	The field values' caption. A string representation of the value for display.
mandatory	A boolean that specifies whether this field is mandatory
editable	A boolean that specifies whether this field is editable or read-only
defaultValue	The default value for this field if value is not available (null)
type	The field’s type. See available field types in Appendix A.

Get CI Relation Types

An API for retrieving CI relation type definitions.

Returns
Returns all the valid CI relation types defined in SysAid database and their ID numbers.

Note

A returned CI relation type element uniquely identified by the “relationTypeId” field.

Sample JSON return value for ci/relationtypes

[
   {
    "relationTypeId": 5,
    "relationName": "Accessed by",
    "oppositeRelationName": "Can access"
   },
   {
    "relationTypeId": 4,
    "relationName": "Connected to",
    "oppositeRelationName": "Connected to"
   }
]

Return values definition

Field	Description
relationTypeId	The CI Relation Type ID
relationName	Textual description of the CI relation type
oppositeRelationName	Textual description of the way the given CI relation type is presented from the destination CI’s point of view (a textual description of another CI relation type that exists in the SysAid system)

Get CI Relation

An API to retrieve all the destination CIs and their relation types, which are associated to a given CI Id.

Returns
Returns a list that contains all the destination CI and their prospective CI relationship types associated to the CI ID.

Sample JSON return value for /ci/9/relation

[
   {
      "src": 9,
      "dest": 1,
      "ciRelationType": 2
   },
   {
     "src": 9,
     "dest": 2,
     "ciRelationType": 3
},
    {
     ………
    },
   {
    "src": 9,
    "dest": 5,
    "ciRelationType": 5
   }
]

Return values definition

Field	Description
src	The source CI ID (the same as the CI ID passed by the Path Parameter call of the API)
dest	The target CI ID that the CI ID is associated to
ciRelationType	The CI Relationship Type ID that describes the Source CI’s association to the destination CI ID

Create CI Relations

API for creating one or more relations for a given CI ID.

Parameters

An array of one or more objects comprising of the following fields in each element

Field	Description
dest	The CI ID of a pre-existing Ci in the system that the CI ID needs to be associated to
ciRelationType	The CI relation type that describes this CI’s association with the destination CI ID (must be a valid CI relation type ID - use Get Ci/Relationtypes API to retrieve the available relation types in the system

Returns
OK if all relations in the list have been generated successfully, or if the relations already exist in the system (does not generate duplicates in the database)
An exception is thrown, containing a parsable (.csv format) string of the relations in the list that failed the creation process.

Sample JSON post params for /ci/9/relation

[
 {
    "dest":2,
    "ciRelationType":3
 },
 {
    "dest":1,
    "ciRelationType":2
 },
 {
    "dest":3,
    "ciRelationType":11
  }
]

Sample error message for a partially failed list

{
 "status": 400,
 "message": "Ci:9 Invalid CI id 100,Ci:9 Invalid CI Relation type 11"
}

Delete CI Relations

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

Parameters

An array of one or more objects comprising of the following fields in each element

Field	Description
dest	The CI ID of a pre-existing Ci in the system that the CI ID needs to be associated to
ciRelationType	The CI relation type that describes this CI’s association with the destination CI ID (must be a valid CI relation type ID - use Get Ci/Relationtypes API to retrieve the available relation types in the system

Returns
Always Returns OK (unless the user is not logged in or is not authorized to perform the call), even if non-existent CI relations or CI destinations were passed to the API

Sample JSON post params for /ci/9/relation

[
 {
    "dest":2,
    "ciRelationType":3
 },
 {
    "dest":1,
    "ciRelationType":2
 },
 {
    "dest":3,
    "ciRelationType":11
  }
]

Resource Bundle

Get RB Translated Keys

Get array of translated keys according to the account location.

Parameters

None.

Payload
A JSON string representing array of Resource Bundle keys.

Field	Description
key	Resource Bundle key

Sample JSONinput /rb

[
 {
   "key":"dir"
 }
]

Returns
A list of translated keys.

Sample JSON return value for /rb

[
 {
     key: "dir"
     value: "LTR"
 }
]

Return values definition

Field	Description
key	Resource Bundle key
value	The value according to the account's location.

Get RB Translated Keys With Given Location

Get array of translated keys according to the given location.

Parameters

Field	Description
locale	The location to display the translated keys.

Payload
A JSON string representing array of Resource Bundle keys.

Field	Description
key	Resource Bundle key

Sample JSON input /rb

[[
 {
   "key":"dir"
 }
]

Returns
A list of translated keys.

Sample JSONreturn value for /rb/{locale}

[
  {
    key: "dir"
    value: "LTR"
  }
]

Return values definition

Field	Description
key	Resource Bundle key.
value	The value according the given location in the path.

Password Services

Get LDAP Domains

Get LDAP domains.

Parameters

None.

Payload

None.

Returns
A list of LDAP domains.

Sample JSON return value for /ps/domain

["ILIENT-HQ","PM-TEST","QA-LAB"]

Return values definition
List of domains as an array of strings.

Get Password Services Permission

Retrieves a llist all Password Services permissions.

Parameters

None.

Payload

None.

Returns
JSON representing Password Services permission.

Sample JSON return value for /ps/permission

{
enableUserSelfServices: true
enableUnlockAccount: true
enableResetPassword: true
enableLdapSupport: true
enableUserReset: false
}

Return values definition

Field	Description
enableUserSelfServices	True - if the PS module is enabled.
enableUnlockAccount	True - if the Unlock Account is enabled.
enableResetPassword	True - if the Reset Password is enabled.
enableLdapSupport	True - if we have LDAP support.
enableUserReset	True - if the reset password method is “user”.

Get Security Question

Get a list of all security questions for a given user.

Parameters

Field	Description
method	reset/unlock

Payload
A JSON string representing the userName and domain name.

Field	Description
userName	userName in the system
domainName	user’s domain

Returns
JSON representing Security Questions object.

Sample JSON return value for /ps/reset/question

{
   "userRefId": 842,
   "userId": "QA-LAB\\test11",
   "userSecurityQuestionsList": [
       {
           "id": 1,
           "question": "In which city were you born?"
       },
       {
           "id": 2,
           "question": "In which state were you born?"
       },
       enableCaptcha: true
   ]
}

Return values definition

Field	Description
userRefId	Auto generated from system per user.
userSecurityQuestionsList	Array of objects represent questions.
userSecurityQuestionsList.id	Question ID
userSecurityQuestionsList.question	Question to display the user.
enableCaptcha	True

Unlock Account

Unlock an account for a specific user upon answering security questions.

Parameters

None.

Payload
A JSON string representing the user’s answers.

Field	Description
userRefId	Fetch in the previous step
userSecurityQuestionsList	An array of the user’s questions
userSecurityQuestionsList.id	Question ID
userSecurityQuestionsList.question	Question
userSecurityQuestionsList.answer	Answer

Returns
JSON representing unlock action response.

Sample JSON return value for /ps/unlock

{
   “actionMessage” : Unlock user account succeeded! \\n Please use your current password to login
}

Return values definition

Field	Description
actionMessage	Success message to the user

Reset password

Reset a user's password upon answering security questions.

Parameters

None.

Payload
A JSON string representing the user’s answers.

Field	Description
userRefId	Fetch in the previous step
userSecurityQuestionsList	An array of the user’s questions
userSecurityQuestionsList.id	Question ID
userSecurityQuestionsList.question	Question
userSecurityQuestionsList.answer	Answer

Returns
JSON representing the reset action response.

Sample JSON return value for /ps/reset/ with reset method = “email”

{
   "actionMessage": "Reset user password succeeded!\\nWithin the next few moments, you will receive an email with your new temporary password.\\nThis password is only valid for 20 minutes, so please log in with it immediately.\\nUpon login, you will be asked to choose a new, permanent password.",
   "settings": {
       "temporaryPasswordValidity": 20,
       "resetPasswordMethod": "email"
   }
}

Return values definition

Field	Description
actionMessage	Success Message to the user
settings	Password services settings object
settings.temporaryPasswordValidity	Password expiration in minutes
settings.resetPasswordMethod	Reset password method(email/sms/user)

Sample JSON return value for /ps/reset with reset method = “user”

{
   "policy": {
       "complexity": true,
       "minLength": 7,
       "historyLength": 24
   },
   "token": "9f5641643c7f49b9920823ba18381a05"
}

Return values definition

Field	Description
policy	Password Services policy
policy.complexity	True - if the policy enforce password complexity
policy.minLength	Password minimum length
policy.historyLength	Password history
token	One time token

Update Password

Manually update a user's password upon verifying the user's token

Parameters

None.

Payload
A JSON string representing update password request object.

Field	Description
userRefId	Fetch in the previous step
newPassword	New password for the user
token	Fetch from the previous step

Returns
JSON representing the Update Password action response.

Sample JSON return value for /ps/reset/update

{
actionMessage: "Reset user password succeeded!"
}

Return values definition

Field	Description
actionMessage	Success Message to the user.

Non-Resource scenarios

API calls that send a response that's not necessarily a resource.

Download File

Download a file from the server. For example: download a user’s photo.

Parameters

Field	Description
file	The URL of the file

Returns
TBD

Sample JSON return value for /users/1?view=Mobile

Return values definition

Field	Description
field
id
name
info

Translate Key

Translate a key for display in the specified language.

Parameters

Field	Description
key	The key of the String, as defined in the sysaid resources file
language	The required language

Returns
The translated string.

Sample JSON return value for a file

{
   “key”:”welcome”,
   “value”:”Bienvenue”
}

Return values definition

Field	Description
key	The requested key for translation
value	The translated string

What's Next

SysAid Copilot REST API Guide

Table of contents

Login
Users
Filters
Service Requests
Action Items
Assets
Lists
Add-ons
CIs
Resource Bundle
Password Services
Non-Resource scenarios

SysAid REST API Details

Login

Parameters

Users

Get Users List

Parameters

Get User

Parameters

Search Users

Parameters

Upload user's photo

Payload:

Get User Permissions

Parameters

Get a User's Permission

Parameters

Filters

Get Filters List

Parameters

Get Filter

Parameters

Service Requests

Get Service Request List

Parameters

Get Service Request Form

Parameters

Search Service Request

Update Service Request

Parameters

Count Service Request

Parameters

Close Service Request

Parameters

Get Service Request Template

Parameters

Create Service Request

Parameters

Delete Service Request

Parameters

Add Service Request Link

Parameters

Delete Service Request Link

Parameters

Add Service Request Attachment

Parameters

Delete Service Request Attachment

Parameters

Add Service Request Activity

Parameters

Delete Service Request Activity

Parameters

Send Message From Service Request

Parameters

Action Items

Get action items

Parameters

Count Action Items

Parameters

Approve Action Items

Parameters

Reject Action Items

Parameters

Complete Action Items

Parameters

Reopen Action Items

Parameters

Assets

Get Assets List

Parameters

Get Asset

Parameters

Search Asset

Parameters

Lists

Get All Lists

Parameters

Get List

Parameters

Add-ons

List application add-ons