About REST API
Application Programming Interface (API) is used to integrate various applications and facilitate sharing
of data between them. The integration can be achieved with any third party
(external) applications or web services that is capable of sending the
data via http protocol.
With API, ServiceDesk Plus operations can be accessed from other applications
or web services. In case of request operations, it provides a convenient
method to raise requests (other than the default e-mail or web form) directly
into ServiceDesk Plus without logging into the application. If required,
you can also have an option to create your own web form for using API.
The purpose of REST API can be explained with the help of a scenario.
Let's take the case of a network monitoring tool (external application)
that is installed in your network. In general, when an alarm is raised
by the network monitoring tool, an e-mail notification is sent as a ticket
to ServiceDesk Plus application. The field values (priority, level, impact,
category and so on) should be filled by the technician manually in ServiceDesk
Plus. This mechanism is time consuming and eventually results as a dip
in your helpdesk productivity chart.
With REST API, you can automate
this ticketing process. When an alarm is triggered, the network monitoring
tool provides the field details and raises a ticket automatically in ServiceDesk
Plus via http protocol. The ticket ID is sent back to the network monitoring
tool in order to perform any further operations over the request.
When the cause for the alarm is resolved, ServiceDesk Plus will invoke
an URL (callback URL) that was provided by the monitoring tool. The URL
functions as a notification to the external application indicating that
the ticket is resolved. If this URL (callback URL) is not provided, ServiceDesk
Plus will not perform any additional operation on the ticket. When ServiceDesk
Plus invokes the callback URL, the network monitoring tool can perform
"any" internal operations based on the URL invocation. However,
the expectation is that the application will clear the alarm (which was
raised as a ticket) at their end.
Note: Please note that the callback
URL is applicable only while creating and editing requests.
The operations performed
based on the 'operation' parameter and is sent to the url via
HTTP POST method. The url format is as shown below,
Authentication to the
ServiceDesk Plus application is key based i.e., an API key is sent along
with the url for every operation. This key is technician based and can
be generate for technicians with login privilege. The role given to the
technician is also taken into consideration, so the key is valid only
for the role given to the technician. Once the key is generated,
the key is manually transferred to the integrated application so that
the application can use the key for further API operations. If the key
is invalid (key is expired or the technician login is disabled), the operation
fails and an error is propagated to the integrated application.
1. Please note that the administrator alone has the privilege
to generate the authentication key for technicians with login permission.
2. If a login for the technician is disabled, then the technician key
3. The operations can be performed based on the Role provided to the
XML is the supported input and output format. The input data is sent as
an XML string along with the technician key and operation name, while
the output is exposed as an XML string.
Generating API Key
The authentication between ServiceDesk Plus and integrated application
is through an API key. A unique key is generated for a technician with
login permission in ServiceDesk Plus application.
-> Technicians icon under User
If you want to generate the API key to the existing
technician, click the edit icon
beside the technician.
If you want to generate the API key to a new technician, click Add New Technician link, enter the technician
details and provide login permission.
link under the API key details block. You can select a time frame
for the key to expire using the calendar icon or simply
retain the same key perpetually.
If a key is already generated for the technician, a Re-generate
The key in the above
image is generated for an existing technician. A time frame for the key
is selected which shows the date, month, year and the time (in hours and
minutes) when the key will expire.
REST API supported operations
The REST API supports the following operations which can be separated into:
request: adding new request, picking up requests, assigning requests, get requests, obtain conversations, add attachments, get request notifications, and add/edit/get resolutions.
a specific request:
editing, closing, deleting and viewing existing
adding new notes to a request, editing, deleting
and viewing existing notes.
adding worklog to a request, editing, deleting
and viewing existing worklogs.
obtain conversations related to request
add attachments to request
add, edit, and get resolution of a request.
pick up / assign request.
reply to request
get notifications related to request
Technician related operations: import technician profiles (of all technicians) and assign operations to them.
Requester related operations: import requester profiles (of all requesters) and work on their requests.
Admin related operations: import specific Category/ all Categories, specific Subcategory/ all Subcategories, specific Item/ all Items, specific Status/ all Status, specific Level/ all Level(s), specific Mode/ all Modes, specific Urgency (all Urgencies), specific Priority/ all Prirorities, specific Request Template/ all Request Templates, and all Support Group(s)
Servlet API is no longer supported. Find the docs related to the servlet API here