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": "leonardhaff@example.com",
                        "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": "defaultcategory@example.com",
                        "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": "category93@example.com",
                        "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": "leonardhaff@example.com", 
                "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": "useremailid@example.com",
        "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": "optionalCCUserEmailID@example.com",
        "bcc": "optionalBCCUserEMailID@example.com"
    }
                    
                

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": "scott@example.com", 
                        "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": "scott@example.com", 
                                "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": "john.smith@example.com", 
                        "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": "john.smith@example.com", 
                "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
        }
    ]