<p>Jutda Helpdesk provides a powerful <acronymtitle='Application Programming Interface'>API</acroynm> to allow you to interact with your helpdesk tickets by a means not otherwise provided by the helpdesk.</p>
<p>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.</p>
<p>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.</p>
<p>All requests to the API must be made using <acroynmtitle='HyperText Transfer Protocol'>HTTP</acronym> POST requests. Any request that is not made using POST will raise an error.</p>
<p>Your requests must be made up of the following elements:</p>
<ol>
<li>A <em>method</em>, or action. This tells the API what core functionality to execute.</li>
<li>A <em>username</em> and <em>password</em> which are valid and active within your helpdesk system. You may wish to create a specific API user just for API usage.</li>
<li>A set of <em>data</em> to be saved into the database. This data will vary from request to request, and is outlined in <ahref='#methods'>Methods</a> below.</li>
</ol>
<p>To build your request, send a HTTP POST request to <em>{% url helpdesk_api "method" %}</em>, where <em>method</em> is the name of a <ahref='#methods'>valid method</a> from the list below.</p>
<p>Your POST must include both <em>user</em> and <em>password</em> parameters.</p>
<p>A sample request for the method <em>hold_ticket</em> may look like this:</p>
<ul>
<li>A HTTP POST to <em>{% url helpdesk_api "hold_ticket" %}</em></li>
<li>A set of POST data containing:<ul>
<li>username=susan</li>
<li>password=fido</li>
<li>ticket=31794</li>
</ul></li>
</ul>
<p>To complete this from a command-line using the <ahref='http://curl.haxx.se/'>cURL</a> application, you may use a command such as this:</p>
<p>In <ahref='http://www.php.net/'>PHP</a>, providing you have access to the <ahref='http://www.php.net/curl'>cURL libraries</a>, you may use code such as this:</p>
<p>The following public methods are available for use via the API. Each of them requires <ahref='#request'>a valid request and authentication</a>, and each has it's own parameters as described below.</p>
<dd>Queue ID (use <ahref='#method_list_queues'>list_queues</a> to get queue ID's) - this is an integer field.</dd>
<dt>title</dt>
<dd>Title or header of this ticket. Character field, maximum 100 characters.</dd>
<dt>submitter_email</dt>
<dd>(Optional) e-mail address of the person submitting this ticket. This e-mail address will receive copies of all public updates to this ticket, and will receive a notification when the ticket is created.</dd>
<dt>assigned_to</dt>
<dd>(Optional) Integer ID of the user to which this ticket should be assigned. Use <ahref='#method_find_user'>find_user</a> to find a user ID from a username.</dd>
<dt>priority</dt>
<dd>(Optional) Priority as an integer from 1 (high) to 5 (low). Defaults to 3 if no priority given.</dd>
</dl>
<h4>Response</h4>
<p>This method responds with <strong>plain-text</strong>.</p>
<p>If you receive a 200 OK <ahref='#response'>response</a>, then the content of the response will be the ticket ID.</p>
<p>When given a ticket ID and confirmation, this method will delete a ticket entirely. This also deletes any followups, attachments, and other details.</p>
<h4>Parameters</h4>
<dl>
<dt>ticket</dt>
<dd>The numeric ticket ID to be deleted</dd>
<dt>confirm</dt>
<dd>You must provide this field, with any value, to enable deletion to continue</dd>
</dl>
<h4>Response</h4>
<p>A standard <ahref='#response'>200 OK response</a> is given on success, or an error message on failure.</p>
<p>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.</p>
<h4>Parameters</h4>
<dl>
<dt>ticket</dt>
<dd>The numeric ticket ID to which this followup should be added</dd>
<dt>message</dt>
<dd>Text of 'unlimited' length - optionally formatted with HTML - to add to the message.</dd>
<dt>public</dt>
<dd>Either 'y' for public, or 'n' for private. This is optional, and it is assumed that followups are private if it is not provided. Private tickets are <strong>not</strong> e-mailed to the ticket submitter.</dd>
</dl>
<h4>Response</h4>
<p>A standard <ahref='#response'>200 OK response</a> is given on success, or an error message on failure.</p>
<p>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.</p>
<h4>Parameters</h4>
<dl>
<dt>ticket</dt>
<dd>The numeric ticket ID to which this followup should be added</dd>
<dt>resolution</dt>
<dd>Text of 'unlimited' length - optionally formatted with HTML. This is the resolution for this ticket.</dd>
</dl>
<h4>Response</h4>
<p>A standard <ahref='#response'>200 OK response</a> is given on success, or an error message on failure.</p>
