API - Add Ticket (XML)
Overview
Enables ticket to be opened from remote website or application. Please read the information below carefully.
XML Wrapper Structure
Your xml wrapper structure should look like the following:
<?xml version="1.0" encoding="utf-8"?>
<msapi>
<api>YOUR KEY</api>
<op>ticket</op>
<tickets>
(ticket tags as shown below)
</tickets>
</msapi>
Op type is "ticket" and must NOT be changed. API key must be same as key in settings.
<?xml version="1.0" encoding="utf-8"?>
<msapi>
<api>YOUR KEY</api>
<op>ticket</op>
<tickets>
(ticket tags as shown below)
</tickets>
</msapi>
Op type is "ticket" and must NOT be changed. API key must be same as key in settings.
Ticket Data (Required)
Multiple tickets are possible with each transmission. Each ticket should be wrapper in <ticket></ticket> tags. Inside each tag set is the data related to the ticket. Custom field
data and attachments are supported, but are optional. Structure as follows:
<ticket>
<name>Persons Name</name>
<email>Persons Email</email>
<dept>Dept ID number</dept>
<subject><![CDATA[Subject of ticket]]></subject> (Uses CDATA example)
<comments>Comments</comments>
<language>english</language>
<priority>ID as shown on priority level page and in screenshot below</priority>
<status>ID as shown on ticket statuses page and in screenshot below</status>
<customfields>
(custom field tags as shown below)
</customfields>
<attachments>
(attachments tags as shown below)
</attachments>
</ticket>
Priority level must be ID as shown on priority levels page in your settings. If invalid or blank, defaults to 'low'. This may be a text value OR a numeric ID as shown in the following screenshot:
Ticket status must be ID as shown on ticket statuses page in your settings. If invalid or blank, defaults to 'open'. This may be a text value OR a numeric ID as shown in the following screenshot:
Language is an optional tag and is only required if you are using the multi language option. If an account exists already, the language will be taken from the account and the xml value will have no meaning. It's for new accounts only and sets their default language. No language specified will default to the main language in the settings.
For comments, if you are using the WYSIWYG editor option, you should send comments with line breaks / links etc.
<ticket>
<name>Persons Name</name>
<email>Persons Email</email>
<dept>Dept ID number</dept>
<subject><![CDATA[Subject of ticket]]></subject> (Uses CDATA example)
<comments>Comments</comments>
<language>english</language>
<priority>ID as shown on priority level page and in screenshot below</priority>
<status>ID as shown on ticket statuses page and in screenshot below</status>
<customfields>
(custom field tags as shown below)
</customfields>
<attachments>
(attachments tags as shown below)
</attachments>
</ticket>
Priority level must be ID as shown on priority levels page in your settings. If invalid or blank, defaults to 'low'. This may be a text value OR a numeric ID as shown in the following screenshot:
Ticket status must be ID as shown on ticket statuses page in your settings. If invalid or blank, defaults to 'open'. This may be a text value OR a numeric ID as shown in the following screenshot:
Language is an optional tag and is only required if you are using the multi language option. If an account exists already, the language will be taken from the account and the xml value will have no meaning. It's for new accounts only and sets their default language. No language specified will default to the main language in the settings.
For comments, if you are using the WYSIWYG editor option, you should send comments with line breaks / links etc.
Custom Field Data (Optional)
Custom field data is also supported and is optional. Structure as follows:
<f1>Custom field ID 1 data</f1>
<f2>Custom field ID 2 data</f2>
<f3>Custom field ID 3 data</f3>
<f4>Custom field ID 4 data</f4>
Each field tag contains the ID number of the field as shown in the main screenshot here prefixed with an 'f'. 'f1' for example would be custom field ID 1. If the ID doesn't exist in the system, the field tag will be ignored.
If the custom field value can be one of a number of specific options, the options you present to visitors in your application should mirror these.
<f1>Custom field ID 1 data</f1>
<f2>Custom field ID 2 data</f2>
<f3>Custom field ID 3 data</f3>
<f4>Custom field ID 4 data</f4>
Each field tag contains the ID number of the field as shown in the main screenshot here prefixed with an 'f'. 'f1' for example would be custom field ID 1. If the ID doesn't exist in the system, the field tag will be ignored.
If the custom field value can be one of a number of specific options, the options you present to visitors in your application should mirror these.
Attachments (Optional)
Multiple attachments are possible with each transmission. Attachment data must be base64 encoded:
<file>
<ext>File Extension</ext>
<data>Base64 Encoded File Data</data>
<name>File name (Optional)</name>
</file>
Each attachment should be wrapped in <file></file> tags and contain 2 additional tags, one for the file extension and one containing the base64 encoded data. A 3rd tag "name" can also be used if you want the attachment to save with a custom file name. Omitting this or leaving it blank will result in the file being saved with a random name. This should ONLY be used if you are sure your files have unique file names!!! File extension examples would be:
<ext>pdf</ext>
<ext>JPG</ext>
The extension is not case sensitive. Same restrictions apply with attachments as with standard tickets. If restrictions are met, attachments are ignored. If a file already exists, the system will auto rename the file to prevent accidental erasure of existing files.
<file>
<ext>File Extension</ext>
<data>Base64 Encoded File Data</data>
<name>File name (Optional)</name>
</file>
Each attachment should be wrapped in <file></file> tags and contain 2 additional tags, one for the file extension and one containing the base64 encoded data. A 3rd tag "name" can also be used if you want the attachment to save with a custom file name. Omitting this or leaving it blank will result in the file being saved with a random name. This should ONLY be used if you are sure your files have unique file names!!! File extension examples would be:
<ext>pdf</ext>
<ext>JPG</ext>
The extension is not case sensitive. Same restrictions apply with attachments as with standard tickets. If restrictions are met, attachments are ignored. If a file already exists, the system will auto rename the file to prevent accidental erasure of existing files.
XML Response
On successful transmission an xml response is returned:
<?xml version="1.0" encoding="utf-8"?>
<msapi>
<status>OK</status>
<ticketID>Database ID of ticket created. For additional custom ops if required</ticketID>
</msapi>
If an error occurs, the following is returned:
<?xml version="1.0" encoding="utf-8"?>
<msapi>
<status>ERROR</status>
<reason>Reason for error..</reason>
</msapi>
Your own application should deal with the response accordingly.
<?xml version="1.0" encoding="utf-8"?>
<msapi>
<status>OK</status>
<ticketID>Database ID of ticket created. For additional custom ops if required</ticketID>
</msapi>
If an error occurs, the following is returned:
<?xml version="1.0" encoding="utf-8"?>
<msapi>
<status>ERROR</status>
<reason>Reason for error..</reason>
</msapi>
Your own application should deal with the response accordingly.
Example File
Click here to view an example xml file.