Newer
Older
Tickets
=======
The API supports ticket creation via the HTTP API (as well as via email,
etc.). Currently, the API support creation of tickets only -- so no
modifications and deletions of existing tickets is possible via the API for
now.
Create a Ticket
---------------
Tickets can be created in the osTicket system by sending an HTTP POST to
`api/tickets.xml`, `api/tickets.email` or `api/tickets.json` depending on the format of the
### Fields ######
* __email__: *required* Email address of the submitter
* __name__: *required* Name of the submitter
* __subject__: *required* Subject of the ticket
* __message__: *required* Initial message for the ticket thread
* __alert__: If unset, disable alerts to staff. Default is `true`
* __autorespond__: If unset, disable autoresponses. Default is `true`
* __ip__: IP address of the submitter
* __phone__: Phone number of the submitter
* __phone_ext__: Phone number extension -- can also be embedded in *phone*
* __priorityId__: Priority *id* for the new ticket to assume
* __source__: Source of the ticket, default is `API`
* __topicId__: Help topic *id* associated with the ticket
* __attachments__: An array of files to attach to the initial message.
Each attachment must have some content and also the
following fields:
* __name__: *required* name of the file to be attached. Multiple files
with the same name are allowable
* __type__: Mime type of the file. Default is `text/plain`
* __encoding__: Set to `base64` if content is base64 encoded
### XML Payload Example ######
* `POST /api/tickets.xml`
The XML data format is extremely lax. Content can be either sent as an
attribute or a named element if it has no sub-content.
In the example below, the simple element could also be replaced as
attributes on the root `<ticket>` element; however, if a `CDATA` element is
necessary to hold special content, or difficult content such as double
quotes is to be embedded, simple sub-elements are also supported.
Notice that the phone extension can be sent as the `@ext` attribute of the
`phone` sub-element.
``` xml
<?xml version="1.0" encoding="UTF-8"?>
<ticket alert="true" autorespond="true" source="API">
<name>Angry User</name>
<email>api@osticket.com</email>
<subject>Testing API</subject>
<phone ext="123">318-555-8634</phone>
<message><![CDATA[Message content here]]></message>
<attachments>
<file name="file.txt" type="text/plain"><![CDATA[
File content is here and is automatically trimmed
]]></file>
<file name="image.gif" type="image/gif" encoding="base64">
R0lGODdhMAAwAPAAAAAAAP///ywAAAAAMAAwAAAC8IyPqcvt3wCcDkiLc7C0qwy
GHhSWpjQu5yqmCYsapyuvUUlvONmOZtfzgFzByTB10QgxOR0TqBQejhRNzOfkVJ
+5YiUqrXF5Y5lKh/DeuNcP5yLWGsEbtLiOSpa/TPg7JpJHxyendzWTBfX0cxOnK
PjgBzi4diinWGdkF8kjdfnycQZXZeYGejmJlZeGl9i2icVqaNVailT6F5iJ90m6
mvuTS4OK05M0vDk0Q4XUtwvKOzrcd3iq9uisF81M1OIcR7lEewwcLp7tuNNkM3u
Nna3F2JQFo97Vriy/Xl4/f1cf5VWzXyym7PHhhx4dbgYKAAA7
</file>
</attachments>
<ip>123.211.233.122</ip>
</ticket>
```
### JSON Payload Example ###
* `POST /api/tickets.json`
Attachment data for the JSON content uses the [RFC 2397][] data URL format.
As described above, the content-type and base64 encoding hints are optional.
Furthermore, a character set can be optionally declared for each attachment
and will be automatically converted to UTF-8 for database storage.
Notice that the phone number extension can be embedded in the `phone` value
denoted with a capital `X`
Do also note that the JSON format forbids a comma after the last element in
an object or array definition, and newlines are not allowed inside strings.
``` json
{
"alert": true,
"autorespond": true,
"source": "API",
"name": "Angry User",
"email": "api@osticket.com",
"phone": "3185558634X123",
"subject": "Testing API",
"ip": "123.211.233.122",
"message": "MESSAGE HERE",
"attachments": [
{"file.txt": "data:text/plain;charset=utf-8,content"},
{"image.png": "data:image/png;base64,R0lGODdhMAA..."},
]
}
```
[rfc 2397]: http://www.ietf.org/rfc/rfc2397.txt "Data URLs"
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
### Email Payload Example ######
* `POST /api/tickets.email`
osTicket supports both remote (over http) and local piping. Please refer to the wiki on step-by-step instruction of setting up email piping.
```email
MIME-Version: 1.0
Received: by 10.194.9.167 with HTTP; Thu, 7 Feb 2013 09:01:04 -0800 (PST)
Date: Thu, 7 Feb 2013 11:01:04 -0600
Delivered-To: support@osticket.com
Message-ID: <CAL4KyrgKmpYxdX+6u3HyHZ3qN5K0mU2_sdfoVu6rT8cUNn+52w@osticket.com>
Subject: Testing
From: Peter Rotich <peter@osticket.com>
To: support@osticket.com
Content-Type: multipart/mixed; boundary=047d7bfcfaf263782204d52563a5
--047d7bfcfaf263782204d52563a5
Content-Type: multipart/alternative; boundary=047d7bfcfaf263781204d52563a3
--047d7bfcfaf263781204d52563a3
Content-Type: text/plain; charset=ISO-8859-1
Testing testing.
--
Peter Rotich
http://www.osticket.com
--047d7bfcfaf263781204d52563a3
Content-Type: text/html; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
<div dir=3D"ltr">Testing testing.<br clear=3D"all"><div><br></div>-- <br>Pe=
ter Rotich<br>
<a href=3D"http://www.osticket.com" target=3D"_blank">http://www.osticket.=
com</a>
</div>
--047d7bfcfaf263781204d52563a3--
--047d7bfcfaf263782204d52563a5
Content-Type: text/plain; charset=US-ASCII; name="file.txt"
Content-Disposition: attachment; filename="file.txt"
Content-Transfer-Encoding: base64
X-Attachment-Id: f_hcw5kqf60
Sm9lIGRhZGR5cyBjb250ZW50Cg==
--047d7bfcfaf263782204d52563a5--
```
Local piping can utilize `api/pipe.php` without the neeed to setup an API key.
### Response ######
If successful, the server will send `HTTP/201 Created`. Otherwise, it will
send an appropriate HTTP status with the content being the error
description. Most likely offenders are
* Required field not included
* Data type mismatch (text send for numeric field)
* Incorrectly encoded base64 data
* Unsupported field sent
* Incorrectly formatted content (bad JSON or XML)
Upon success, the content of the response will be the external ticket id of
the newly-created ticket.
Status: 201 Created
123456