Freshdesk Ticketing

Freshdesk Ticket Management

Overview

Tickets are the core unit of service delivery in Freshdesk. Every customer request, incident, and task flows through the ticketing system. This skill covers listing, getting, searching, creating, updating, replying, adding notes, and reading conversation threads via the Freshdesk REST API v2, surfaced through tools named freshdesk_tickets_<action>.

Anti-triggers

A Freshdesk ticket may carry type: "Incident", which collides with two other meanings of the word. The routing test is what the operator does next: answer a customer under an SLA clock (this skill), page a responder, or approve a remediation on a compromised endpoint.

• An on-call service incident — something is broken and a human must be woken up; the deliverable is acknowledgement and restoration, not a customer reply. Use pagerduty-incidents or rootly-incidents.
• A confirmed security incident — malware or intrusion with a remediation to approve. Use huntress-incidents, or sentinelone-alerts for raw EDR detections. Never draft a customer reply about containment from this skill's data alone.
• Tickets in another helpdesk or PSA — the vocabulary is nearly identical but the field models are not (Freshdesk encodes status and priority as integers; the PSAs use instance-configurable IDs). Use halopsa-tickets, connectwise-psa-tickets, or autotask-tickets.
• Why due_by or fr_due_by has the value it does — deadline computation, business-hours calendars, and breach detection are freshdesk-sla-business-hours; this skill only reads the timestamps.
• Resolving the requester to a person or company — contact lookup, creation, and merge are freshdesk-contacts-companies.

Status, Priority & Source Encodings

Freshdesk encodes these fields as integers in both the API payloads and the search query language.

Status

Priority

Source

(Additional source codes exist for chat, feedback widget, and other channels.)

Key Ticket Fields

Core Fields

Requester & Assignment Fields

SLA Fields

When creating a ticket you must supply subject, description, and a requester (requester_id or email). Status defaults to Open (2) and priority to Low (1) if omitted.

Operations

List Tickets

GET /api/v2/tickets?per_page=100&page=1

Common query params: filter (e.g. new_and_my_open, watching, spam, deleted), updated_since, order_by, order_type. Use include=requester,stats to embed related data.

Get a Single Ticket

GET /api/v2/tickets/{id}?include=conversations,requester,company,stats

include=conversations embeds the reply/note thread; include=stats adds resolution and first-response timestamps useful for SLA checks.

Search Tickets

GET /api/v2/search/tickets?query="status:2 AND priority:4"

The query language wraps the whole expression in double quotes, combines clauses with AND / OR, and supports fields such as status, priority, agent_id, group_id, type, tag, created_at, and updated_at. Search returns up to 30 results per page and a maximum of 10 pages (300 records) — narrow the query when a result set would exceed that.

# Unresolved urgent tickets
"status:2 AND priority:4"

# A group's high/urgent backlog created this month
"group_id:7 AND (priority:3 OR priority:4) AND created_at:>'2024-02-01'"

Create a Ticket

POST /api/v2/tickets

{
  "subject": "Unable to access email - Outlook disconnected",
  "description": "User reports Outlook showing disconnected since 9am. Webmail works fine.",
  "email": "john.smith@acme.com",
  "priority": 3,
  "status": 2,
  "source": 1,
  "group_id": 7
}

Update a Ticket

PUT /api/v2/tickets/{id}

Assign and re-prioritize:

{
  "responder_id": 42,
  "status": 2,
  "priority": 4
}

Resolve:

{
  "status": 4
}

Reply to a Ticket (customer-facing)

POST /api/v2/tickets/{id}/reply

{
  "body": "<p>We've identified the cause and a technician is working on the fix. We'll update you within the hour.</p>"
}

A reply is added to the conversation thread and emailed to the requester.

Add a Note (internal or public)

POST /api/v2/tickets/{id}/notes

Internal note (private to agents):

{
  "body": "<p>Event logs show KB5034441 correlation. Known Outlook cache issue.</p>",
  "private": true
}

Public note (visible to requester):

{
  "body": "<p>Thanks for the additional screenshots — they confirm the cache issue.</p>",
  "private": false
}

Read Conversations

GET /api/v2/tickets/{id}/conversations

Returns the ordered thread of replies and notes. Each entry indicates whether it is private (internal note), incoming (from the requester), or an outgoing agent reply. Use this to reconstruct the full history of a ticket before summarizing or responding.

Common Workflows

Ticket Creation Flow

1. Resolve the requester — look up the contact by email; if none exists, passing email on create will auto-create the contact.
2. Check for duplicates — search recent open tickets for the same requester/subject.
3. Set defaults — status Open (2), priority by impact/urgency.
4. Create — POST /tickets with subject, description, requester.
5. Acknowledge — optionally post a reply confirming receipt.

Triage Workflow

1. Pull the unresolved queue — search "status:2 OR status:3", ordered by priority descending.
2. Identify unassigned tickets — those with no responder_id.
3. Check SLA pressure — get each ticket with include=stats and compare due_by / fr_due_by against now to flag breached and at-risk tickets.
4. Route — set group_id / responder_id by category and skillset.
5. Re-prioritize — bump priority where impact warrants it.
6. Document — add an internal note recording the triage decision.

Escalation

PUT /api/v2/tickets/{id}

{
  "priority": 4,
  "group_id": 9
}

Add an internal note capturing the escalation reason alongside the update.

Error Handling

Best Practices

1. Use integer encodings — never send status/priority as strings.
2. Validate the requester first — confirm the contact or rely on email auto-creation deliberately.
3. Keep internal detail in private notes — public replies stay customer-appropriate.
4. Pull conversations before replying — avoid repeating prior answers.
5. Check due_by / fr_due_by — let SLA deadlines drive triage order.
6. Tag consistently — tags power later search and reporting.

Related Skills

• Freshdesk API Patterns - Auth, pagination, search, rate limits
• Freshdesk Contacts & Companies - Requester resolution
• Freshdesk Knowledge Base - Suggesting KB articles on tickets
• Freshdesk SLA & Business Hours - SLA deadlines and breach detection