Help Desk API Docs

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

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 be helpdesk.
type Will always be ticket.
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, or urgent.
status Can be one of four values: open, pending, resolved, or closed.
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 of CustomProperty objects.
group A string representing the group this ticket belongs to.
company A string representing the company associated with this ticket.
requester A Person 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 of Person objects representing people cc’d to this ticket.
followers A list of Person 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

List TicketsGET /accounts/{account_id}/helpdesk/tickets/{?page,page_size}

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’s page query parameter for the next page. This will be null if there are no more pages.
objects Array. List of objects.

Parameters
page_size
number (optional) Default: 100
Number 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. The page_size must be between 1 and 1000.

page
string (optional)
Page to return. If page is not specified, the first page is returned, containing page_size objects. To retrieve pages after the first page, set page to the value of next_page returned in the previous response.

Response 200Toggle

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

Retrieve a TicketGET /accounts/{account_id}/helpdesk/tickets/{ticket_id}

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 200Toggle

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

Create a TicketPOST /accounts/{account_id}/helpdesk/tickets

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 Either low, normal, high, or urgent. Defaults to normal.
status Either open, pending, resolved, or closed. Defaults to open.
tags A list of strings representing tags associated with the ticket.
public A boolean value representing whether the ticket is public or not. Defaults to true. Note that for freshdesk, this field is not supported (tickets are always public).
due_at ISO 8601 timestamp indicating the ticket due date. Note that for freshdesk, this will set both the upstream due_by and fr_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 a user_id or email should be provided. For freshdesk, the requester field is required. For zendesk, currently only user_id is supported.
submitter An identifier (upstream service specific) of the submitter of the ticket. Not supported by freshdesk.
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. For freshdesk, if email_ccs is present, only the email subfield is supported.
followers A list of Person objects representing people following the ticket. Not supported by freshdesk.

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/json

Body

{
  "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 201Toggle

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

Update a TicketPATCH /accounts/{account_id}/helpdesk/tickets/{ticket_id}

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 for freshdesk. Tickets are always public.
due_at Note that for freshdesk, this will set both the upstream due_by and fr_due_by properties.
custom_properties
group
company
requester For zendesk, currently only user_id is supported.
submitter Not supported by freshdesk.
assignee
email_ccs For freshdesk, if email_ccs is present, only the email subfield is supported.
followers Not supported by freshdesk.

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/json

Body

{
  "status": "open",
  "priority": "high"
}

Response 200Toggle

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

Delete a TicketDELETE /accounts/{account_id}/helpdesk/tickets/{ticket_id}

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 be helpdesk.
type Will always be comment.
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 of Attachment 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

List Ticket CommentsGET /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’s page query parameter for the next page. This will be null if there are no more pages.
objects Array. List of objects.

Parameters
page_size
number (optional) Default: 100
Number 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. The page_size must be between 1 and 1000.

page
string (optional)
Page to return. If page is not specified, the first page is returned, containing page_size objects. To retrieve pages after the first page, set page to the value of next_page returned in the previous response.

Response 200Toggle

Headers

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"
}

Create a Comment

Create a CommentPOST /accounts/{account_id}/helpdesk/tickets/{ticket_id}/comments

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 to true.

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/json

Body

{
  "content": "<div>This is a test comment</div>."
}

Response 201Toggle

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

Update a CommentPATCH /accounts/{account_id}/helpdesk/tickets/{ticket_id}/comments/{comment_id}

To update a ticket comment, perform a PATCH request with a JSON object with any of the following attributes:

content
author Not supported for freshdesk.
public Not supported for freshdesk.

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/json

Body

{
  "content": "<div>This is a test comment</div>."
}

Response 200Toggle

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

Delete a CommentDELETE /accounts/{account_id}/helpdesk/tickets/{ticket_id}/comments/{comment_id}

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