Introduction to the Help Desk API
Start with our Core API docs for an introduction to the Kloudless API and more information on connecting user accounts and performing API requests.
Once an account is connected to your application, your application can begin making requests to the Help Desk API endpoints listed below.
Here are the supported services, listed with service identifiers:
- Help Desk Services
- Zendesk
zendesk
- Freshdesk
freshdesk
- Zendesk
The Help Desk API includes the following object types:
-
ticket
-
comment
Each object type is documented below, with its standard Kloudless attributes listed.
Kloudless object attributes that are absent in the upstream service
will be null
when retrieved, and ignored when sent in create/update
requests.
Tickets
A Ticket object represents an individual Help Desk ticket’s metadata.
-
id
Unique identifier for the ticket. -
api
Will always behelpdesk
. -
type
Will always beticket
. -
ticket_type
A string representing the type of ticket. -
subject
The subject of the ticket. -
description
The description of the ticket. This could be an HTML string. -
priority
Can be one of four values:low
,normal
,high
, orurgent
. -
status
Can be one of four values:open
,pending
,resolved
, orclosed
. -
tags
A list of tags associated with the ticket. -
public
A boolean value indicating whether the ticket is public or not. -
due_at
ISO 8601 timestamp indicating the ticket due date. -
custom_properties
A list ofCustomProperty
objects. -
group
A string representing the group this ticket belongs to. -
company
A string representing the company associated with this ticket. -
requester
APerson
object representing who requested the ticket. -
submitter
A string representing the submitter of the ticket. -
assignee
A string representing the assignee of the ticket. -
email_ccs
A list ofPerson
objects representing people cc’d to this ticket. -
followers
A list ofPerson
objects representing people following this ticket. -
created_at
ISO 8601 timestamp indicating when the ticket was created. -
modified_at
ISO 8601 timestamp indicating when the ticket was last modified.
Person objects have the following structure:
-
user_id
A string representing the user’s id in the upstream system. -
email
Email address of the person. -
name
Name of the person. Note that this field is read-only and is not supported for the purpose of creating tickets.
CustomProperty objects have the following structure:
-
id
The custom property’s id or key. -
value
The custom property’s value.
List Tickets
This endpoint enables you to retrieve all tickets from your Help Desk account.
Example request:
curl -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v1/accounts/me/helpdesk/tickets/'
Page sizes requested are treated as advisory. (Some services may not support
page_size
, or may have restrictions on how big or small the page size
can be.)
The response contains the following information, where each object is a Ticket:
-
count
Integer. Number of objects on this page. -
page
String. Page identifier. -
next_page
The value to provide in the request’spage
query parameter for the next page. This will benull
if there are no more pages. -
objects
Array. List of objects.
- Parameters
- page_size
number
(optional) Default: 100Number of objects in each page. The
page_size
is treated as advisory and may not be strictly adhered to, depending on the upstream service’s capabilities. Thepage_size
must be between1
and1000
.- page
string
(optional)Page to return. If
page
is not specified, the first page is returned, containingpage_size
objects. To retrieve pages after the first page, setpage
to the value ofnext_page
returned in the previous response.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "count": 1, "page": 1, "next_page": null, "objects": [ { "api": "helpdesk", "id": "ticket_NjQ2MTUz", "type": "ticket", "ticket_type": null, "subject": "test ticket", "description": "<div>this is a ticket</div>", "priority": "high", "status": "open", "tags": [], "public": true, "due_at": "2020-08-25T19:50:31Z", "custom_properties": [], "group": null, "company": null, "requester": { "user_id": "3008384627", "email": "test@test.com", "name": null }, "assignee": null, "email_ccs": [ { "email": "test2@test.com" }, { "email": "test3@test.com" } ], "followers": [], "created_at": "2020-08-25T07:50:31Z", "modified_at": "2020-08-25T07:50:31Z" } ], "type": "object_list", "api": "helpdesk" }
Retrieve a Ticket
This API endpoint retrieves metadata for an individual ticket when provided its ID.
Example request:
curl -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v1/accounts/me/tickets/ticket_MTIx'
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "api": "helpdesk", "id": "ticket_NjQ2MTUz", "type": "ticket", "ticket_type": null, "subject": "test ticket", "description": "<div>this is a ticket</div>", "priority": "high", "status": "open", "tags": [], "public": true, "due_at": "2020-08-25T19:50:31Z", "custom_properties": [], "group": null, "company": null, "requester": { "user_id": "3008384627", "email": "test@test.com", "name": null }, "assignee": null, "email_ccs": [ { "email": "test2@test.com" }, { "email": "test3@test.com" } ], "followers": [], "created_at": "2020-08-25T07:50:31Z", "modified_at": "2020-08-25T07:50:31Z" }
Create a Ticket
To create a ticket, perform a POST request with a JSON object with any of the following attributes:
-
ticket_type
The type of ticket in the upstream service. -
subject
(required) The subject of the ticket. -
description
(required) The description of the ticket. -
priority
Eitherlow
,normal
,high
, orurgent
. Defaults tonormal
. -
status
Eitheropen
,pending
,resolved
, orclosed
. Defaults toopen
. -
tags
A list of strings representing tags associated with the ticket. -
public
A boolean value representing whether the ticket is public or not. Defaults totrue
. Note that forfreshdesk
, this field is not supported (tickets are always public). -
due_at
ISO 8601 timestamp indicating the ticket due date. Note that forfreshdesk
, this will set both the upstreamdue_by
andfr_due_by
properties. -
custom_properties
A list of CustomProperty objects. -
group
A string representing the group associated with the ticket. -
company
A string representing the company associated with the ticket. -
requester
A Person object representing the person requesting the ticket. If this field is present, either auser_id
oremail
should be provided. Forfreshdesk
, therequester
field is required. Forzendesk
, currently onlyuser_id
is supported. -
submitter
An identifier (upstream service specific) of the submitter of the ticket. Not supported byfreshdesk
. -
assignee
An identifier (upstream service specific) of the assignee of the ticket. -
email_ccs
A list of Person objects representing people cc’d to the ticket. Forfreshdesk
, ifemail_ccs
is present, only theemail
subfield is supported. -
followers
A list of Person objects representing people following the ticket. Not supported byfreshdesk
.
Here is an example request:
curl -X POST -H 'Authorization: Bearer [TOKEN]' \
-H 'Content-Type: application/json' \
'https://api.kloudless.com/v1/accounts/me/helpdesk/tickets/' \
-d '{
"subject": "test ticket",
"description": "<div>this is a ticket</div>",
"status": "open",
"priority": "high",
"requester": {"email": "test@test.com"},
"email_ccs": [{"email": "test2@test.com"}, {"email": "test3@test.com"}]
}'
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "subject": "test ticket", "description": "<div>this is a ticket</div>", "status": "open", "priority": "high", "requester": { "email": "test@test.com" }, "email_ccs": [ { "email": "test2@test.com" }, { "email": "test3@test.com" } ] }
- Response
201
Toggle Body
{ "api": "helpdesk", "id": "ticket_NjQ2MTUz", "type": "ticket", "ticket_type": null, "subject": "test ticket", "description": "<div>this is a ticket</div>", "priority": "high", "status": "open", "tags": [], "public": true, "due_at": "2020-08-25T19:50:31Z", "custom_properties": [], "group": null, "company": null, "requester": { "user_id": "3008384627", "email": "test@test.com", "name": null }, "assignee": null, "email_ccs": [ { "email": "test2@test.com" }, { "email": "test3@test.com" } ], "followers": [], "created_at": "2020-08-25T07:50:31Z", "modified_at": "2020-08-25T07:50:31Z" }
Update a Ticket
To update a ticket, perform a PATCH request with a JSON object with any of the following attributes:
-
ticket_type
-
subject
-
description
-
priority
-
status
-
tags
-
public
Not supported forfreshdesk
. Tickets are always public. -
due_at
Note that forfreshdesk
, this will set both the upstreamdue_by
andfr_due_by
properties. -
custom_properties
-
group
-
company
-
requester
Forzendesk
, currently onlyuser_id
is supported. -
submitter
Not supported byfreshdesk
. -
assignee
-
email_ccs
Forfreshdesk
, ifemail_ccs
is present, only theemail
subfield is supported. -
followers
Not supported byfreshdesk
.
Here is an example request:
curl -X PATCH -H 'Authorization: Bearer [TOKEN]' \
-H 'Content-Type: application/json' \
'https://api.kloudless.com/v1/accounts/me/helpdesk/tickets/ticket_MTIx' \
-d '{
"status": "open",
"priority": "high"
}'
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "status": "open", "priority": "high" }
- Response
200
Toggle Body
{ "api": "helpdesk", "id": "ticket_NjQ2MTUz", "type": "ticket", "ticket_type": null, "subject": "test ticket", "description": "<div>this is a ticket</div>", "priority": "high", "status": "open", "tags": [], "public": true, "due_at": "2020-08-25T19:50:31Z", "custom_properties": [], "group": null, "company": null, "requester": { "user_id": "3008384627", "email": "test@test.com", "name": null }, "assignee": null, "email_ccs": [ { "email": "test2@test.com" }, { "email": "test3@test.com" } ], "followers": [], "created_at": "2020-08-25T07:50:31Z", "modified_at": "2020-08-25T07:50:31Z" }
Delete a Ticket
This API endpoint deletes an individual ticket when provided its ID.
Example request:
curl -X DELETE -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v1/accounts/me/tickets/ticket_MTIx'
- Response
204
Comments
A Comment object represents a comment or reply to a ticket.
-
id
Unique identifier for the comment. -
api
Will always behelpdesk
. -
type
Will always becomment
. -
content
The content of the comment. This could be an HTML string. -
author
An identifier (upstream service specific) for the author of the comment. -
public
A boolean representing whether the comment is private or public. -
attachments
A list ofAttachment
objects tied to this comment. -
created_at
ISO 8601 timestamp indicating when the comment was created. -
modified_at
ISO 8601 timestamp indicating when the comment was last modified.
Attachment objects have the following structure:
-
id
The id of the attachment. -
filename
The filename of the attachment. -
content_type
The content type of the attachment. -
url
The download url of the attachment. -
thumb_url
The thumbnail url of the attachment if it’s an image. -
size
The size of the attachment.
List Ticket Comments
Create a Comment
To create a ticket comment, perform a POST request with a JSON object with any of the following attributes:
-
content
The content of the comment. -
author
An identifier (upstream service specific) of the author of the comment. -
public
A boolean representing whether the comment is public or private. Defaults totrue
.
Here is an example request:
curl -X POST -H 'Authorization: Bearer [TOKEN]' \
-H 'Content-Type: application/json' \
'https://api.kloudless.com/v1/accounts/me/helpdesk/tickets/ticket_NjQ1NjIz/comments' \
-d '{
"content": "<div>This is a test comment</div>."
}'
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "content": "<div>This is a test comment</div>." }
- Response
201
Toggle Body
{ "api": "helpdesk", "id": "comment_MzExOTg2MTQ2Mw", "type": "comment", "content": "<div>This is a test comment.</div>", "author": "4206043", "public": false, "attachments": [], "created_at": "2020-08-25T07:54:31Z" }
Update a Comment
To update a ticket comment, perform a PATCH request with a JSON object with any of the following attributes:
-
content
-
author
Not supported forfreshdesk
. -
public
Not supported forfreshdesk
.
Here is an example request:
curl -X PATCH -H 'Authorization: Bearer [TOKEN]' \
-H 'Content-Type: application/json' \
'https://api.kloudless.com/v1/accounts/me/helpdesk/tickets/ticket_MTIx/comments/comment_MzExOTMwMDczMQ' \
-d '{
"content": "<div>This is a test comment</div>."
}'
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "content": "<div>This is a test comment</div>." }
- Response
200
Toggle Body
{ "api": "helpdesk", "id": "comment_MzExOTg2MTQ2Mw", "type": "comment", "content": "<div>This is a test comment.</div>", "author": "4206043", "public": false, "attachments": [], "created_at": "2020-08-25T07:54:31Z" }
Delete a Comment
This API endpoint deletes an individual ticket comment when provided its ID.
Example request:
curl -X DELETE -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v1/accounts/me/tickets/ticket_MTIx/comments/comment_MzExOTMwNzY0OQ'
- Response
204
/accounts/{account_id}/helpdesk/tickets/{ticket_id}/comments{?page,page_size}
This endpoint enables you to retrieve all comments associated with a given ticket.
Example request:
curl -H 'Authorization: Bearer [TOKEN]' \ 'https://api.kloudless.com/v1/accounts/me/helpdesk/tickets/ticket_NjQ1NjIz/comments?page_size=1&page=2'
Page sizes requested are treated as advisory. (Some services may not support
page_size
, or may have restrictions on how big or small the page size can be.)The response contains the following information, where each object is a Comment:
count
Integer. Number of objects on this page.page
String. Page identifier.next_page
The value to provide in the request’spage
query parameter for the next page. This will benull
if there are no more pages.objects
Array. List of objects.number
(optional) Default: 100Number of objects in each page. The
page_size
is treated as advisory and may not be strictly adhered to, depending on the upstream service’s capabilities. Thepage_size
must be between1
and1000
.string
(optional)Page to return. If
page
is not specified, the first page is returned, containingpage_size
objects. To retrieve pages after the first page, setpage
to the value ofnext_page
returned in the previous response.200
ToggleHeaders
Content-Type: application/json
Body
{ "count": 1, "page": 1, "next_page": null, "objects": [ { "api": "helpdesk", "id": "comment_MzExOTg2MTQ2Mw", "type": "comment", "content": "<div>This is a test comment.</div>", "author": "4206043", "public": false, "attachments": [], "created_at": "2020-08-25T07:54:31Z" } ], "type": "object_list", "api": "helpdesk" }