Help Desk API Docs
Ticket
Tickets are the means through which your end users (customers) communicate with agents inside HappyFox Helpdesk.
Read 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 |
Data Structure
JSON
[
{
"page_info": {
"count": 3,
"last_index": 37,
"page_count": 13,
"start_index": 34,
"end_index": 36
},
"data": [
{
"category": {
"id": 1,
"description": "Default Category, please edit this.",
"name": "General",
"public": true
},
"status": {
"default": false,
"name": "Closed",
"behavior": "completed",
"id": 5
},
"updates": [
{
"priority_change": null,
"category_change": null,
"timestamp": "2012-12-05 09:29:31",
"due_date_change": null,
"time_spent": null,
"message": {
"attachments": [],
"bcc_list": "",
"text": "Articles can be placed in sections and sub sections, and built using rich content that includes rich text, images, videos and other media that is accessible via a URL.",
"cc_list": "",
"customer_updated": false,
"html": "Articles can be placed in sections and sub sections, and built using rich content that includes rich text, images, videos and other media that is accessible via a URL.",
"forward_list": null,
"message_type": null,
"subject": ""
},
"assignee_change": null,
"status_change": null,
"by": {
"type": "user",
"id": 94
}
},
{
"priority_change": {
"new": 2,
"old": 1
},
"category_change": null,
"timestamp": "2012-12-05 09:29:31",
"due_date_change": null,
"time_spent": null,
"message": null,
"assignee_change": null,
"status_change": null,
"by": {
"type": "smartrule",
"id": 2
}
},
{
"priority_change": null,
"category_change": null,
"timestamp": "2012-12-05 09:30:33",
"due_date_change": null,
"time_spent": null,
"message": null,
"assignee_change": null,
"status_change": null,
"by": null
},
{
"priority_change": null,
"category_change": null,
"timestamp": "2012-12-10 09:15:01",
"due_date_change": null,
"time_spent": null,
"message": null,
"assignee_change": null,
"status_change": {
"new": 5,
"old": 1
},
"by": {
"type": "staff",
"id": 1
}
}
],
"time_spent": null,
"due_date": null,
"created_at": "2012-12-05 09:29:31",
"last_updated_at": "2012-12-05 09:29:31",
"last_user_reply_at": "2012-12-05 09:29:31",
"priority": {
"default": false,
"name": "Critical",
"id": 2
},
"last_staff_reply_at": null,
"user": {
"id": 94,
"email": "[email protected]",
"custom_fields": [],
"name": "leonard"
},
"last_accessed_at": "2012-12-05 09:29:32",
"assigned_to": null,
"id": 240,
"custom_fields": [],
"subject": "KB articles"
},
{
"category": {
"id": 1,
"description": "Default Category, please edit this.",
"name": "General",
"public": true
},
"status": {
"default": true,
"name": "New",
"behavior": "pending",
"id": 1
},
"updates": [
{
"priority_change": null,
"category_change": null,
"timestamp": "2012-12-05 09:29:18",
"due_date_change": null,
"time_spent": null,
"message": {
"attachments": [],
"bcc_list": "",
"text": "The API supports operations as creating a ticket, adding updates to a ticket, listing tickets and users of the help desk, etc. It supports JSON, Form URLencoded and Multipart Form Data formats.",
"cc_list": "",
"customer_updated": false,
"html": "The API supports operations as creating a ticket, adding updates to a ticket, listing tickets and users of the help desk, etc. It supports JSON, Form URLencoded and Multipart Form Data formats.",
"forward_list": null,
"message_type": null,
"subject": ""
},
"assignee_change": null,
"status_change": null,
"by": {
"type": "user",
"id": 92
}
},
{
"priority_change": {
"new": 2,
"old": 1
},
"category_change": null,
"timestamp": "2012-12-05 09:29:18",
"due_date_change": null,
"time_spent": null,
"message": null,
"assignee_change": null,
"status_change": null,
"by": {
"type": "smartrule",
"id": 2
}
},
{
"priority_change": null,
"category_change": null,
"timestamp": "2012-12-05 09:30:33",
"due_date_change": null,
"time_spent": null,
"message": null,
"assignee_change": null,
"status_change": null,
"by": null
}
],
"time_spent": null,
"due_date": null,
"created_at": "2012-12-05 09:29:18",
"last_updated_at": "2012-12-05 09:29:18",
"last_user_reply_at": "2012-12-05 09:29:18",
"priority": {
"default": false,
"name": "Critical",
"id": 2
},
"last_staff_reply_at": null,
"user": {
"id": 92,
"email": "[email protected]",
"custom_fields": [],
"name": "tester"
},
"last_accessed_at": "2012-12-05 09:29:19",
"assigned_to": null,
"id": 238,
"custom_fields": [],
"subject": "API"
},
{
"category": {
"id": 1,
"description": "Default Category, please edit this.",
"name": "General",
"public": true
},
"status": {
"default": true,
"name": "New",
"behavior": "pending",
"id": 1
},
"updates": [
{
"priority_change": null,
"category_change": null,
"timestamp": "2012-12-05 09:29:25",
"due_date_change": null,
"time_spent": null,
"message": {
"attachments": [],
"bcc_list": "",
"text": "The built-in Knowledge Base is linked to the end user interface and allows you to build articles within sections, for use as an online reference medium.",
"cc_list": "",
"customer_updated": false,
"html": "The built-in Knowledge Base is linked to the end user interface and allows you to build articles within sections, for use as an online reference medium.",
"forward_list": null,
"message_type": null,
"subject": ""
},
"assignee_change": null,
"status_change": null,
"by": {
"type": "user",
"id": 93
}
},
{
"priority_change": {
"new": 2,
"old": 1
},
"category_change": null,
"timestamp": "2012-12-05 09:29:25",
"due_date_change": null,
"time_spent": null,
"message": null,
"assignee_change": null,
"status_change": null,
"by": {
"type": "smartrule",
"id": 2
}
},
{
"priority_change": null,
"category_change": null,
"timestamp": "2012-12-05 09:30:33",
"due_date_change": null,
"time_spent": null,
"message": null,
"assignee_change": null,
"status_change": null,
"by": null
}
],
"time_spent": null,
"due_date": null,
"created_at": "2012-12-05 09:29:25",
"last_updated_at": "2012-12-05 09:29:25",
"last_user_reply_at": "2012-12-05 09:29:25",
"priority": {
"default": false,
"name": "Critical",
"id": 2
},
"last_staff_reply_at": null,
"user": {
"id": 93,
"email": "[email protected]",
"custom_fields": [],
"name": "ram"
},
"last_accessed_at": "2012-12-05 09:29:26",
"assigned_to": null,
"id": 239,
"custom_fields": [],
"subject": "Knowledge base"
}
]
}
]
Read One Ticket
| URL | <base_uri> / <response_format> /ticket /<id>/ |
|---|---|
| HTTP Method | GET |
| Response Data | Ticket |
Data Structure
JSON
[
{
"category": {
"id": 1,
"description": "Default Category, please edit this.",
"name": "General",
"public": true
},
"status": {
"default": false,
"name": "Closed",
"behavior": "completed",
"id": 5
},
"updates": [
{
"priority_change": null,
"category_change": null,
"timestamp": "2012-12-05 09:29:31",
"due_date_change": null,
"time_spent": null,
"message": {
"attachments": [],
"bcc_list": "",
"text": "Articles can be placed in sections and sub sections, and built using rich content that includes rich text, images, videos and other media that is accessible via a URL.",
"cc_list": "",
"customer_updated": false,
"html": "Articles can be placed in sections and sub sections, and built using rich content that includes rich text, images, videos and other media that is accessible via a URL.",
"forward_list": null,
"message_type": null,
"subject": ""
},
"assignee_change": null,
"status_change": null,
"by": {
"type": "user",
"id": 94
}
},
{
"priority_change": {
"new": 2,
"old": 1
},
"category_change": null,
"timestamp": "2012-12-05 09:29:31",
"due_date_change": null,
"time_spent": null,
"message": null,
"assignee_change": null,
"status_change": null,
"by": {
"type": "smartrule",
"id": 2
}
},
{
"priority_change": null,
"category_change": null,
"timestamp": "2012-12-05 09:30:33",
"due_date_change": null,
"time_spent": null,
"message": null,
"assignee_change": null,
"status_change": null,
"by": null
},
{
"priority_change": null,
"category_change": null,
"timestamp": "2012-12-10 09:15:01",
"due_date_change": null,
"time_spent": null,
"message": null,
"assignee_change": null,
"status_change": {
"new": 5,
"old": 1
},
"by": {
"type": "staff",
"id": 1
}
}
],
"time_spent": null,
"due_date": null,
"created_at": "2012-12-05 09:29:31",
"last_updated_at": "2012-12-05 09:29:31",
"last_user_reply_at": "2012-12-05 09:29:31",
"priority": {
"default": false,
"name": "Critical",
"id": 2
},
"last_staff_reply_at": null,
"user": {
"id": 94,
"email": "[email protected]",
"custom_fields": [],
"name": "leonard"
},
"last_accessed_at": "2012-12-05 09:29:32",
"assigned_to": null,
"id": 240,
"custom_fields": [],
"subject": "KB articles"
}
]
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 |
Data Structure
JSON
{
"subject": "Test Ticket",
"text": "This is a test ticket created using API.",
"category": 1,
"priority": 2,
"user": 24
}
Notes:
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.
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>"
Errors
If you specify an invalid user, you will get the error
"field": "client",
"errors": [
"Select a valid choice. That choice is not one of the available choices."
]
Create new ticket using email and ID
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.
Data Structure
JSON
{
"subject":"Test Ticket",
"text":"This is a test ticket created using API.",
"category": 1,
"priority": 2,
"email": "[email protected]",
"name": "Example Name"
}
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 |
Data Structure
JSON
{
"assignee" : 20,
"due_date" : "2012-12-21",
"notify_user" : 1,
"priority" : 1,
"staff" : 13,
"status" : 2,
"text" : "Sure. Once your payment gets unflagged, we will send across your tickets to your email address.\n\nThanks\n",
"time_spent" : 2
}
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 Update |
| Response Data | Ticket |
Data Structure
JSON
{
"alert_to" : 2,
"assignee" : 13,
"priority" : 3,
"staff" : 13,
"status" : 2,
"text" : "UnPaid invoices still exists in his account. Therefore he is receiving payment reminders."
}
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 |
Data Structure
JSON
{
"user": 24,
"text": "This is a test customer reply using API.",
"cc": "[email protected]",
"bcc": "[email protected]"
}
Search Tickets
| URL | <base_uri> / <response_format> /tickets/ ?q=<querystring> |
|---|---|
| HTTP Method | GET |
| Request Data | <querystring> can be replaced with just a single search keyword, or you can use the search syntax same as the one generated by the advanced search in the HappyFox User Interface. |
| Response Data | List of tickets matching the search criteria |
Advanced Search Keywords
| Keyword | Type | Description |
|---|---|---|
| id | String | List of ticket ids separated by comma. eg "q=id:7095,7094" |
| subscribed | Boolean | |
| unresponded | Boolean | |
| breached | Boolean | |
| has_attachments | Boolean | |
| tag | String | Comma separated values |
| duedate | String | Accepted values: today / yesterday / tomorrow / next 7 days / overdue (get all tickets that are overdue) |
| priority | String | Name of priority |
| status | String | Name of status |
| assignee | String | Values: none (unassigned tickets)/ any (assigned tickets)/ some keyword identifying staff like first name, last name, username, email, etc |
| group | String | Values: none(contact is not part of any group) / any (contact is part of a group) / name of contact group |
| contact | String | Identifying keyword like name of contact, email or phone number. |
| Custom Field names | String | Format: "< custom field name >: < custom field value >". Eg "Address: Georgetown". You can search by contact and ticket custom fields |
Data Structure
JSON
[
{
"page_info": {
"count": 1,
"last_index": 1,
"page_count": 1,
"start_index": 1,
"end_index": 1
},
"data": [
{
"display_id": "#SUPP00000252",
"last_user_reply_at": "2013-01-11 06:45:12",
"time_spent": null,
"id": 252,
"custom_fields": [],
"subject": "Can you please help me solve my problem?",
"category": {
"id": 2,
"description": null,
"name": "Sample",
"public": false
},
"attachments_count": 0,
"last_updated_at": "2013-01-11 06:45:12",
"priority": {
"default": true,
"name": "Normal",
"id": 1
},
"last_staff_reply_at": null,
"messages_count": 1,
"merged_tickets": [],
"status": {
"color": "FF9900",
"default": true,
"name": "New",
"behavior": "pending",
"id": 1
},
"due_date": null,
"tags": "",
"user": {
"name": "Scott",
"pending_tickets_count": 1,
"email": "[email protected]",
"tickets_count": 1,
"id": 97,
"custom_fields": []
},
"unresponded": true,
"merged_to": null,
"created_at": "2013-01-11 06:45:12",
"last_accessed_at": "2013-02-19 09:03:49",
"assigned_to": null,
"updates": [
{
"priority_change": null,
"category_change": null,
"timestamp": "2013-01-11 06:45:12",
"due_date_change": null,
"time_spent": null,
"message": {
"attachments": [],
"bcc_list": "",
"text": "Can you please help me solve my problem?",
"cc_list": "",
"customer_updated": false,
"html": "Can you please help me solve my problem?",
"forward_list": null,
"message_type": null,
"subject": ""
},
"assignee_change": null,
"status_change": null,
"by": {
"email": "[email protected]",
"type": "user",
"id": 97,
"name": "Scott"
}
}
]
}
],
"filters": {
"status": "_all",
"category": "_all",
"q": "Can you please help me solve my problem",
"sort": "updated"
}
}
]
Summary Information for All Tickets
| URL | <base_uri> / <response_format> / tickets / ?show_updates=0 |
|---|---|
| HTTP Method | GET |
| Response Data | List of tickets without any updates |
Data Structure
JSON
[
{
"page_info": {
"count": 1,
"last_index": 1,
"page_count": 1,
"start_index": 1,
"end_index": 1
},
"data": [
{
"display_id": "#DC00000001",
"first_message": "Can you please help me solve my problem?",
"last_user_reply_at": "2013-02-19 17:26:04",
"time_spent": null,
"id": 1,
"custom_fields": [],
"subject": "Can you please help me solve my problem?",
"category": {
"id": 1,
"description": "Default Category, please edit this.",
"name": "Default Category",
"public": true
},
"attachments_count": 0,
"last_updated_at": "2013-02-19 17:31:55",
"priority": {
"default": true,
"name": "Normal",
"id": 1
},
"last_staff_reply_at": "2013-02-19 17:31:55",
"messages_count": 7,
"sla_breaches": 0,
"merged_tickets": [],
"status": {
"color": "FF9900",
"default": true,
"name": "New",
"behavior": "pending",
"id": 1
},
"due_date": null,
"tags": "",
"user": {
"name": "John Smith",
"primary_phone": null,
"phones": [],
"pending_tickets_count": 1,
"id": 1,
"tickets_count": 1,
"email": "[email protected]",
"custom_fields": []
},
"unresponded": false,
"created_at": "2013-02-19 17:26:04",
"last_accessed_at": "2013-02-19 17:31:55",
"assigned_to": null,
"merged_to": null
}
],
"filters": {
"status": "_all",
"category": "_all",
"q": "",
"sort": "updated"
}
}
]
Summary Information for One Ticket
| URL | <base_uri> / <response_format> /ticket / <id> / ?show_updates=0 |
|---|---|
| HTTP Method | GET |
| Response Data | Ticket without any updates |
Data Structure
JSON
[
{
"display_id": "#DC00000001",
"first_message": "Can you please help me solve my problem?",
"last_user_reply_at": "2013-02-19 17:26:04",
"time_spent": null,
"id": 1,
"custom_fields": [],
"subject": "Can you please help me solve my problem?",
"category": {
"id": 1,
"description": "Default Category, please edit this.",
"name": "Default Category",
"public": true
},
"attachments_count": 0,
"last_updated_at": "2013-02-19 17:31:55",
"priority": {
"default": true,
"name": "Normal",
"id": 1
},
"last_staff_reply_at": "2013-02-19 17:31:55",
"messages_count": 7,
"sla_breaches": 0,
"merged_tickets": [],
"status": {
"color": "FF9900",
"default": true,
"name": "New",
"behavior": "pending",
"id": 1
},
"due_date": null,
"tags": "",
"user": {
"name": "John Smith",
"primary_phone": null,
"phones": [],
"pending_tickets_count": 1,
"id": 1,
"tickets_count": 1,
"email": "[email protected]",
"custom_fields": []
},
"unresponded": false,
"created_at": "2013-02-19 17:26:04",
"last_accessed_at": "2013-02-19 17:31:55",
"assigned_to": null,
"merged_to": null
}
]