SysAid REST API Guide
    • 12 Feb 2024
    • PDF

    SysAid REST API Guide

    • PDF

    Article summary

    The SysAid REST API was designed to help:

    • Display, store, and process help desk data in a way that is best for your organization
    • Interface SysAid with third party applications
    Versions Supported
    The REST API is supported by SysAid versions 15.4 and up


    This guide is for Web Developers/IT Professional programmers and assumes advanced understanding of computer protocols to best utilize the APIs to your organization's advantage. 

    This document assumes knowledge of how to program REST API calls using your programming language and selected technology in your System Environment setting.

    Request Limits

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

    • A maximum of two API login requests will be allowed within a five minute period
    • Up to 1,000 other API requests will be allowed within a five minute period

    If usage exceeds the framework, an HTTP 429 message appears, and you will be able to continue once that five-minute time period has passed.

    Definitions

    There are several definitions that you should be familiar with before you read the rest of this guide.

    SysAid Entity (Object) 

    A SysAid entity is anything in SysAid that has both a list page and a form page. Each SysAid entity is represented by a SysAid object. 

    The API gives you access to the following SysAid entities: service records, assets, CIs, and users.

    Endpoint

    When you use the API, the endpoint should be appended to your account URL as in the following example:

    https://www.johndoe.sysaid.com/api/v1/<api_url>

    Common Parameters

    The following parameters are available in all or most of the API calls.

    Offset

    If you are retrieving a list of items, you can use the Offset parameter to set where on the list you should begin. For example, if you are retrieving a list of service records and there are 500 that match your criteria, but you are not interested in the first 100, you can set the Offset to 101 so the API returns service records 101 and up.

    Limit
    The maximum number of items to retrieve. For example, if your API call retrieves 1000 assets, you can set the limit to 300 so that only the first 300 assets (beginning from the defined offset, if specified) are retrieved.

    View
    A SysAid view which defines the available fields. Such views can be selected and set for lists in SysAid. You can create or customize views from the SysAid admin web interface.

    Fields

    Define a ist of comma seperated values representing the field names you wan to retrieve. If this parameter is set together with the View parameter, the API call returns both View fields and the fields specified in this parameter.

    Info
    Additional information fields.

    JSON Samples

    Throughout this guide, sample JSON Input and Return values are displayed in a white box like the one below:

    Sample JSON input - set sr status, assigned to, due date and add a note

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

    Login

    This Login call is for non-OAuth users.

    Command NameCommandDescriptionMore Details
    Authenticate a user on the SysAid serverPOST/loginChecks that the user is an administrator and that they have permissions to access the mobile appMore Details
    Important

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

    For security reasons, each session expires after 24 hours.
    Please make sure to log in again before the session expires.

    Note
    For Cloud accounts:
    Subsequent API Calls for SysAid Cloud Accounts need to include:
    • An Additional Cookie named SERVERID
    • The Additional Cookie's value, which is returned from the Login response


    Users

    Command NameCommandDescriptionMore Details
    Get Users ListGET/users?view={view_name}&fields={field1,field2...}&type={type} &offset={offset}&limit={limit}Get list of users in SysAidMore Details
    Get UserGET/users/{id}?view={view_name}&fields={field1,field2...}Get information on the specified userMore Details
    Search UsersGET/users/search?query={query_string}&view={view_name}&fields={field1,field2...}&type={type} &offset={offset}&limit={limit} &sort={field1,field2...}&dir={dir}Get list of users in SysAid, according to a search criteriaMore Details
    Get User's PhotoGET /users/{id}/photoDownloads the specified user's photoMore Details
    Upload User's PhotoPOST/users/{id}/photouploads the specified user's photoMore Details
    Get User PermissionsGET/users/{id}/permissionGet user permissionsMore Details
    Get A User's PermissionGET/users/{id}/permission/{permissionId}Check a specific user permissionMore Details

    Filters

    Command NameCommandDescriptionMore Details
    Get Filters ListGET/filters?view={view_name}&fields={field1,field2..}&offset={offset}&limit={limit}Get list of available filters and their values.More Details
    Get FilterGET/filters/{id}?view={view_name}&offset={offset}&limit={limit}Returns the information and available values for the specified filterMore Details

    Service Requests

    Command NameCommand
    Description
    More Details
    Get Service Request ListGET/sr?view={view_name}&fields={field1,field2..}&ids={id1,id2..}&type={type}&offset={offset}&limit={limit}&{filter1}={filter1_value}&{filter2}={filter2_value}..&sort={field}&dir={dir}...

    Returns a list of available service records (SR).

    Number of SRs to return can be controlled by offset, limit & type parameters.

    Returned SRs can be filtered by filters (See Filter Service).

    Each service record, Includes the fields according to view & fields parameters. If none specified, all SR fields are returned.

    More Details
    Get Service RequestGET/sr/{id}?view={view_name}&fields={field1,field2...}Returns the information for the specified service record.More Details
    Search Service RequestsGET/sr/search?query={search_criteria}&view={view_name}&fields={field1,field2..}&type={type}&offset={offset}&limit={limit}&{filter1}={filter1_value}&{filter2}={filter2_value}..&sort={field}&dir={dir}...Returns a list of service records (SRs), that matched the search criteria.More Details
    Update Service RequestPUT/sr/{id}Update a service recordMore Details
    Count Service RequestsGET/sr/count?{filter1}={filter1_value}&{filter2}={filter2_value}..Returns the number of SR’s that are compatible with the provided filters.More Details
    Close Service RequestPUT/sr/{id}/closeClose a service record. Sets the service record status to the default close status, as defined in the Help Desk settings.More Details
    Get Service Request TemplateGET/sr/template?view={view_name}&fields={field1,field2..}&type={sr_type}&template={template_id}Get a new service record templateMore Details
    Create Service RequestPOST/sr?view={view_name}&type={sr_type}&template={template_id}Create a new service record and returns the newly created service record.More Details
    Delete Service RequestDELETE/sr?ids={id1,id2….}Delete one or more service recordsMore Details
    Service Record Links
    Add Service Request LinkPOST /sr/{id}/linkAdd a link to service recordMore Details
    Delete Service Request LinkDELETE /sr/{id}/linkDelete a link from service recordMore Details
    Service Record Attachments
    Add Service Request AttachmentPOST /sr/{id}/attachmentAdd an attachment to service recordMore Details
    Delete Service Request AttachmentDELETE /sr/{id}/attachmentDelete an attachment from service recordMore Details
    Service Record Activities
    Add Service Request ActivityPOST /sr/{id}/activityAdd an activity to service recordMore Details
    Delete Service Request ActivityDELETE /sr/{id}/activityDelete an activity from service recordMore Details
    Service Record Messages
    Send Message From Service RequestPOST /sr/{id}/message?method={method}Send a message from a service recordMore Details

    Action Item

    Command NameCommandDescriptionMore Details
    Get Action ItemsGET/action_item?view={view_name}&fields={field1,field2..}&type={type}&archive={archive}&ids={id1,id2..}&
    staticFilterId={filter_id}&{filter1}={filter1_value}&{filter2}={filter2_value}..&
    query={search_criteria}&offset={offset}&limit={limit}&sort={field}&dir={dir}...
    Get list of action items in SysAidMore Details
    Count Action ItemsGET/action_item/count?view={view_name}&fields={field1,field2..}&type={type}&
    archive={archive}&ids={id1,id2..}&staticFilterId={filter_id}&{filter1}={filter1_value}&{filter2}={filter2_value}..&
    query={search_criteria}
    Count action itemsMore Details
    Approve Action ItemsPUT/action_item/{id}/approveApprove an action itemsMore Details
    Reject Action ItemsPUT/action_item/{id}/rejectReject action itemsMore Details
    Complete Action ItemsPUT/action_item/{id}/completeComplete action itemsMore Details
    Reopen Action ItemsPUT/action_item/{id}/reopenReopen action itemsMore Details

    Assets

    Command NameCommandDescriptionMore Details
    Get Assets ListGET/asset?view={view_name}&fields={field1,field2...}&type={type} &offset={offset}&limit={limit}Get list of assets in SysAidMore Details
    Get AssetGET/asset/{id}?view={view_name}&fields={field1,field2...}Get information on the specified assetMore Details
    Search AssetGET/asset/search?query={search_criteria}&view={view_name}&fields={field1,field2...}&offset={offset}&limit={limit}Get list of assets in SysAid, that matched the search criteriaMore Details

    Lists

    Command NameCommandDescriptionMore Details
    Get All ListsGET/list?entity={entity}&fields={field1,fields2..}&offset={offset}&limit={limit}Get all available lists and their values.More Details
    Get ListGET/list/{id}?entity={entity}&entityId={entity_id}&entityType={entityType}&fields={field1,fields2..}&offset={offset}&limit={limit}&key={keyField}Returns the values of the specified list. Values may be filtered according to the entity (sr, asset etc) for which you populate the list values.More Details

    Add-Ons

    Command NameCommandDescriptionMore Details
    List Add-On ApplicationGET/addonsGet a list of all available add-ons.More Details
    Get Add-On ParametersGET/addons/{addon name}Returns the full information about an add-on with all of its parameters.More Details
    UpdateAdd-On ParametersPUT/addon/{addon name}Update an add-on's parameters.More Details
    Test Add-On ConnectionPUT/addon/{addon name}/testConnectionTest an add-on's parameters.More Details
    Refresh Add-On ListGET/addons/refreshImmediately refresh the list of add-ons.More Details

    CIs

    Command NameCommandDescriptionMore Details
    Get CI List/FormGET/ci?view={view_name}&fields={field1,field2..}&ids={id1,id2..}&offset={offset}&limit={limit}&{filter1}={filter1_value}&{filter2}={filter2_value}..&sort={field}&dir={dir}supportBarcode={true/false}...

    Returns a list of CIs that can be filtered by the available filters.

    The Number of CIs to return can be controlled by the Offset and Limit parameters.
    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.

    More Details
    Update CIPUT/ci/{id}Update a CIMore Details
    Get CI TypesGET/ci/type?supportBarcode={true/false}

    Returns the available CI types.

    If the barcode flag is requested, returns only CI types with barcode support (if add-on is available).
    More Details
    Get CI ViewGET/ci/view/{ciTypeId}?view={view_name}Returns the fields contained in the specified view.More Details
    Get CI Relation TypesGET /ci/relationtypesReturns all the valid CI relation types defined in SysAid database and their ID numbers.More Details
    Get CI Relation GET /ci/relationAn API to retrieve all the destination CIs and their relation types, which are associated to a given Ci Id.More Details
    Create CI RecordsPOST/ciCreate a CI
    Create CI RelationsPOST /ci/{ciId}/relationAPI for creating one or more relations for a given CI ID.More Details
    Delete CI RelationsDELETE /ci/{ciId}/relation

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

    More Details

    Resource Bundle (RB)

    Command NameCommandDescriptionMore Details
    Get RB Translated KeysPOST /rbGet array of translated keys according to the account location.More Details
    Get RB Translated Keys With Given LocationPOST /rb/{locale}Get array of translated keys according to the given location.More Details

    Password Services

    Command NameCommandDescriptionMore Details
    Get LDAP Domains

    GET /ps/domain

    Get LDAP domains.More Details
    Get Password Services PermissionGET /ps/permissionGet Password Services permissions.More Details
    Get Security QuestionPOST ps/{method}/question

    Get Security Questions for given user.

    The method @pathparam can be: unlock/reset.
    More Details
    Unlock AccountPOST ps/unlock/Unlock user on verifying his answers.More Details
    Reset PasswordPOST ps/reset/Reset user’s password on verifying his answers.More Details
    Update PasswordPOST ps/reset/updateUpdate user’s password manual on verifying his token.More Details

    Appendix A: Field Types

       

    Field TypeDescription
    text

    A textual value

    numericA numeric value
    booleanBoolean value - can be either 0/1, or true/false
    dateA date value. Returned as milliseconds in UTC/GMT (since January 1, 1970). The valueCaption is the formatted date representation, according to date display configuration in SysAid.
    listA list of values. The full list of values can be retrieved using the /list/{id} api call.
    nestedThe value is an item in a nested list. Currently used for category levels.
    objectThe value is an object with sub values.
    customTBD...

    Appendix B: Lists

    The available lists are fetched by entity types.
    For example, if you want to retreive all available lists in the Service Record form, you can send the following API call:
    /list?entity=sr

    The available lists are:

    List TypeDescription
    srService record related lists
    assetAsset related lists
    userUser related lists
    ciCI related lists
    companyCompany related lists
    action_itemAction item related lists
    projectService record Sub Tabs lists
    taskTask related lists
    catalogCatalog related lists
    softwareSoftware related lists
    sr_activityService Record activity related lists
    supplierSupplier related lists
    task_activityTask activity related lists
    user_groupsUser Group related lists