API Reference: Tickets API Endpoints

All HappyFox help-desk instances are shipped with a RESTful web service API that enables various operations, including ticket creation, ticket update submission, ticket and user listing. This API supports payload formats such as JSON and multipart/form-data.

Requirements:

• Make sure you have generated an API and auth code by following this article
• Making HTTP requests (using GET and POST HTTP methods as a minimum requirement)
• Doing HTTP Basic Authentication
• Generating and reading data in the JSON format
• Optionally making HTTP POST requests using content type of "multipart/form-data" (needed for ticket attachments)

Documentation Conventions:

• The documentation indicates parameters that need to be replaced with actual values. 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
• Endpoint url format: /api/1.1/json/<module>/ - This tail url has to be prefixed with your HappyFox account url.

        Eg:- https://acme.happyfox.com/api/1.1/json/<module>/

• All HTTP POST API calls are to be explicitly marked as https. Else, it would be considered as GET only.

Note:

1) If you are using a custom domain, please use the custom domain url only.

2) API key and auth code are to be passed in Basic HTTP authentication format only. 

• To update assignee, status, priority, ticket custom fields, user custom fields, category, etc in the payload please use their IDs. Refer this article to fetch their IDs
• <module> - refers the module that is being accessed viz., /tickets/, /users/ etc. A full constructed example url: https://acme.happyfox.com/api/1.1/json/tickets/
• If your HappyFox account is hosted in EU, please use <instance_name>.happyfox.net. Eg. acme.happyfox.net
   

List of topics covered in this article

1.Get a list of all tickets

2.Get a paginated list of tickets

2.1 Using url query parameters and search strings

3.Ticket Detail Page

4.Create Ticket

5.Create Multiple Tickets

6.Create an inline attachment to be added to the ticket body

7.Fetch ticket attachment urls

8.Adding a Staff update

8.1 Update ticket properties

9.Adding a Staff private note

10.Adding a Contact Reply

11.Edit custom fields of a ticket

12.Update tags of a ticket

13.Subscribe to a ticket (agent only)

14.Unsubscribe ticket (agent only)

15.Forward a ticket to an external email address

16.Move ticket to another Category

17.Delete ticket

18.Create ticket with attachments

19.List all ticket custom fields

20.Fetch specific JSON fields 

1. Get a list of all Tickets

API Endpoint: /api/1.1/json/tickets/

Method: GET

Query parameters that can be passed to the url are listed below with their description

Back to top

2. Get a paginated list of tickets

API Endpoint : /api/1.1/json/tickets/?size=<size value>&page=<page number>

Default size value is 10 and can be max 50

Method: GET

Query Parameters that can be passed to the url are listed below with their description

Filter fields

2.1 Using url query parameters and search strings

Filter by time based fields (timestamp format: yyyy/mm/dd). 

Search query format: /api/1.1/json/tickets/?status=_all&q=""

All of the following fields are to be passed as a search string as shown above.

Filter by custom fields

We can search for tickets by contact and ticket custom fields

Format of specifying custom fields in search

• If the custom field name has only one word <name of the field>: “value” - do not enclose the field name in quotes
• If the custom field name has multiple words “<name of the field>”:”value” - enclose the field name in quotes “field_name”:”value”
• Custom field name and value should be enclosed in quotes separately.
• Name and value should be separated by a colon (:)
• No space after the colon separator
• Field names and values are not case sensitive
• Multiple fields should be separated by space
• For dropdown and multiple choice fields, the values are the option labels
• For multiple choice fields - each option is given in quotes and the options are separated by commas

Examples queries:

• text field: /tickets/?status=_all&q="Enterprise Company Name":"enterprise company"

• dropdown: /tickets/?status=_all&q="Team Name":"arsenal"

• multiple choice: /tickets/?status=_all&q="Country":"finland","germany"

• date field: /tickets/?status=_all&q="Date Field":"08/23/2019"

• number field: /tickets/?status=_all&q="Number Field":"300"

• multiple fields: /tickets/?status=_all&q=Field1:"value1" "Field2":"value 2"

• Filtering with contact and custom fields. Here the name of the custom field is passed within quotations:  /tickets/?status=_all&q=contact:"[email protected]" "Product Name":"Helpdesk"

• Unlike custom fieldsFiltering with system fields like status, requires the name of the field to be passed without quotations:  
  /tickets/?status=_all&q=status:"In+Progress"

• To combine multiple search items for system fields, please build the search query by concatenating each search item with a + 
  
  Eg. Search for status In Progress and New, along with tickets that contain that contain tag routine_checks 
  
  To search statuses, the query string would be,
                     /tickets/?status=_all&q=status:"In+Progress","New"
  
  To search with tags, the query string would be,
                    /tickets/?status=_all&q=tag:"routine_checks"
  
  To combining the two,
                    /tickets/?status=_all&q=tag:"routine_checks"+status:"In+Progress","New"
  
  Other combined examples using status, category IDs and last modified parameters
                    /tickets/?status=_all&category=34&category=5&q=status:"In+Progress","Send+SMS"
                    /tickets/?status=_all&category=34&category=5&q=status:"In+Progress","Send+SMS"+last-modified-on-or-after:"2023/04/15"+last-modified-before:"2023/06/15"
  
  As shown in the above examples multiple search parameters can be combined using the plus operator (+). 

Sorting list of tickets

• Default sorting - last updated based on contact/agent reply in descending order.
• If we search tickets, the sort order is always by relevance and last updated descending.

Other sort options

• categorya - sort by category ascending
• categoryd - sort by category descending
• subjecta - sort by subject in alphabetical order ascending
• subjectd - sort by subject descending
• due - sort by due date
• statusd - sort by status order descending
• statusa - sort by status order ascending
• prioritya - sort by priority order ascending
• priorityd - sort by priority order descending
• updated - sort by last updated (agent / contact reply) descending
• updatea - sort by last updated (agent / contact reply) ascending
• unresponded - unresponded tickets first
• createa - sort by ticket creation date ascending
• created - sort by ticket creation date descending
• assigneea - sort by assignee username ascending
• assigneed - sort by assignee username descending
• last_modifieda - sort by ticket last modified date ascending
• last_modifiedd - sort by ticket last modified date descending
• ticketa - sort by ticket id ascending
• ticketd - sort by ticket id descending
• clienta - sort by contact id ascending
• clientd - sort by contact id ascending

Back to top

3. Ticket detail page

Endpoint - /api/1.1/json/ticket/<ticket_number>/

Note: Ticket ID is a unique identifier for each ticket. It is a combination of category prefix and ticket number. Eg. #HFS00000001. Here 1 is the ticket number and HFS is the category prefix. Ticket number and ticket ID can be obtained from the /tickets/ endpoint from the id and display_id attributes in each item of the data JSON array. 

Ticket ID

Ticket number

Method: GET

Example Response

{

"status": {

"name": "In Progress",

"color": "0066CC",

"order": 2,

"default": false,

"behavior": "pending",

"id**": 2**

},

"first_message": "Example message\n\n",

"last_user_reply_at": "2019-08-13 08:59:11",

"time_spent": 12,

"id": 3,

"messages_count": 2,

"subject": "Example ticket",

"category": {

"prepopulate_cc": "AR",

"description": "Default Category, please edit this.",

"time_spent_mandatory": false,

"public": true,

"id": 1,

"name": "Default Category"

},

"attachments_count": 1,

"last_updated_at": "2019-08-13 08:59:42",

"priority": {

"default": false,

"id": 3,

"name": "High",

"order": 3

},

"last_staff_reply_at": "2019-08-13 08:59:42",

"custom_fields": [

{

"compulsory_on_complete": false,

"name": "Product Color",

"value": "grey",

"value_id": null,

"type": "text",

"id": 1,

"visible_to_staff_only": false

}

],

"sla_breaches": 0,

"merged_tickets": [],

"visible_only_staff": null,

"display_id": "#DC00000003",

"due_date": "2019-08-16",

"tags": "test",

"last_modified": "2019-08-13 08:59:42",

"user": {

"name": "Welcome",

"primary_phone": {

"type": "o",

"number": "02323412",

"id": 1

},

"phones": [

{

"type": "o",

"number": "02323412",

"id": 1

}

],

"created_at": "2019-07-16 11:27:30",

"updated_at": "2019-08-13 08:59:11",

"pending_tickets_count": 3,

"contact_groups": [],

"tickets_count": 3,

"id": 1,

"email": "[email protected]",

"custom_fields": [

{

"name": "Company",

"value": "Changed company",

"value_id": null,

"type": "text",

"id": 2,

"visible_to_staff_only": false

}

]

},

"subscribers": [

{

"first_name": "Admin",

"last_name": "User",

"id": 1,

"email": "[email protected]"

}

],

"unresponded": false,

"created_at": "2019-08-13 08:59:11",

"source": "TKT_CREATION_ADMIN_PANEL",

"assigned_to": {

"name": "Admin User",

"is_account_admin": true,

"email": "[email protected]",

"role": {

"name": "Administrator",

"id": 1

},

"active": true,

"id": 1,

"categories": [

1

],

"permissions": [

"relate_tickets",

"manage_import_assets",

]

},

"updates": [

{

"priority_change": {

"new_name": "High",

"new": 3,

"old": 1,

"old_name": "Medium"

},

"category_change": null,

"custom_field_change": null,

"timestamp": "2019-08-13 08:59:42",

"due_date_change": {

"new": "2019-08-16",

"old": null

},

"by": {

"email": "[email protected]",

"type": "staff",

"id": 1,

"name": "admin"

},

"time_spent": 12,

"update_id": 52,

"message": {

"attachments": [

{

"url": "https://exampleurl.com/attachments/examplefile.jpg",

"id": 22,

"filename": "bicycle.gif"

}

],

"bcc_list": "",

"text": "Attachment added\n\n",

"cc_list": "[email protected]",

"customer_updated": false,

"html": "

 

",

"forward_list": null,

"message_type": null,

"subject": ""

},

"assignee_change": null,

"status_change": {

"new_name": "In Progress",

"new": 2,

"old": 1,

"old_name": "New"

},

"satisfaction_survey": null

}

],

"merged_to": null

}

To obtain a history of changes/updates made on ticket custom fields, add the below url parameter.

Endpoint: /api/1.1/json/ticket/<ticket_number>/?show_cf_changes=true

Method: GET

Example Response:

Without show_cf_changes=true parameter:

With show_cf_changes=true parameter:

Back to top

4. Create Ticket

Using this API endpoint, tickets can be created in all Public categories/Agents and Contacts visible categories

API Endpoint: /api/1.1/json/tickets/

Method:POST

Payload Fields

Example payload

Example 1: With custom fields

{

"name": "james",

"email": "[email protected]",

"category": 1,

"subject": "test ticket",

"text": "example ticket",

"t-cf-3": [1, 2],

"t-cf-1": "text field value",

"t-cf-5": 200,

"t-cf-4": "2019-12-20",

"c-cf-3": 1

}

Example 2: Creating ticket with attachments

Ticket with attachments can be created by passing the payload as multi-part/form type. Here is a sample code in Python. 

import requests

url = "https://<account_name>.happyfox.com/api/1.1/json/tickets/"

payload={'category': '4',

'name': 'Name',

'text': 'Ticket creation message',

'subject': 'Ticket creation subject',

'email': '[email protected]',

't-cf-5': '1',

't-cf-25': '1'}

files=[

('attachments',('Second_screen.png',open('/Users/Laura/Desktop/Second_screen.png','rb'),'image/png'))

]

headers = {

'Authorization': 'Basic <BASIC_AUTH_STRING>'

}

 

response = requests.request("POST", url, headers=headers, data=payload, files=files)

 

print(response.text)

 

# To generate the BASIC_AUTH_STRING, please use the below code snippet

#from requests.auth import _basic_auth_str
#v1_api_key = <API_Key>
#v1_auth_code = <AUTH_Code>
#v1_auth_token = _basic_auth_str(v1_api_key, v1_auth_code)

Successful response data for status 200 is as same as /ticket/

Example failure response (400)

{

"error": [

   {

       "field": "category",

       "errors": [

           "This field is required."

       ]

   }

]

}

{

"error": [

   {

       "field": "t-cf-3",

       "errors": [

           "This field is required"

       ]

   }

]

}

Back to top

5. Create multiple tickets

API Endpoint: /api/1.1/json/tickets/

Method:POST

Payload

• The payload should be a list of ticket payloads.
• For the payload structure of one ticket refer the Create Ticket section
• A maximum of 100 tickets can be created in one request
• Response will be a list of dictionary, indicating successfully created tickets and payloads with validation errors (ref example below)
• success - false indicates that the payload had validation errors
• success - true indicates that the ticket got created successfully

Example response

[

{

   "display_id": "#DC00000011",

   "id": 11,

   "success": true

},

{

   "success": false,

   "error": [

       {

           "field": "category",

           "errors": [

               "This field is required."

           ]

       }

   ]

}

]

Back to top

6. Create an inline attachment to be added to the ticket body

• Use the below endpoint to upload the inline attachment to HappyFox.
• This will generate a temporary url
• Set this temporary url as the value of src property of img tag in the ticket message (html) when creating a ticket

API Endpoint : /api/1.1/json/ticket-inline-attachment

Method: POST

Payload Fields

Example success response (200)

{
“url”: “https://example.happyfox.com/get_hdp_temporarily_attachment/2091/”

}

Please reach out to [email protected] for an example code snippet (mention the coding language) that allows you to create ticket with inline and external attachments.

Back to top

7. Fetch ticket attachment urls

API Endpoints: 

/api/1.1/json/ticket/<ticket_number>/

/api/1.1/json/tickets/

Method: GET

The api response for these endpoints contain a field called attachments_count that contains the total count of attachments in the ticket.
 

{
...

 

...

...

"attachments_count": 1,

"last_updated_at": "2025-07-18 08:09:37",

"priority": {

"default": true,

"id": 5,

"name": "No Priority",

"order": 1

...

...

...

}

The attachment urls are listed in the attachments array for every element present in the updates array for each ticket element in the data field. Each url has an expiry time of 5 mins. The attachment can be accessed directly using the link as the authentication code is embedded in the url for one time use.

Note: attachments, updates and data are payload fields in the api response.

{

...

...

...

"message": {

"attachments": [

{

"url": "https://hf-files-oregon.s3.amazonaws.com/hdpdemofox_email_attachments/2021/07-19/426cd298-63c8-4ff8-8161-93e19545df48/home-2741413_1280_1.png?Signature=jdvU%2Bzx6tQaf%2BdjnkZwi45iRoo0%3D&Expires=1752826500&AWSAccessKeyId=AKIASBRBREIGNJFFU4OL",

"id": 321,

"filename": "home-2741413_1280 (1).png"

}

],

...

...

...

}

8. Adding a Staff update

API Endpoint: /api/1.1/json/ticket/<ticket_number>/staff_update/

Method: POST

Payload Fields

Example payload

{

"staff": 1,

"status": 4,

"html": "

Example reply

",

 

"t-cf-3": [1, 2],

"c-cf-3": 1

}

Refer ticket details page for example response for success

Example failure response

{

"error": {
"t-cf-2": "This field should be filled before marking this ticket as completed"

}

}

 Note: Concurrent/parallel API calls to this endpoint, for any given particular ticket, is not supported.

Back to top

8.1 Updating ticket properties

To update ticket properties such as status, priority, assignee, etc, the /api/1.1/json/ticket/{ticket_number}/staff_update/ endpoint can be used. Following are the options.

API endpoint: /api/1.1/json/ticket/{ticket_number}/staff_update/

HTTP Method: POST

Payload:

{

"staff" : 1,

"priority" : 5,
"assignee": 4,
"status": 3

}

Here, 5 is the ID of the priority, 1 is the ID of the agent/staff making the update, 4 is the ID of the staff/agent to whom the ticket will be assigned and 3 is the status ID

IDs of priority, status, assignee and agent/staff can be fetched by using the following API endpoints. The HTTP method for fetching these would be GET

/api/1.1/json/staff/

/api/1.1/json/priorities/

/api/1.1/json/statuses/

Back to top

9. Adding a Staff private note

API Endpoint: /api/1.1/json/ticket/<ticket_number>/staff_pvtnote/

Method: POST

Payload Fields

Back to top

10. Adding a Contact reply

API Endpoint: </api/1.1/json/ticket/<ticket_number>/user_reply/

Method: POST

Sample payload: 

{ 

"text": "This is a response sent by the user via API",

"cc": "[email protected]",

"bcc" : ""[email protected]",

"user": 27662

}

Payload Fields

Back to top

11.Edit custom fields values of a ticket

API Endpoint:

/api/1.1/json/ticket/<ticket_number>/update_custom_fields/

Method: POST

Payload Fields

Back to top

12. Update tags of a ticket

API Endpoint: /api/1.1/json/ticket/<ticket_number>/update_tags/

Method: POST

Payload Fields

Example Request

{

"add": "test1, example",

"remove": "test",

"staff_id" : 1

}

For a sample success response please refer ticket details response

Back to top

13. Subscribe to ticket (agent only)

API Endpoint: /api/1.1/json/ticket/ticket_number/subscribe/

Method: POST

Payload Fields

Example Request

{

"data": [3, 2],

"staff_id": 1

}

Example success response

{

"message": "Admin Agent, james may, Subscribers added to ticket"

}

Back to top

14. Unsubscribe from ticket (agent only)

API Endpoint: >/api/1.1/json/ticket/<ticket_number>/unsubscribe/

Method: POST

Payload Fields

Example Request

{

"staff_id": 1

}

Example for a successful response

{

"message": "Admin Agent unsubscribed"

}

Back to top

15. Forward ticket to an external email address

API Endpoint : /api/1.1/json/ticket/<ticket_number>/forward/

Method: POST

Payload Fields

Example Request

{

"staff_id": 1,

"subject": "test",

"to": "[email protected], [email protected]"

}

Example successful response

{

"message": "Successfully forwarded the ticket #DC00000004"

}

Back to top

16. Move ticket to another Category

API Endpoint : /api/1.1/json/ticket/<ticket_number>/move/

POST

Payload Fields

Note: The staff used for the above action should have the below permission enabled for their role.

Example Request

{

"staff_id": 1,

"target_category_id": 2,

"move_note": " move note text ",

"assign_to": 2

}

Example success response

{

"status_code": 200,

"message": "moved ticket to Test"

}

Back to top

17. Delete ticket

API Endpoint : /api/1.1/json/ticket/<ticket_number>/delete/

Method: POST

Payload Fields

Example request:

{

"staff_id": 1

}

Example successful response:

{

"deleted_ticket": "#DC00000005"

}

Back to top

18. Create ticket with attachments

 
Sample python script to create a new ticket with attachments is available here
 

Note: Ticket creation with attachments is supported only for HTTP POST, with multi-part/form data payloads.

19. List all ticket custom fields

API Endpoint: /api/1.1/json/ticket_custom_fields/

Method: GET

Example response:

[

{

"name": "City",

"depends_on_choice": null,

"required": false,

"compulsory_on_completed": true,

"choices": null,

"compulsory_on_move": false,

"type": "text",

"id": 1,

"categories": [

{

"category": 1,

"order": 1

}

],

"visible_to_staff_only": false

},

{

"name": "State",

"depends_on_choice": null,

"required": false,

"compulsory_on_completed": false,

"choices": null,

"compulsory_on_move": false,

"type": "text",

"id": 2,

"categories": [

{

"category": 1,

"order": 2

},

{

"category": 2,

"order": 1

},

{

"category": 3,

"order": 1

},

{

"category": 4,

"order": 1

},

{

"category": 5,

"order": 1

}

],

"visible_to_staff_only": false

},

{

"name": "City",

"depends_on_choice": null,

"required": false,

"compulsory_on_completed": false,

"choices": [

{

"text": "Bengaluru",

"id": 4,

"dependant_fields": []

},

{

"text": "Chennai",

"id": 1,

"dependant_fields": []

},

{

"text": "Hyderabad",

"id": 5,

"dependant_fields": []

},

{

"text": "Kochi",

"id": 7,

"dependant_fields": []

},

{

"text": "Mumbai",

"id": 3,

"dependant_fields": []

},

{

"text": "New Delhi",

"id": 2,

"dependant_fields": []

},

{

"text": "Trivandrum",

"id": 6,

"dependant_fields": []

}

],

"compulsory_on_move": false,

"type": "choice",

"id": 3,

"categories": [

{

"category": 1,

"order": 3

},

{

"category": 2,

"order": 2

},

{

"category": 3,

"order": 2

},

{

"category": 4,

"order": 2

},

{

"category": 5,

"order": 2

}

],

"visible_to_staff_only": false

}

]

Back to top

20. Fetch specific JSON fields 

Specific JSON fields from the top-level of the JSON structure can be retrieved using this method. The names of the fields are passed as comma separated values to the fields parameter.

API Endpoint: /api/1.1/json/tickets/?fields=last_user_reply_at,last_staff_reply_at&size=50

HTTP Method: GET

Example: /api/json/1.1/tickets/?fields=id,last_user_reply_at,last_staff_reply_at

Example response:

{
"page_info":
  { "count": 50,
     "last_index": 440,
     "page_count": 9,
     "start_index": 1,
     "end_index": 50

  },

"data":
     [
       {
           "last_staff_reply_at": null,
             "id": 5392,
             "last_user_reply_at": "2025-07-15 17:39:35"
        },
       {
         "last_staff_reply_at": "2025-07-15 09:38:39",
          "id": 5391,
         "last_user_reply_at": "2025-07-10 16:29:48" }
        ,
       {
          "last_staff_reply_at": null,
           "id": 5390,
          "last_user_reply_at": "2025-07-10 16:25:18"
       },

         ...

         ...

         ...

       ]

}