Want to develop an interface with the Naverisk system?

This reference guide is intended for developers creating an interface with the Naverisk system. This is a technical document showing how to use the Naverisk API. The API uses SOAP and this document provides the information required to make the SOAP requests and process the responses correctly. This document also includes examples of each call, demonstrating how to add the request to a tool called Postman.

In your code, it is recommended to use Json.NET from Json.NET - Newtonsoft which is a free third-party dll to convert the response to an object which you can then use. The documentation can be found here:

http://james.newtonking.com/json/help/index.html?topic=html/T_Newtonsoft_Json_JsonConvert.htm#

If your requests are not working:

If you get the error “Unable to handle request without a valid action parameter. Please supply a valid soap action.” => The request parameters are case-sensitive. So for example, in the login request if you type in “login” instead of “Login” or “Username” instead of “username” then the request will not succeed. We realize that our web services are not consistently cased nor named so it is necessary to be careful when typing in the requests. All the requests in this document have been tested - so if it does not work then look carefully at how it is written here.

Ensure that you have a login username and password for a user that has sufficient rights.
Ensure that you do POST requests
Ensure that you have the correct Naverisk Website Address (which you use when you go to the Naverisk Website).
Ensure that you have added a Content-Type header of “text/xml; charset=utf-8”.
Ensure that you have a currently logged-on session guid
There is variation in the APIs as to whether tags that you do not want to provide a value for should be included in the request with no value or completely excluded from the request.

1.0 Postman

We recommend using Postman to test your API calls. We will use Postman throughout this guide to explain the API requests and their responses.

Postman can be downloaded here: Download Postman | Get Started for Free. The version we have worked on within this reference guide is 9.15.10. Postman may also be accessed via your web browser. In both cases, you need to create a free Postman account.

1.1 Postman Newman

You can also install Postman Newman - a command-line tool. It makes it easy to run your postman collections as part of some other process. eg your build system.

1.2 Postman Collection

Create a collection in Postman. You may call the collection whatever you like. Here we have called it Naverisk”. This collection will be used to hold all the API requests you create when you are testing the API. You do not have to do this, but it certainly helps when coding against the API so that you can understand precisely how to make an API request and also see the response that is returned.

1.3 Adding a Request to the Collection

In this guide, for each API, we will say “Add a request to your Postman collection and the use this xml.” This section explains how to do that. Note the Request URL is different for each Webservice.

The steps are:

Right click on your Postman collection and select “Add Request” from the menu.

Request name: Login

Request type: POST

Request Url: https://<NaveriskWebsiteAddress>/api/<WebServiceName>

Click on Headers tab and add the header:

Key: Content-Type
Value: text/xml; charset=utf-8

Click on Body tab and select raw: change raw type to XML

Enter in the request XML

1.4 Collection Variables

See the Postman documentation here: Using variables | Postman Learning Center.

What you can do is create a collection variable called session_guid. Then when you login you just need to update this variable. You can then use this variable in all of your requests. ie {{session_guid}}

2.0 Authentication Webservice

The Authentication Webservice URL is https://<NaveriskWebsiteAddress>/api/AuthenticationService.asmx.

2.1 Login

This request logs in a user bypassing the username and the password. This request will return a Session Guid used to identify all further requests to the API.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this XML.

Click Send button

If all goes well then you will see a response of “Status: 200 OK”. Click on the Body tab to see the response. Here is what the above looks like in Postman:

The response data includes the Session Guid which will be used for other requests. There is also the UserID and the ClientID.

2.2 Logoff

This request logs off the user and so discards the Session Guid.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml.

Click Send button

If all goes well then you will see a response of “Status: 200 OK”. Click on the Body tab to see the response. Here is what the above looks like in Postman:

3.0 Client Webservice

The Client Webservice URL is https://<NaveriskWebsiteAddress>/api/ClientService.asmx

3.1 Get Client List

This request returns a list of clients which the user you have authenticated as is allowed to see.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml.

Click Send button

Sample Response:

{"Keys": [“2”, “3”],

"Values":[“ClientName2”, “ClientName3”]}

3.2 Get Detailed Client List

This request returns a list of clients with detailed client data which the user you have authenticated as is allowed to see.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml.

Click Send button

Sample Response:

{“List”: [

{"LicenseType":"Standard", "CombinedID":"1", "ClientTypeID":1, "ParentID":"", "Name":"ClientName"}, {"LicenseType":"Standard", "CombinedID":"2", "ClientTypeID":2, "ParentID":"1", "Name":"ClientName2"}, {"LicenseType":"Standard", "CombinedID":"3", "ClientTypeID":2, "ParentID":"1", "Name":"ClientName3"}]}

3.3 Get Client Child List

This request returns a list of clients who are children (or sub clients) of the client.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml.

Click Send button

Sample Response:

{"Keys": [“2”, “3”],

"Values":[“ClientName2”, “ClientName3”]}

3.4 Get Parent and Client Child List

This request returns a list of clients who are children (or sub clients) of the client.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml.

<s:Envelope
	xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
	<s:Body>
		<GetParentAndChildClientsList
			xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
			xmlns="http://Iris.net">
			<clientID>1</clientID>
			<sessionGuid>{{session_guid}}</sessionGuid>
		</GetParentAndChildClientsList>
	</s:Body>
</s:Envelope>

Click Send button

Sample Response:

{"Keys": [““, “2”, “3”],

"Values":[““, “ClientName2”, “ClientName3”]}

3.5 Create Client

This request creates a client.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml.

<s:Envelope
	xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
	<s:Body>
		<CreateClient
			xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
			xmlns="http://Iris.net">
			<clientId>1</clientId>
			<name>Test Client</name>
			<industry></industry>
			<status>Good</status>
			<numberOfStaff>0</numberOfStaff>
			<address></address>
			<sessionGuid>{{session_guid}}</sessionGuid>
		</CreateClient>
	</s:Body>
</s:Envelope>

Click Send button

Will return “success” = true if the request successfully creates the client. Will also return the generated client id in the PrimaryIdentifier field.

Parameters:

Parameter	Details	Mandatory
clientId	The parent client id	Yes
name		Yes
industry		No
status	Client status Will default to “Medium” Options are “Good”, “Medium” and “Bad”	No
numberOfStaff		Yes
address		No

3.6 Modify Client

This request modifies a client.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml.

<s:Envelope
	xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
	<s:Body>
		<ModifyClient
			xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
			xmlns="http://Iris.net">
			<targetClientId>265</targetClientId>
			<name>Test Client Modified</name>
			<industry></industry>
			<status>Good</status>
			<numberOfStaff>5</numberOfStaff>
			<address></address>
			<sessionGuid>{{session_guid}}</sessionGuid>
		</ModifyClient>
	</s:Body>
</s:Envelope>

Click Send button

Will return “success” = true if the request successfully modifies the client.

Parameters:

Parameter	Details	Mandatory
tagetClientId	The client to modify	Yes
name		Yes
industry		No
status	Client status Will default to “Medium” Options are “Good”, “Medium” and “Bad”	No
numberOfStaff		Yes
address		No

3.7 Set Client Integration

This request sets the integration system for the client.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml.

Click Send button

Will return “success” = true if the request successfully sets the client system integration settings.

Parameters:

Parameter	Details	Mandatory
tagetClientId	The client to modify	Yes
name		Yes
industry		No
status	Client status Will default to “Medium” Options are “Good”, “Medium” and “Bad”	No
numberOfStaff		Yes
address		No

4.0 Device Webservice

The Device Webservice URL is https://<NaveriskWebsiteAddress>/api/DeviceService.asmx

4.1 Get Device List

This request returns a list of devices for the given client.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml.

Click Send button

Sample Response:

{"Keys": [“1000_1”, “1001_1”],

"Values":[“Device 1”, “Device 2”]}

4.2 Get Client Device List

This request returns the list of devices owned by the client with two filtering options:

Only include devices with the agent installed
Only include SNMP devices

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml.

Click Send button

Sample Response:

{"List” : [

{Device 1 properties},

{Device 2 properties}]}

4.3 Get Device Details

This request returns the details of the device.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml.

Click Send button

This one needs a lot of work on describing the response. It is not enough by any means to just regurgitate an example of what is returned. It needs to document what is returned so that it can be understood.

4.4 Change Device Maintenance Mode

This request sets the device in and out of maintenance mode.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml.

Click Send button

The response will include “Error” and “Success” values. “Success” will be true or false.

4.5 Get Agent Device List

This request returns the list of devices which have agents installed and the user is allowed to see.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml.

Click Send button

Sample Response:

{"Keys": [“1000_1”, “1001_1”],

"Values":[“Device 1”, “Device 2”]}

4.6 Installed Software By Device (Naverisk 2023 R1 onwards)

This request returns a list of devices, each with a list of software installed on them. The ‘deviceIds’ parameter can be one of the following:

a single Device to return the list of all installed software on the selected device,
a list of Devices separated by commas (eg “2,4,6”) to return the list of all installed software on all the selected devices,
blank to return the list of all installed software of the selected client and sub-clients devices.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml.

<s:Envelope
	xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
	<s:Body>
		<InstalledSoftwareByDevice
			xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
			xmlns="http://Iris.net">
			<clientId>1</clientId>
			<deviceIds></deviceIds>     
			<sessionGuid>{{session_guid}}</sessionGuid>
		</InstalledSoftwareByDevice>
	</s:Body>
</s:Envelope>

Click Send button

Sample Response:

{
    "retrieveDate": 1677465456969,
    "devices": [
        {
            "clientId": 1,
            "deviceId": 4,
            "operatingSystem": "Microsoft Windows 10 Pro 22H2",
            "installedSoftware": [
                {
                    "id": 1769,
                    "installIdentifier": "Notepad++.Notepad++",
                    "name": "Notepad++",
                    "version": "8.4.6",
                    "installDate": ""
                },
                {
                    "id": 1765,
                    "installIdentifier": "",
                    "name": "7-Zip 22.01 (x64 edition)",
                    "version": "22.01.00.0",
                    "installDate": 1667214000000
                }
            ]
        },
        {
            "clientId": 1,
            "deviceId": 5,
            "operatingSystem": "Microsoft Windows 10 Pro 22H2",
            "installedSoftware": [
                {
                    "id": 1769,
                    "installIdentifier": "Notepad++.Notepad++",
                    "name": "Notepad++",
                    "version": "8.4.6",
                    "installDate": ""
                },
                {
                    "id": 1765,
                    "installIdentifier": "",
                    "name": "7-Zip 22.01 (x64 edition)",
                    "version": "22.01.00.0",
                    "installDate": 1667214000000
                }
            ]
        }
    ]
]
}

Note that the dates in this sample are numbers - future revisions of this API will have differently formatted Dates.

5.0 Ticket Webservice

The Ticket Webservice URL is https://<NaveriskWebsiteAddress>/api/TicketService.asmx

5.1 Get Ticket List

This request returns a list of tickets, filtered by the parameters, which the user is allowed to see.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml (as an example).

OR (only including the mandatory parameters)

Click Send button

Parameters:

Parameter	Details	Mandatory
start	Start row number, starting at row 0	Yes
itemCount	Number of rows to return	Yes
sort	0 No sort, 1 Ascending, 2 Descending	Yes
sortColumn	201: Incident Identifier 202: Incident Source Id 204: SLA Class Id 205: Severity Id 206: Incident State Id 207: Subject 208: Description 210: Device Type Name 213: Duration 215: Client Name 217: Ticket Source Name 218: Ticket Priority Name 219: Ticket Job Type Name 220: Ticket Category Name 221: Ticket Status Name 222: Is Billable 223: Person Name 224: Status 225: Scheduled Type 226: Scheduled Date 227: Incident Type 228: Job Duration 229: Creation Date 230: Location 234: Ticket Description 235: Contacted Date 237: Due Date 238: Billing Status	Yes
consoleType	The types of SLA Classes: -1: None 0: All 1: Sales 2: Support 3: Monitor 4: Support And Monitor 5: Billing	Yes

5.2 Close Ticket List

This request closes the ticket. The user who you are logged on as is the one who actions the close. The notes are attached to the closed ticket.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml (as an example).

Click Send button

Note the eventIDList property is in fact the ticket Id list.

5.3 Create Sales Ticket

This request creates a sales ticket.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml (as an example).

Click Send button

Will return “success” = true if the request successfully creates the ticket. Will also return the generated ticket id in the PrimaryIdentifier field.

Parameters:

Parameter	Details	Mandatory
clientID		Yes
incidentCombinedID	A ticket that you want to relate this ticket to	No
slaStatusID	1: Warning 2: Threat 3: Failure 5: Information	Yes
description		Yes
from	Email address from	Yes
to	Email address to	Yes
emailSubject		Yes
emailBody		Yes
sendEmail	true \| false	Yes

5.4 Create Manual Ticket

This request creates a manual ticket.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml (as an example).

Click Send button

Will return “success” = true if the request successfully creates the ticket. Will also return the generated ticket id in the PrimaryIdentifier field.

Parameters:

Parameter	Details	Mandatory
clientID		Yes
incidentID	A ticket that you want to relate this ticket to. Can be set to 0.	Yes
deviceID	For example: 10_1 where 10 is the deviceID and 1 is the ClientID	Yes
slaClassID	1: Performance 2: Availability 4: Security 6: Backup 7: Support 8: Antivirus 10: Sales	Yes
slaStatusID	1: Warning 2: Threat 3: Failure 5: Information	Yes
trigger	Trigger text	Yes
description	Description text	Yes
userID	Ticket assigned user	No
personID	Ticket contact	Yes
ticketSourceID	For example 2_1 where 2 is the ticket source id and 1 is the client id	Yes
ticketPriorityID	For example 2_1 where 2 is the ticket priority id and 1 is the client id	Yes
ticketJobTypeID	For example 2_1 where 2 is the ticket job type id and 1 is the client id	Yes
ticketCategoryID	For example 2_1 where 2 is the ticket category id and 1 is the client id	No
ticketStatusID	For example 2_1 where 2 is the ticket job status id and 1 is the client id	Yes
ticketType	1: Incident 2: Problem 3: Service Call 4: Change 5: Other	Yes
TicketIncidentStateID	The ticket status: 1: Unassigned 2: Assigned 3: Closed 4: Archived	Yes
triggerType	0: None 1: Once 2: Daily 3: Weekly 4: Monthly	Yes
ticketDuration	Ticket duration in whole minutes	No
remindHrs	To be documented	No
sendCalendar	To be documented	No
triggerOnceDateTimeText triggerDailyRecursEveryText triggerDailyOccursTimeText triggerDailyStartDateText triggerDailyEndDateText triggerWeeklyRecursEveryText triggerWeeklyWeekday triggerWeeklyOccursTimeText triggerWeeklyStartDateText triggerWeeklyEndDateText triggerMonthlyRecursEveryDayText triggerMonthlyRecursEveryMonthText triggerMonthlyOccursTimeText triggerMonthlyStartDateText triggerMonthlyEndDateText TriggerMonthlyRepeatType TriggerMonthlyRepeatWeekdayNumber TriggerMonthlyRepeatWeekdayValue	To be documented

5.5 Create Manual Ticket for Devices

This request creates a manual ticket for each device in a device list

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml (as an example).

Click Send button

Parameters: See the Create Manual Ticket section. The only difference is that we have the property deviceIDList instead of deviceID.

5.6 Add Note to Ticket List

This request adds a note to a list of tickets.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml (as an example).

Click Send button

Parameters:

Parameter	Details	Mandatory
eventIDList	The list of tickets, For example 2_1,3_1 where 2 and 3 are ticket ids and 1 is the client id.	Yes
notes	The notes to add to each ticket	Yes

5.6 Add History Note to Ticket

This request adds time/expense notes to an existing ticket

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml (as an example).

Click Send button

Parameters:

Parameter	Details	Mandatory
incidentCombinedID	The ticket. For example 2_1 where 2 is the ticket id and 1 is the client id.	Yes
noteType		Yes
notes		Yes
isBillable	true or false	No
duration	24	No
startDateTime	yyy-mm-dd	Yes
agreementCombinedID	For example 2_1 where 2 is the agreement id and 1 is the client id.	No
costPerHour		Yes
technicianCombinedID		No
expenseCombinedID		No
expenseAmount		No

5.7 Get Ticket History

This request returns the Ticket History.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml (as an example).

Click Send button

Parameters:

Parameter	Details	Mandatory
incidentID	The ticket id	Yes
iClientId	The client id	Yes

5.8 Archive Ticket List

This request will archive the tickets in the list.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml (as an example).

Click Send button

Parameters:

Parameter	Details	Mandatory
eventIDList	the comma delimited list of ticket ids that are to be archived.	Yes
notes	The not to add to each ticket regarding it being archived.	Yes

5.9 Change Ticket Status List

This request will change the status of each of the tickets in the list. The user you are logged in as will be the one who actioned it.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml (as an example).

Click Send button

Parameters:

Parameter	Details	Mandatory
eventIDList	The comma delimited list of ticket ids that are to have their status changed. This web service requires a combined id for each ticket. eg 2_1 where 2 is the ticket id and 1 is the client id.	Yes
status	Options are: unassigned active assigned open closed archived autoClosed	Yes
notes	The not to add to each ticket regarding the status being changed.	Yes

6.0 Person Webservice

The Authentication Webservice URL is https://<NaveriskWebsiteAddress>/api/PersonService.asmx.

6.1 Create Contact

This request creates a Contact.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml.

6.2 Create Multiple Contacts

This request creates multiple contacts.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml.

Click Send button

Will return “success” = true if the request successfully creates the contacts.

Parameters:

Parameter	Details	Mandatory
clientId		Yes
SerilisedPersonList._additonalParameters	Set to ““. Ignored.	Yes
SerilisedPersonList.firstName		Yes
SerilisedPersonList.lastName		Yes
SerilisedPersonList.jobTitle		Yes
SerilisedPersonList.email		Yes
SerilisedPersonList.phone1	Saved to phone	Yes
SerilisedPersonList.phone2	Saved to mobile	Yes
SerilisedPersonList.fax		Yes
SerilisedPersonList.contactNumber	Set to ““. Ignored.	Yes
SerilisedPersonList.address	Set to ““. Ignored.	Yes
SerilisedPersonList.state	Set to ““. Ignored.	Yes
SerilisedPersonList.city	Set to ““. Ignored.	Yes
SerilisedPersonList.zip	Set to ““. Ignored.	Yes
SerilisedPersonList.contactMethod	Set to ““. Ignored.	Yes
SerilisedPersonList.contactType	Set to ““. Ignored.	Yes
SerilisedPersonList.emailType	Set to false. Ignored.	Yes
SerilisedPersonList.isARContact	Set to false. Ignored.	Yes
SerilisedPersonList.isDecisionMakerContact	Set to false. Ignored.	Yes
SerilisedPersonList.isEquipmentContact	Set to false. Ignored.	Yes
primaryContactName	Matches on firstName + “ “ + lastName and makes that contact the primary contact.	Yes

6.3 Modify Contact

This request modifies a Contact.

Add a request to your Postman collection (see 1.3 Adding a Request to the Collection) and use this xml.

Click Send button

Will return “success” = true if the request successfully finds and modifies the contact.

If you need further assistance with the API then please contact the support team.

7.0 JSON API Addendum (Naverisk 2023 R1 onwards)

This is a sample request for login using xml. This will return the usual response as above.

Note the addition of the method name at the end. All calls are POST requests and the json field names are case sensitive as are the API method names.

Also note the following:

Calls with array type structures may not be supported at this time.
Session GUID is part of the payload in all requests.
All parameters are compulsory in json requests, although empty string or default values are allowed.
APIs that contain a string of JSON will need to still take it in as JSON string and extra care must be taken to ensure all special characters are escaped accordingly.

https://qatest.naverisk.com/api/PersonService.asmx/CreateMultiplePerson
Content-Type: application/json; charset=utf-8
Accept: application/json

{
    "clientId": "3134",
    "SerilisedPersonList": "[{\"_additionalParameters\": \"\", \"firstName\":\"Joe\",\"lastName\":\"Smith\",\"jobTitle\":\"Developer\",\"email\":\"joe@smith.com\",\"phone1\":\"0220000000\",\"phone2\":\"0220000000\",\"fax\":\"0220000000\",\"contactNumber\":\"0220000000\", \"address\": \"\", \"state\": \"\", \"city\": \"\", \"zip\": \"\", \"contactMethod\": \"\", \"contactType\": \"\", \"emailType\": false, \"isARContact\": false, \"isDecisionMakerContact\": false, \"isEquipmentContact\": false}]",
    "primaryContactName": "Joe Smith",
    "sessionGuid": "72f55bb4-6a5e-4990-9320-6e30c92e9604"
}

7.1 Example difference in requests

This is a sample request for login using xml. This will return the usual response as above.

POST http://localhost/api/AuthenticationService.asmx
Content-Type: text/xml; charset=utf-8

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Body>
         <Login xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://Iris.net">
            <username>myuser</username>
            <password>mypassword</password>
         </Login>
    </s:Body>
</s:Envelope>

Next is the same request as JSON. Notice the extra/changed headers and the method name. The result will be a simple json object with the same contents as above minus the xml/html/js wrapping.

POST http://localhost/api/AuthenticationService.asmx/Login
Content-Type: application/json; charset=utf-8
Accept: application/json

{
    "username": "myuser",
    "password": "mypassword"
}