---
title: "SysAid REST API Details"
slug: "rest-api-details"
description: "Parameters, return values definitions, payloads, etc. for SysAid REST API."
tags: ["On-prem", "SysAid Classic", "SysAid Spaces"]
updated: 2026-07-05T06:43:42Z
published: 2026-07-05T06:43:42Z
canonical: "documentation.sysaid.com/rest-api-details"
excludeFromExternalSearch: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.sysaid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SysAid REST API Details

> [!NOTE]
> 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
> 
> 🔗 [Go to SysAid Developers](https://developers.sysaid.com/)

## Login

#### 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 the 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

```plaintext
{
“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's unique ID |
| language | Returns the user’s default language, as defined in the !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 subsequent 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

```plaintext
[
    {
“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**

```plaintext
 {
  “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 a list of users in SysAid, according to a search criteria.

#### Parameters

| Field | Description |
| --- | --- |
| query | The search criteria (**Required**) |
| view | A SysAid view that 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**

```plaintext
 [
{ “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 |

Please 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

```plaintext
{
    “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's permission.

#### Parameters

None

**Returns** User’s permission for the requested permission ID.

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

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

**Return values definition**

| Field | Description |
| --- | --- |
| key | The requested permission ID |
| value | The permission value |

## Filters

### Get Filters List

Get a 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**

```plaintext
[
  {
“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 | 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. 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 that 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**

```plaintext
{
  “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 the 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 that 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**

```plaintext
[
{
 “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) that 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, whether it is editable, etc.

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

```plaintext
{
    “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.](/v1/docs/rest-api-guide#appendix-a-field-types) |

### Search Service Request

Returns a list of service requests (SR), that matched the search criteria. The 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 are specified, all SR fields are returned.

**Parameters**

| Field | Description |
| --- | --- |
| query | The search criteria. |
| view | A SysAid view (tab) that 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**

```plaintext
[
{
“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

```plaintext
{
“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**

```plaintext
{
"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 that 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**

```plaintext
{
  “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 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.](/v1/docs/rest-api-guide#appendix-a-field-types) |

### Create Service Request

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

#### Parameters

| Field | Description |
| --- | --- |
| view | A SysAid view that 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

```plaintext
{
  “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, whether it is editable, etc.

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

```plaintext
{
  “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.](/v1/docs/rest-api-guide#appendix-a-field-types) |

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 the 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

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

Please note:

If the list of To and/or CC users includes 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 items

Sample JSON return value

```plaintext
[{
“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 that defines the available fields. If **view** is 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

```plaintext
{
"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**

```plaintext
[
    {
“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**

```plaintext
{
“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 a 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

```plaintext
[
{
“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.](/v1/docs/rest-api-guide#appendix-b-lists) |
| fields | A comma-separated list of fields to return. Available fields to return are: id (always returned), caption, and values. |
| offset | The 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**

```plaintext
{
 { “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](/classic/docs/Guide_REST_API.htm#AppendixB). |
| 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 | The 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 the SR entity, send the SR_type ID, for the CI entity, send the CI_type ID ( e.g., for getting the list of CI subtypes). |
| 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**

```plaintext
{ “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 |

## CIs

### Create CI

Create a CI

#### Payload

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

| Field | Description |
| --- | --- |
| 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

```json
{
   "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 that 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 the **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**

```plaintext
[
{
 “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.](/v1/docs/rest-api-guide#appendix-a-field-types) |

### 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

```plaintext
{
  “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, it 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

```plaintext
[
    {
“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 the view name and the CI type ID will determine the fields that will be returned. |

**Returns** A list of fields with the requested view.

Please 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

```plaintext
[
   {
       "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](/classic/docs/Guide_REST_API.htm#AppendixA). |

### Get CI Relation Types

An API for retrieving CI relation type definitions.

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

Note

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

Sample JSON return value for ci/relationtypes

```plaintext
[
   {
    "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 with a given CI ID.

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

Sample JSON return value for /ci/9/relation

```plaintext
[
   {
      "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 with |
| ciRelationType | The CI Relationship Type ID that describes the Source CI’s association with 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 which the CI ID needs to be associated. |
| 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

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

Sample error message for a partially failed list

```plaintext
{
 "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 which the CI ID needs to be associated. |
| 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

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

## Resource Bundle

### Get RB Translated Keys

Get an array of translated keys according to the account location.

#### Parameters

None.

**Payload** A JSON string representing an array of Resource Bundle keys.

| Field | Description |
| --- | --- |
| key | Resource Bundle key |

Sample JSONinput /rb

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

**Returns** A list of translated keys.

Sample JSON return value for /rb

```plaintext
[
 {
     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 an 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 an array of Resource Bundle keys.

| Field | Description |
| --- | --- |
| key | Resource Bundle key |

Sample JSON input /rb

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

**Returns** A list of translated keys.

Sample JSONreturn value for /rb/{locale}

```plaintext
[
  {
    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 list of all Password Services permissions.

#### Parameters

None.

#### Payload

None.

**Returns** JSON representing Password Services permission.

Sample JSON return value for /ps/permission

```plaintext
{
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 the Security Questions object.

Sample JSON return value for /ps/reset/question

```plaintext
{
   "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 the system per user. |
| userSecurityQuestionsList | An array of objects represents 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

```plaintext
{
   “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”

```plaintext
{
   "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”

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

**Return values definition**

| Field | Description |
| --- | --- |
| policy | Password Services policy |
| policy.complexity | True - if the policy enforces 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 the 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

```plaintext
{
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 |

**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

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

**Return values definition**

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

## Download Daily Database Backup

This endpoint returns a **direct download link** for the latest available daily database backup file. The link is valid for a limited time and will trigger the file download when accessed.

While it can be used manually, it’s primarily intended to support **automated workflows**. You can create a **scheduled script** that retrieves the latest backup each day and feeds it directly into your **BI or analytics tools**, enabling richer, external reporting based on your SysAid data.

> [!NOTE]
> Please note:
> 
> - Only SysAdmin users are authorized to access this endpoint. Authentication is required prior to use. See the [Login section](/classic/docs/rest-api-details#login).
> - You must allow for backup delivery in your SysAid account. To do so, please contact your SysAid representative.

**Endpoint:**

```plaintext
GET /api/v1/dbbackup
```

**Exmaple URL:**

```plaintext
https://<your_subdomain>.sysaidit.com/api/v1/dbbackup
```

**Response:**

The response returns a 200 OK with a JSON body that includes the download link to the latest database backup.

```json
{
  "downloadUrl": "https://csmp.sysaid.com/api/download_backups?account_id=yourcompany&uuid=some-id&token=your-token"
}
```

You can paste the *downloadUrl* in your browser to download the .zip backup file. The link will return “NO_DATA” if none exist in SysAid.