API guide for ServiceDesk Plus On-Demand

ManageEngine ServiceDesk Plus On-Demand provides an API (Application Programming Interface) using which you can integrate it with any of your existing applications such as network monitoring, intranet web applications and any other outside application. The ServiceDesk Plus On-Demand API supports XML and JSON formats and is programming language-neutral; allowing you to develop applications in a language you are familiar with.

With the ServiceDesk Plus On-Demand API, the possibilities are manifold and constrained just by the limits of our imagination. Here are some of the things you can do with our API

• Create / Edit / Delete requests from your own website, having your own user interface.
• Create / Edit requests from your monitoring application

Prerequisites for using your API

To use the ServiceDesk Plus On-Demand API you should have the following

• A valid ServiceDesk Plus On-Demand account username and password
  
• Get an Authtoken

Generating Authtoken

https://accounts.zoho.com/apiauthtoken/create?SCOPE=SDPOnDemand/sdpodapi
You will be requested to sign in if you are not signed in already.

Sample Response

#
#Tue Nov 30 13:08:11 PST 2010
AUTHTOKEN=a8b6de25b5bf481824c9c4173c56231a
RESULT=TRUE

Remarks :
AUTHTOKEN : The permanent authtoken generated for ServiceDesk Plus On-Demand API access.
RESULT : Value is TRUE if the authtoken is generated successfully.

Invoking the API

Any of our API methods can be invoked via HTTP POST request. All parameters in the request should be form-urlencoded. For all the APIs you need to pass authtoken, scope and operation name, which are mandatory.

Mandatory parameters to be passed for all APIs

There are certain parameters that are mandatory for all API requests of ServiceDesk Plus On-Demand. They are,

Supported formats

ServiceDesk Plus On-Demand supports both the XML and JSON formats.
The URL structure for an XML format API would be as below: https://sdpondemand.manageengine.com/api/request

The URL structure for a JSON format API would be as below: https://sdpondemand.manageengine.com/api/json/request

Formats for input and output

{
   "operation": {
      "Details": {
         "PARAMETER_NAME_1": 
               "PARAMETER_VALUE_1",         
         "PARAMETER_NAME_2": 
               "PARAMETER_VALUE_2",
      }
   }
}

For example, for adding a request, the following is a sample INPUT_DATA in json and xml formats :

{
   "operation": {
      "Details": {
         "URGENCY": "High",         
         "SUBJECT": "Subject of the request",
         "LEVEL": "Tier 1",         
      }
   }
}

Sample Output :
The following is a sample output in json & xml formats for the worklog addition api :

{
   "operation": {
      "name": "ADD_WORKLOG",
      "result": {
         "status": "Success",
         "message": 
             "WorkLog added successfully 
                for request"
      },
      "Details": {
         "WORKLOGID": "2000000124193"
      }
   }
}

Some general rules for input and output

1. Content type while calling the api must be application/x-www-form-urlencoded and all parameter values must be url encoded
   
2. In the output, “Details” will be a JSON object or a JSON array. For returning multiple objects, JSON array will be used. For example, GET_REQUEST will contain a JSON Object in the output, whereas, GET_REQUESTS will return a JSON array in the output. Similarly, there will be single or multiple "<Details>" elements in the output xml, depending on the operation.
3. The parameter names (inside "Details") in the INPUT_DATA are to be in UPPER case only. For e.g., you can specify "URGENCY":"High" or "PRIORITY" : "High" in the input data while adding a request.
   
4. In the output, all the parameter names (inside "Details") will be returned in upper case.
5. Date/Time field values will always be sent in Long. Input should also contain Long value for these fields