Jutda Helpdesk provides a powerful API to allow you to interact with your helpdesk tickets by a means not otherwise provided by the helpdesk.
For example, you may use this API to implement a system to automatically open a ticket when an invoice is raised in your invoicing system, or to automatically close a ticket from an instant messenger application.
Your use of this system is open-ended: most business cases should be addressible with a little bit of coding to allow you to interact nicely with your helpdesk.
All requests to the API must be made using
Your requests must be made up of the following elements:
To build your request, send a HTTP POST request to {% url helpdesk_api "method" %}, where method is the name of a valid method from the list below.
Your POST must include both user and password parameters.
A sample request for the method hold_ticket may look like this:
To complete this from a command-line using the cURL application, you may use a command such as this:
/usr/bin/curl {% url helpdesk_api "hold_ticket" %} --data "user=susan&password=fido&ticket=31794"
In PHP, providing you have access to the cURL libraries, you may use code such as this:
<?php
$api = curl_init();
curl_setopt($api, CURLOPT_URL, "{% url helpdesk_api "hold_ticket" %}");
curl_setopt($api, CURLOPT_POST, 1);
curl_setopt($api, CURLOPT_POSTFIELDS, "user=susan&password=fido&ticket=31794");
$result = curl_exec($api);
curl_close($api);
echo $result;
?>
Note that cURL expects all data to be urlencoded, this is left as an exercise for the reader.
The API system makes proper use of the following HTTP response codes:
Responses will have one of two content-types:
The following public methods are available for use via the API. Each of them requires a valid request and authentication, and each has it's own parameters as described below.
This method creates a new helpdesk ticket.
This method responds with plain-text.
If you receive a 200 OK response, then the content of the response will be the ticket ID.
When given a ticket ID and confirmation, this method will delete a ticket entirely. This also deletes any followups, attachments, and other details.
A standard 200 OK response is given on success, or an error message on failure.
If a ticket needs to be placed on hold, preventing it from being escalated, use this method.
A standard 200 OK response is given on success, or an error message on failure.
If a ticket is currently on hold and you wish to remove that hold, use this method.
A standard 200 OK response is given on success, or an error message on failure.
This method adds a comment / followup to a ticket. The followup can be public, in which case it is e-mailed to the submitter, or private. The followup will also be sent to others involved in the ticket: The owner and the queue notification / CC address.
A standard 200 OK response is given on success, or an error message on failure.
This method adds a resolution to a ticket and marks it as resolved. The resolution will be e-mailed to everybody involved with the ticket, including the submitter.
A standard 200 OK response is given on success, or an error message on failure.
This method provides a JSON-parsable list of queues, letting you access the individual queue ID in order to create tickets.
This method responds with json.
It provides a list of queues in JSON format. The fields provided are ID and Title.
When given a username, this method provides the related numeric user ID - commonly used when creating or reassigning tickets.
This method responds with plain-text.
If you receive a 200 OK response, then the content of the response will be the users ID.