HappyFox API

Technical Reference

API Version 1.0

Document Version 0.1

© 2011, Tenmiles Corporation

 Copyright Information
Under the copyright laws, this manual may not be copied, in whole or in part. Your rights to
the software are governed by the HappyFox license agreement. The HappyFox logo is a
trademark of Tenmiles Technologies Pvt Ltd, registered in India. Every effort has been
made to ensure that the material in this manual is accurate.

Other company names mentioned in this manual are trademarks of their respective
companies. Mention of third-party products is for informational purposes only and
constitutes neither an endorsement nor recommendation. Tenmiles Technologies Pvt. Ltd.
assumes no responsibility with regard to the performance or use of these products.

Tenmiles Technologies Pvt Ltd, 1A, Jhaver plaza, Nungambakkam, Chennai 600007
 HappyFox API - Technical Reference
Table of Contents
1 Getting Started.................................................................................................................... 5
1.1 Introduction.................................................................................................................. 5
1.2 Requirements...............................................................................................................5
1.3 Documentation Conventions....................................................................................... 5
2 Protocols, Data Formats and Mechanisms.........................................................................6
2.1 API Version.................................................................................................................. 6
2.2 Resource URIs............................................................................................................ 6
2.2.1 Base URI.............................................................................................................. 6
2.3 Request Methods.........................................................................................................6
2.4 Authentication.............................................................................................................. 7
2.5 Throttling...................................................................................................................... 7
2.6 Request Content Types............................................................................................... 7
2.7 Response Content Types............................................................................................ 8
2.8 Data Types...................................................................................................................8
2.9 NULL Values................................................................................................................ 8
2.10 Paginated Lists for Collection Resources..................................................................9
2.10.1 URL Parameters................................................................................................. 9
2.10.2 Paginated List - Response Data Structure.........................................................9
2.10.3 Page Info - Inner Data Structure........................................................................ 9
2.11 Data Validation Errors.............................................................................................. 10
2.11.1 Field Errors - Response Data Structure........................................................... 10
3 Resources And Operations............................................................................................... 11
3.1 Ticket Category - Resource....................................................................................... 11
3.1.1 Operations.......................................................................................................... 11
3.1.1.1 Reading All Categories................................................................................11
3.1.1.2 Reading One Category................................................................................11
3.1.2 Data Structures...................................................................................................11
3.1.2.1 Ticket Category - Response Data Structure...............................................11
3.2 Ticket Status - Resource............................................................................................12
3.2.1 Operations.......................................................................................................... 12
3.2.1.1 Reading All Statuses................................................................................... 12
3.2.1.2 Reading One Status....................................................................................12
3.2.2 Data Structures...................................................................................................12
3.2.2.1 Ticket Status - Response Data Structure....................................................12
3.3 Ticket Priority - Resource...........................................................................................13
3.3.1 Operations.......................................................................................................... 13
3.3.1.1 Reading All Priorities................................................................................... 13
3.3.1.2 Reading One Priority...................................................................................13
3.3.2 Data Structures...................................................................................................13
3.3.2.1 Ticket Priority - Response Data Structure...................................................13
3.4 Staff - Resource......................................................................................................... 14
3.4.1 Operations.......................................................................................................... 14
3.4.1.1 Reading All Staff..........................................................................................14
3.4.1.2 Reading One Staff By ID.............................................................................14
3.4.1.3 Reading One Staff By Email....................................................................... 14
3.4.2 Data Structures...................................................................................................14
3.4.2.1 Staff - Response Data Structure................................................................. 14
3.5 User - Resource.........................................................................................................15
 3.5.1 Operations.......................................................................................................... 15
3.5.1.1 Reading All Users........................................................................................15
3.5.1.2 Reading One User By ID............................................................................ 15
3.5.1.3 Reading One User By Email....................................................................... 15
3.5.2 Data Structures...................................................................................................15
3.5.2.1 User - Response Data Structure.................................................................15
3.6 Ticket - Resource.......................................................................................................16
3.6.1 Operations.......................................................................................................... 16
3.6.1.1 Reading All Tickets......................................................................................16
3.6.1.2 Reading One Ticket.....................................................................................16
3.6.1.3 Create A Ticket............................................................................................ 16
3.6.1.4 Add A Staff Update...................................................................................... 16
3.6.1.5 Add A Staff Private Note..............................................................................17
3.6.1.6 Add A User Reply........................................................................................ 17
3.6.2 Data Structures...................................................................................................17
3.6.2.1 Ticket - Response Data Structure............................................................... 17
3.6.2.2 Ticket Update - Inner Data Structure.......................................................... 18
3.6.2.3 Ticket Update By - Inner Data Structure..................................................... 18
3.6.2.4 Ticket Message- Inner Data Structure........................................................ 19
3.6.2.5 Ticket Attachment - Inner Data Structure....................................................19
3.6.2.6 Ticket Status Change - Inner Data Structure.............................................. 19
3.6.2.7 Ticket Priority Change - Inner Data Structure............................................. 19
3.6.2.8 Ticket Assignee Change - Inner Data Structure..........................................20
3.6.2.9 Ticket Category Change - Inner Data Structure..........................................20
3.6.2.10 Ticket Due Date Change - Inner Data Structure....................................... 20
3.6.2.11 Create Ticket - Request Data Structure.................................................... 20
3.6.2.12 Create Ticket Using User Email & Name - Request Data Structure.........21
3.6.2.13 Add Staff Update - Request Data Structure..............................................21
3.6.2.14 Add Staff Private Note - Request Data Structure......................................22
3.6.2.15 Add User Reply - Request Data Structure................................................ 22
3.6.2.16 Attachments - File Upload Request.......................................................... 22
3.7 Custom Fields............................................................................................................ 24
3.7.1 Operations.......................................................................................................... 24
3.7.1.1 Reading All User Custom Fields................................................................. 24
3.7.1.2 Reading One User Custom Fields.............................................................. 24
3.7.1.3 Reading All Ticket Custom Fields............................................................... 24
3.7.1.4 Reading One Ticket Custom Field.............................................................. 24
3.7.2 Types.................................................................................................................. 24
3.7.2.1 Custom Field Types.................................................................................... 24
3.7.2.2 Custom Field Choice Types........................................................................ 25
3.7.3 Data Structures...................................................................................................25
3.7.3.1 User Custom Field – Response Data Structure..........................................25
3.7.3.2 Ticket Custom Field - Response Data Structure.........................................25
3.7.3.3 Ticket Custom Fields To Category - Inner Data Structure..........................26
3.7.3.4 Choice Item - Inner Data Structure............................................................. 26
3.7.3.5 Multiple Choice Item - Inner Data Structure................................................26
3.7.3.6 Custom Field Value - Inner Data Structure................................................. 27
3.7.4 Notes.................................................................................................................. 27
3.7.4.1 Common Information For Setting Ticket / User Custom Field Values........27
3.7.4.2 Ticket Custom Field Values For Create Ticket............................................27
3.7.4.3 User Custom Field Values For Create Ticket..............................................28
1 Getting Started

1.1 Introduction
The API provided by the Helpdesk is a RESTful web service. It supports operations like
creating a ticket, adding updates to a ticket, listing tickets and users of the Helpdesk, etc. It
supports JSON, YAML, XML, Form Urlencoded and Multipart Form Data formats.

1.2 Requirements
The API requires following skills in any programming language

1. Making HTTP requests (using GET and POST HTTP methods as a minimum
requirement).

2. Doing HTTP Basic Authentication.

3. Generating and reading data in any one of the formats - JSON, YAML or XML

4. Optionally making HTTP POST requests using content type of "multipart/form-data"

(needed for ticket attachments)

1.3 Documentation Conventions

1. The documentation indicates parameters that need to be replaced with actual
values using the format <parameter_name>. The entire string including the
enclosing < and > should be replaced.

For example: if the parameter is <email> it should be replaced with the required
email address
2 Protocols, Data Formats and Mechanisms
This section of the document describes the communication protocol, data formats and
application mechanisms used in the API.

2.1 API Version

The resources and operations provided by the API will change over time as new features
are added or existing features are modified. In order to maintain compatibility between the
API clients and server each version of the API has a designated a version string. This
string has to be specified as part of all the requests sent to the server. See Resource URIs
for details on how to send the version number.

2.2 Resource URIs

The URIs used by the API have a common base URI followed by the response data format
and finally followed by the resource or collection URI.

For Example, In http://<server>:<port>/api/<api_version>/<response_format>/tickets/

http://<server>:<port>/api/<api_version>/ is the Base URI

<response_format>/ is a response data format like json or yaml or xml

tickets/ is the Resource URI

2.2.1 Base URI

The base URI is composed of the following parts

1. HTTP or HTTPS protocol specifier

2. API server hostname

3. API server port number (optional – defaults to port 80)

4. API version string

2.3 Request Methods

The following HTTP methods are used to perform operations on resources provided by the
API.

NOTE: not all resources support all the listed operations, see the documentation of each
resource for the supported methods

HTTP Method Operation

 GET Retrieve a element or list of elements
POST Create a new element or a child entry in a element
PUT Update a element
DELETE Delete a element

2.4 Authentication
The API requires a "API Key" and "Auth Code" pair for access. Contact the Helpdesk
Admin for access details.

The server uses HTTP Basic Authentication with the "API Key" as username and "Auth
Code" as the password. The authentication realm is "API".

The API server returns HTTP response code 401 in case of authorization required or login
failure.

SECURITY NOTES:

1. Credentials are passed as plain-text in HTTP Basic Authentication, therefore it is

recommended to use SSL/TLS if the API is used over the Internet.

2. It is not recommended to invoke the API directly from browser using Javascript as
this would require the "API Key" and "Auth Code" to be present on the browser
side. Instead the API should be invoked from the web application server.

2.5 Throttling
The API server limits the number of requests that can be sent during a interval of time.
There are independent limits for read and write operations. Contact the Helpdesk Admin to
know the current limits and for changing them to meet requirements.

In case the request limits are exceeded the API server returns HTTP response code 503
along with the time to wait before retrying in the response body.

2.6 Request Content Types

The following data formats are supported by the API server when data is sent to it for
POST and PUT operations.

Any of the data formats can be used provided the correct Content-Type is set in the HTTP
request header.

NOTE: file uploads are only supported with Multipart Form Data.

Request Format Content-Type File Upload

 JSON application/json NO
YAML application/x-yaml NO
Form Urlencoded application/x-www-form-urlencoded NO
Multipart Form Data multipart/form-data YES

2.7 Response Content Types

The following data formats are supported for response data sent back by the API server.

The required data format is specified as the <response_format> mentioned under

Resource URIs

Response Format Specified in URI as Response Content-Type

JSON json application/json
YAML yaml application/x-yaml
XML xml application/xml

2.8 Data Types

These are the basic data types that are used in the API. Using these types more complex
data structures for the resources are built.

Type Description
String String type with Unicode support
Integer Signed 64 bit integral number
ID Special type of Integer with minimum value 1, Will be unique within
each resource type
Float Floating point number
Boolean True/False type
DateTime Combined date and time in the ISO 8601 extended format of YYYY-
MM-DD HH:MM:SS.ssssss
NOTES:
1) all DateTime values in the API are in UTC timezone
2) the decimal part represented by ssssss is optional
3) a space separator is used between the date and time values
Date Date in the ISO 8601 extended format of YYYY-MM-DD
NOTE: all Date values in the API are in UTC timezone

2.9 NULL Values

Some of the fields in a resource may be optional or currently absent . The values of these
fields are represented as a special NULL value. This value maps to corresponding
equivalents in the data formats as listed below

Response Format NULL Value Representation

 JSON null
YAML null
XML Element attribute null="True"

2.10 Paginated Lists for Collection Resources

Some of the collection resources provided by the API may return a large volume of
elements. In these cases the API imposes a upper limit on the number elements that can
be returned in a single collection read request.

By specifying a page size (lesser than or equal to the upper limit) and a corresponding
page number as URL parameters, the collection can be split the into a smaller number of
elements and progressively retrieved from the API server.

The response from the API server contains information about the page split and the actual
data as described below.

2.10.1 URL Parameters

Field Type Description
size Integer The number of items per page (limited to the
maximum defined for the particular collection
resource)
page Integer The number of the page required

2.10.2 Paginated List - Response Data Structure

This data structure contains information and data from the paginated list

Field Type Description

page_info Page Info Information about the pagination
data List of Elements The list of elements retrieved from the
collection

2.10.3 Page Info - Inner Data Structure

This inner data structure is used in the "page_info" field of a Paginated List

Field Type Description

count Integer Number of elements returned
start_index Integer The index of the first element in the returned
subset
end_index Integer The index of the last element in the returned
subset
last_index Integer The index of the last element in the entire
 collection
page_count Integer Number of pages for the given page size

2.11 Data Validation Errors

The API server performs validation on the data submitted via POST and PUT requests. In
case the data validation fails, the API server returns HTTP response code 400 along with
error information in the response body.

The error information response data is a List of Field Errors that contains information about
data validation errors in individual fields as well as any errors that apply to the entire
request (like errors that are not dependent on individual fields).

2.11.1 Field Errors - Response Data Structure

This data structure contains the field name and the list of errors messages for the field.

Field Type Description

field String The name of the field.
(For errors that pertain to the entire request
and not to a particular field, the field name will
be "__all__")
errors List of String One or more errors related to the field value
3 Resources And Operations
This section of the document describes the various REST element and collection
resources provided by the API and the operations that can be performed on them.

3.1 Ticket Category - Resource

A Ticket Category is a grouping of tickets based on a common attribute like ticket purpose,
product or service, support type or department

3.1.1 Operations

3.1.1.1 Reading All Categories

URL <base_uri>/<response_format>/categories/
HTTP Method GET
Response Data List of Ticket Category

3.1.1.2 Reading One Category

URL <base_uri>/<response_format>/category/<id>/
HTTP Method GET
Response Data Ticket Category

3.1.2 Data Structures

3.1.2.1 Ticket Category - Response Data Structure

This data structure contains information about a ticket category

Field Type Description

id ID Unique numerical identifier
name String Name of the category
description String Short description about the category
public Boolean If True, visible to users, else only visible to
staff
3.2 Ticket Status - Resource
A Ticket Status describes the current status of a ticket

3.2.1 Operations

3.2.1.1 Reading All Statuses

URL <base_uri>/<response_format>/statuses/
HTTP Method GET
Response Data List of Ticket Status

3.2.1.2 Reading One Status

URL <base_uri>/<response_format>/status/<id>/
HTTP Method GET
Response Data Ticket Status

3.2.2 Data Structures

3.2.2.1 Ticket Status - Response Data Structure

This data structure contains information about a ticket status

Field Type Description

id ID Unique numerical identifier
name String Name of the status
behavior String Either "pending" or "completed" to indicate the
completed state of the ticket
default Boolean If True, this status is the default for newly
created tickets if the status is not specified
3.3 Ticket Priority - Resource
A Ticket Priority describes the current importance of a ticket

3.3.1 Operations

3.3.1.1 Reading All Priorities

URL <base_uri>/<response_format>/priorities/
HTTP Method GET
Response Data List of Ticket Priority

3.3.1.2 Reading One Priority

URL <base_uri>/<response_format>/priority/<id>/
HTTP Method GET
Response Data Ticket Priority

3.3.2 Data Structures

3.3.2.1 Ticket Priority - Response Data Structure

This data structure contains information about a ticket priority

Field Type Description

id ID Unique numerical identifier
name String Name of the priority
default Boolean If True, this priority is the default for newly
created tickets if the priority is not specified
3.4 Staff - Resource
A Staff is a person handling Helpdesk duties like responding to incoming tickets, solving
the requests / problems covered in the tickets

3.4.1 Operations

3.4.1.1 Reading All Staff

Retrieve a list of all staff

URL <base_uri>/<response_format>/staff/
HTTP Method GET
Response Data List of Staff

3.4.1.2 Reading One Staff By ID

Retrieve details of a staff using their ID

URL <base_uri>/<response_format>/staff/<id>/
HTTP Method GET
Response Data Staff

3.4.1.3 Reading One Staff By Email

Retrieve details of a staff using the their email address

URL <base_uri>/<response_format>/staff/<email>/
HTTP Method GET
Response Data Staff

3.4.2 Data Structures

3.4.2.1 Staff - Response Data Structure

This data structure contains information about a Helpdesk staff

Field Type Description

id ID Unique numerical identifier
email String Email address of the Staff
name String Full name of the Staff
3.5 User - Resource
A User is a person opening a ticket on the Helpdesk.

3.5.1 Operations

3.5.1.1 Reading All Users

URL <base_uri>/<response_format>/users/?
size=<size>&page=<page>
HTTP Method GET
Response Data Paginated List of User
Additional Params size: number of items per page
(minimum 10, maximum 50, default 10)
page: the number of the page required

3.5.1.2 Reading One User By ID

Retrieve details of a user using the their ID

URL <base_uri>/<response_format>/user/<id>/
HTTP Method GET
Response Data User

3.5.1.3 Reading One User By Email

Retrieve details of a user using the their email address

URL <base_uri>/<response_format>/user/<email>/
HTTP Method GET
Response Data User

3.5.2 Data Structures

3.5.2.1 User - Response Data Structure

This data structure contains information about a user of the Helpdesk

Field Type Description

id ID Unique numerical identifier
email String Email address of the user
name String Full name of the user
custom_fields List of Custom Field The list of custom field values of the user
Value
3.6 Ticket - Resource
A Helpdesk request created by a User

3.6.1 Operations

3.6.1.1 Reading All Tickets

URL <base_uri>/<response_format>/tickets/?
size=<size>&page=<page>
HTTP Method GET
Response Data Paginated List of Ticket
Additional Params size: number of items per page
(minimum 10, maximum 50, default 10)
page: the number of the page required

3.6.1.2 Reading One Ticket

URL <base_uri>/<response_format>/ticket/<id>/
HTTP Method GET
Response Data Ticket

3.6.1.3 Create A Ticket

To create a ticket make a POST request to the URL below with request data encoded in
one of the supported formats. On success it returns the newly created ticket.

NOTE: file attachments are supported only when using Multipart Form Data

URL <base_uri>/<response_format>/tickets/
HTTP Method POST
Request Data Create Ticket or Create Ticket Using User Email & Name
Response Data Ticket

3.6.1.4 Add A Staff Update

To add a staff update make a POST request to the URL below with request data encoded
in one of the supported formats. On success it returns the modified ticket.

NOTE: file attachments are supported only when using Multipart Form Data

URL <base_uri>/<response_format>/ticket/<id>/staff_update/
HTTP Method POST
Request Data Add Staff Update
Response Data Ticket
3.6.1.5 Add A Staff Private Note
To add a staff private note make a POST request to the URL below with request data
encoded in one of the supported formats. On success it returns the modified ticket.

URL <base_uri>/<response_format>/ticket/<id>/staff_pvtnote/
HTTP Method POST
Request Data Add Staff Private Note
Response Data Ticket

3.6.1.6 Add A User Reply

To add a user reply make a POST request to the URL below with request data encoded in
one of the supported formats. On success it returns the modified ticket.

NOTE: file attachments are supported only when using Multipart Form Data

URL <base_uri>/<response_format>/ticket/<id>/user_reply/
HTTP Method POST
Request Data Add User Reply
Response Data Ticket

3.6.2 Data Structures

3.6.2.1 Ticket - Response Data Structure

This data structure contains information about a ticket in the Helpdesk

Field Type Description

id ID Unique numerical identifier
subject String The subject of the ticket
category Category The category under which the ticket is present
status Status The current status of the ticket
priority Priority The current priority of the ticket
user User The user who created the ticket
assigned_to Staff The staff currently assigned
created_at Timestamp The time when the ticket was created
last_updated_at Timestamp The time when the ticket was last update
last_accessed_at Timestamp The time when the ticket was last accessed
last_user_reply_at Timestamp The time when a user last replied to a ticket
last_staff_reply_at Timestamp The time when a staff last replied to a ticket
(Can be NULL)
time_spent Integer Total time spent by staff on the ticket
 due_date Date The due date for completion of the ticket
updates List of Ticket The list of updates that were done on a ticket
Update
custom_fields List of Custom The list of custom fields values in the ticket
Field Value

3.6.2.2 Ticket Update - Inner Data Structure

This is a inner data structure present in the "updates" field of Ticket. It is used to describe
the updates done on the ticket.

Field Type Description

timestamp DateTime The time when the update was added
by Ticket Update By who was the ticket updated
By
message Ticket Message Details of the message
(Can be NULL)
status_change Ticket Status The IDs of the old and new Statuses
Change
(Can be NULL)
priority_change Ticket Priority The IDs of the old and new Priorities
Change
(Can be NULL)
assignee_change Ticket Assignee The IDs of the old and new Staff
Change
(Can be NULL)
category_change Ticket Category The IDs of the old and new categories
Change
(Can be NULL)
due_date_change Ticket Due Date The the old and new due dates
Change
(Can be NULL)
time_spent Integer Time spent by staff on the ticket
(Can be NULL)

3.6.2.3 Ticket Update By - Inner Data Structure

This is a inner data structure present in the "by" field of Ticket Update. It is used to
describe the source of the update.

Field Type Description

type String "staff" or "user" or "smartrule" to indicate the
who updated the ticket
id ID ID of the corresponding staff/user/smartrule
3.6.2.4 Ticket Message- Inner Data Structure
This is a inner data structure present in the "message" field of Ticket Update. It is used to
describe the message update on a ticket.

Field Type Description

subject String The subject of the message
text String The message text in plain-text format
html String The message text in HTML format
attachments List of Ticket The file attachments for this message
Attachment
message_type String “p” - Private Note
“f” - Forward
null – staff/customer update
cc_list String Comma separated list of email addresses
bcc_list String Comma separated list of email addresses
forward_list String Comma separated list of email addresses to
which the ticket is forwarded and it's present
only for forwarded messages i.e.
message_type = “f”

3.6.2.5 Ticket Attachment - Inner Data Structure

This is a inner data structure present in the "attachments" field of Ticket Message. It is
used to describe the file attachments for a message.

Field Type Description

filename String The name of the file
url String The URL where the attachment can be
accessed

3.6.2.6 Ticket Status Change - Inner Data Structure

This is a inner data structure present in the "status_change" field of Ticket Update. It is
used to describe the status change of a ticket.

Field Type Description

old ID ID of the old status
new ID ID of the new status

3.6.2.7 Ticket Priority Change - Inner Data Structure

This is a inner data structure present in the "priority_change" field of Ticket Update. It is
used to describe the priority change of a ticket.
 Field Type Description
old ID ID of the old priority
new ID ID of the new priority

3.6.2.8 Ticket Assignee Change - Inner Data Structure

This is a inner data structure present in the "assignee_change" field of Ticket Update. It is
used to describe the change of a ticket's assigned staff.

Field Type Description

old ID ID of the old staff
(Can be NULL)
new ID ID of the new staff
(Can be NULL)

3.6.2.9 Ticket Category Change - Inner Data Structure

This is a inner data structure present in the "category_change" field of Ticket Update. It is
used to describe the category change of a ticket.

Field Type Description

old ID ID of the old category
new ID ID of the new category

3.6.2.10 Ticket Due Date Change - Inner Data Structure

This is a inner data structure present in the "due_date_change" field of Ticket Update. It is
used to describe the change of a ticket due date.

Field Type Description

old Date Old due date
(Can be NULL)
new Date New due date

3.6.2.11 Create Ticket - Request Data Structure

This data structure contains information required to create a ticket.

NOTE: Any custom fields required for the ticket need to be appended to the list below. See

Ticket Custom Field Values For Create Ticket for information.

Field Type Description

subject String The ticket subject
text String The ticket message in plain-text format
attachments Attachments The file attachments for this ticket
 category ID ID of the ticket category
priority ID ID of the ticket priority
user ID ID of the user creating the ticket

3.6.2.12 Create Ticket Using User Email & Name - Request Data
Structure
This data structure contains information required to create a ticket. This variation uses the
email and name of a user. If the email already exists in the Helpdesk, the corresponding
user is used, else a new user is created.

NOTE: Any custom fields required for the ticket and user need to be appended to the list
below. See Ticket Custom Field Values For Create Ticket and User Custom Field Values
For Create Ticket for information.

Field Type Description

subject String The ticket subject
text String The ticket message in plain-text format
attachments Attachments The file attachments for this ticket
category ID ID of the ticket category
priority ID ID of the ticket priority
email String Email address of the user
name String Full name of the user

3.6.2.13 Add Staff Update - Request Data Structure

This data structure contains information required to add an staff update to a ticket.

Field Type Description

staff ID ID of the staff adding this update
subject String The update subject
text String The update message in plain-text format
cc String Comma separated list of email addresses
bcc String Comma separated list of email addresses
attachments Attachments The file attachments for this update
status ID ID of the ticket's new status
(Can be NULL)
priority ID ID of the ticket's new priority
(Can be NULL)
assignee ID ID of staff the ticket is reassigned to
(Can be NULL)
time_spent Integer Time spent by the staff on this ticket
 (Can be NULL)
due_date Date New due date for the ticket
(Can be NULL)
tags String Comma separated list of tags
(Can be NULL)
notify_user Boolean If True, send email notification to the user
about this update

3.6.2.14 Add Staff Private Note - Request Data Structure

This data structure contains information required to add an staff private note to a ticket.

Field Type Description

staff ID ID of the staff adding this update
subject String New subject for the ticket
(Can be NULL)
text String The update message in plain-text format
status ID ID of the ticket's new status
(Can be NULL)
priority ID ID of the ticket's new priority
(Can be NULL)
time_spent Integer Time spent by the staff on this ticket
(Can be NULL)
due_date Date New due date for the ticket
(Can be NULL)
tags String New tags as comma separated list
(Can be NULL)
alert_to ID ID of a staff to send email notification to
(Can be NULL) (cannot be the same as the ID used for the
staff field)

3.6.2.15 Add User Reply - Request Data Structure

This data structure contains information required to add an user reply to a ticket.

Field Type Description

user ID ID of the user sending this reply
text String The reply message in plain-text format
cc String Comma separated list of email addresses
bcc String Comma separated list of email addresses
attachments Attachments The file attachments for this reply

3.6.2.16 Attachments - File Upload Request

This section describes the request format to be used for upload file attachments for
creating a ticket or in a reply/update.

File uploads are only supported with Multipart Form Data format. To upload a file, construct
the request as documented at http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4.2
(check if library functions are available in your programming languages to prepare
Multipart Form Data requests)

To upload multiple files, repeat the "attachments" field as required.

3.7 Custom Fields
Custom fields allow additional data to be added to the Helpdesk as required. Custom fields
can be defined for independently for users and tickets. For example, a phone number
custom field can be added for users.

3.7.1 Operations

3.7.1.1 Reading All User Custom Fields

URL <base_uri>/<response_format>/user_custom_fields/
HTTP Method GET
Response Data List of User Custom Field

3.7.1.2 Reading One User Custom Fields

URL <base_uri>/<response_format>/user_custom_field/<id>/
HTTP Method GET
Response Data User Custom Field

3.7.1.3 Reading All Ticket Custom Fields

URL <base_uri>/<response_format>/ticket_custom_fields/
HTTP Method GET
Response Data List of Ticket Custom Field

3.7.1.4 Reading One Ticket Custom Field

URL <base_uri>/<response_format>/ticket_custom_field/<id>/
HTTP Method GET
Response Data Ticket Custom Field

3.7.2 Types

3.7.2.1 Custom Field Types

Custom fields can be of the following data types

Custom Field Type Data Type Of Value

text String
number Float
choice String
multiple_choice List of String
3.7.2.2 Custom Field Choice Types
A custom field's choice can be of the following types based on the type of the custom field

Custom Field Type Value for Choices

text NULL
number NULL
choice List of Choice Item
multiple_choice List of Multiple Choice Item

3.7.3 Data Structures

3.7.3.1 User Custom Field – Response Data Structure

This data structure contains information about a custom field defined for users

Field Type Description

id ID Unique numerical identifier
name String Name of the custom field
type String A type as listed in Custom Field Types
depends_on_choice ID ID of the choice that this custom field
(Can be NULL) depends on
required Boolean If true, this field has to be filled in when
creating a new ticket
visible_to_staff_only Boolean If true, this field is private to staff alone and
should not be shown to the users
choices Depends on Choices for "choice" and "multiple_choice"
type as listed in custom fields, NULL for other types
Custom Field
Choice Types
order Integer The order in which to show custom fields
during data entry or display

3.7.3.2 Ticket Custom Field - Response Data Structure

This data structure contains information about a custom field defined for tickets. Each
ticket category can have its own sub-set of ticket custom fields, this information is
contained in the "categories" field of the data structure.

Field Type Description

id ID Unique numerical identifier
name String Name of the custom field
type Custom Field A type as listed in Custom Field
Type Types
depends_on_choice ID ID of the choice that this custom field
 (Can be NULL) depends on
required Boolean If true, this field has to be filled in
when creating a new ticket
visible_to_staff_only Boolean If true, this field is private to staff
alone and should not be shown to the
users
choices Depends on The choices for "choice" and
type as listed in "multiple_choice" custom fields,
Custom Field NULL for other types
Choice Types
compulsory_on_completed Boolean If true, this field has to be filled in
before the ticket can be set to any of
the completed Status
categories List of Ticket Information about which categories
Custom Fields this custom field is present in and the
To Category display order

3.7.3.3 Ticket Custom Fields To Category - Inner Data Structure

This is a inner data structure present in the "categories" field of Ticket Custom Field. It is
used to define which ticket categories the ticket custom field is associated with.

Field Type Description

category ID ID of the category in which the Ticket
Custom Field appears
order Integer The order in which to show custom fields
during data entry or display

3.7.3.4 Choice Item - Inner Data Structure

This is a inner data structure present in the "choices" field of User Custom Field and Ticket
Custom Field. It is used to define which choices are defined in this "choice" type custom
field.

Field Type Description

id ID Unique numerical identifier
text String The text of the choice
dependant_fields List of ID IDs of the custom fields that depend on this
choice

3.7.3.5 Multiple Choice Item - Inner Data Structure

This is a inner data structure used for the "choices" field of User Custom Field and Ticket
Custom Field. It is used to define which choices are defined in this "multiple_choice" type
custom field.
 Field Type Description
id ID Unique numerical identifier
text String The text of the choice

3.7.3.6 Custom Field Value - Inner Data Structure

This is a inner data structure used for the "custom_fields" field of User and Ticket. It is
used to define the value of the custom field.

Field Type Description

name String Name of the custom field
type String A type as listed in Custom Field Types
value Depends on Value of the custom field
type as listed in
Custom Field
Types

3.7.4 Notes

3.7.4.1 Common Information For Setting Ticket / User Custom Field

Values
1. When the "depends_on_choice" field of a custom field set to a non-NULL value, it is
applicable only when the corresponding choice is selected. The "dependant_fields"
field of Choice Item can also be used to determine which custom fields are
applicable when the choice is selected

2. Values for "multiple_choice" type custom fields should be sent as multiple fields with
the same field name when using Form Urlencoded and Multipart Form Data
formats. The values can be sent as List for JSON and YAML formats.

3.7.4.2 Ticket Custom Field Values For Create Ticket

1. All the points in Common Information For Setting Ticket / User Custom Field Values

2. The values for ticket custom fields should be appended to the fields for Create
Ticket

3. The value for a ticket custom field should be sent using a field name constructed
from the ID of the ticket custom field in the following format "t-cf-<id>"

4. The ticket custom fields applicable to a ticket are dependent on the ticket's
category. This can be determined from the "categories" field of Ticket Custom Field
3.7.4.3 User Custom Field Values For Create Ticket
1. All the points in Common Information For Setting Ticket / User Custom Field Values

2. The values for user custom fields should be appended to the fields for Create Ticket

3. The value for a user custom fields should be sent using a field name constructed
from the ID of the user custom field in the following format "c-cf-<id>"