Skip to main content

​
Overview

The Tickets API allows you to manage support tickets in Frappe Helpdesk. Tickets are the core entity representing customer support requests.

​
Ticket DocType Fields

The HD Ticket DocType contains the following key fields:
​
name
integer
Auto-incremented ticket ID
​
subject
string
required
Ticket subject/title
​
description
HTML
Detailed description of the ticket
​
raised_by
email
Email address of the person who raised the ticket
​
status
Link
Current ticket status (links to HD Ticket Status)
​
status_category
string
Category of the status (Open, Closed, Paused, etc.)
​
priority
Link
Ticket priority (links to HD Ticket Priority)
​
ticket_type
Link
Type/category of the ticket (links to HD Ticket Type)
​
agent_group
Link
Assigned team (links to HD Team)
​
contact
Link
Associated contact record
​
customer
Link
Associated customer (links to HD Customer)

​
SLA Fields

​
sla
Link
Service Level Agreement applied to this ticket
​
response_by
datetime
Expected first response time based on SLA
​
resolution_by
datetime
Expected resolution time based on SLA
​
agreement_status
Select
SLA status: First Response Due, Resolution Due, Failed, Fulfilled, or Paused

​
Response Metrics

​
first_response_time
duration
Time taken for first agent response
​
first_responded_on
datetime
When the first response was sent
​
avg_response_time
duration
Average response time for this ticket
​
last_agent_response
datetime
Timestamp of last agent response
​
last_customer_response
datetime
Timestamp of last customer response

​
Resolution Fields

​
resolution_details
HTML
Details about how the ticket was resolved
​
resolution_date
datetime
When the ticket was resolved
​
resolution_time
duration
Total time to resolution

​
Feedback

​
feedback_rating
rating
Customer satisfaction rating
​
feedback
Link
Selected feedback option (links to HD Ticket Feedback Option)
​
feedback_extra
text
Additional feedback comments

​
Assign Ticket to Agent

Assigns a ticket to a specific agent.
This endpoint is defined in helpdesk/api/ticket.py:5
def assign_ticket_to_agent(ticket_id, agent_id=None):
    """Assign a ticket to an agent
    
    Args:
        ticket_id: ID of the ticket to assign
        agent_id: ID of the agent. If None, assigns to current user
    
    Returns:
        The updated ticket document
    """
​
ticket_id
string
required
The ID of the ticket to assign
​
agent_id
string
The ID of the agent to assign the ticket to. If not provided, assigns to the current user (frappe.session.user)

​
Response

​
ticket_doc
object
The updated HD Ticket document with the new assignment

​
Error Cases

  • Throws error if agent_id is not a valid HD Agent
  • Throws error with message: “Tickets can only be assigned to agents”

​
Get List Data

Retrieves a list of tickets with flexible filtering, sorting, and column selection.
This endpoint is defined in helpdesk/api/doc.py:18 and works for any DocType
@frappe.whitelist()
def get_list_data(
    doctype: str,
    filters: dict = {},
    default_filters: dict = {},
    order_by: str = "modified desc",
    page_length: int = 20,
    columns: list = [],
    rows: list = [],
    show_customer_portal_fields: bool = False,
    view: dict | None = None,
    is_default: bool = False,
) -> dict:
​
doctype
string
required
The DocType to query (e.g., “HD Ticket”)
​
filters
dict
Filters to apply to the query
​
order_by
string
default:"modified desc"
Field to sort by
​
page_length
integer
default:"20"
Number of records to return
​
columns
list
Column configuration for the list view
​
rows
list
Fields to fetch from the database
​
show_customer_portal_fields
boolean
default:"false"
Whether to filter fields for customer portal view

​
Response

​
data
array
Array of ticket objects matching the query
​
columns
array
Column definitions used in the view
​
rows
array
List of fields included in each record
​
fields
array
Available fields for filtering (only for HD Ticket)
​
total_count
integer
Total number of records matching filters
​
row_count
integer
Number of records in current page

​
Special Filter: @me

The API supports @me in filters which automatically converts to the current user: 
{
  "filters": {
    "_assign": ["like", "%@me%"]
  }
}

​
Get Filterable Fields

Returns the list of fields that can be used for filtering tickets. 
@frappe.whitelist()
def get_filterable_fields(
    doctype: str,
    show_customer_portal_fields: bool = False,
    ignore_team_restrictions: bool = False,
):
​
doctype
string
required
The DocType (e.g., “HD Ticket”)
​
show_customer_portal_fields
boolean
default:"false"
Limit to customer-visible fields

​
Response

Returns an array of field objects:
​
fieldname
string
Internal field name
​
fieldtype
string
Field type (Link, Data, Select, etc.)
​
label
string
Display label for the field
​
options
string
Options for Link/Select fields

​
Get Quick Filters

Returns the fields configured as quick filters for tickets. 
@frappe.whitelist()
def get_quick_filters(doctype: str, show_customer_portal_fields: bool = False):
​
doctype
string
required
The DocType (e.g., “HD Ticket”)

​
Response

Returns an array of quick filter configurations with label, name, type, and options.

​
Remove Assignments

Removes ticket assignments from specified assignees. 
@frappe.whitelist()
def remove_assignments(
    doctype: str,
    name: str | int,
    assignees: list[str],
    ignore_permissions: bool = False,
):
​
doctype
string
required
The DocType (typically “HD Ticket”)
​
name
string
required
The document name/ID
​
assignees
array
required
List of user IDs to remove from assignments
​
ignore_permissions
boolean
default:"false"
Whether to bypass permission checks

​
Example: Creating a Ticket

Using Frappe’s standard document API: 
import frappe

# Create a new ticket
ticket = frappe.get_doc({
    "doctype": "HD Ticket",
    "subject": "Cannot login to my account",
    "description": "<p>I've been getting error messages...</p>",
    "raised_by": "[email protected]",
    "priority": "High",
    "ticket_type": "Technical Issue"
})
ticket.insert()

print(f"Created ticket: {ticket.name}")

​
Example: Querying Tickets

import frappe

# Get all open tickets assigned to current user
tickets = frappe.get_list(
    "HD Ticket",
    filters={
        "status": "Open",
        "_assign": ["like", f"%{frappe.session.user}%"]
    },
    fields=["name", "subject", "priority", "response_by"],
    order_by="response_by asc",
    limit=20
)

​
Standard Frappe API Methods

Since HD Ticket is a standard DocType, you can use all Frappe document APIs:
  • frappe.get_doc("HD Ticket", ticket_id) - Get single ticket
  • frappe.get_list("HD Ticket", filters={...}) - Query tickets
  • frappe.get_value("HD Ticket", ticket_id, fieldname) - Get specific field
  • frappe.db.set_value("HD Ticket", ticket_id, fieldname, value) - Update field
  • frappe.delete_doc("HD Ticket", ticket_id) - Delete ticket

Build docs developers (and LLMs) love

Get started for freeTalk to us