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.

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.

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.

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:

  1. Only include devices with the agent installed

  2. 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”]}

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.

Did this answer your question?