Tickiti

Show ticket API

This article and the rest of the API documentation in this section are written for a technical audience — integrators and developers connecting external systems to Tickiti. Familiarity with HTTP, REST, JSON and bearer-token authentication is assumed.

The show endpoint returns a single ticket together with its participants, its linked tickets and its full response thread — every reply, public and internal, in the order the staff agent would see them — and the metadata for each response’s attachments. Use it to read a conversation before deciding how to act on it: the natural companion to Reply to ticket, and the detail behind a row from List tickets.

Endpoint

POST /api/v1/tickets/show

Headers

  1. Authorization: Bearer YOUR_TOKEN — required. Token must have the tickets:read ability. A tickets:write token also works (write implies read).
  2. Content-Type: application/json — required. No Idempotency-Key is needed (this is a read).

Body

Required fields:

  1. ticket_number — the 6-digit number of the ticket to read, as a string. Alternatively send ticket_id, the ticket’s internal id. Send exactly one of the two. The ticket must exist and be visible to the acting user.

Optional fields — these keep the payload small when a thread holds long email bodies:

  1. fields — an array choosing which of the heavy response fields to return: any of html, plain_text, attachments. Defaults to all three. A field left out is absent from each response; the metadata fields (id, flags, author, dates, audit, body_chars) are always returned.
  2. max_body_chars — a whole number. Cuts each response’s html and plain_text to this many characters; a field that was cut gains html_truncated: true or plain_text_truncated: true.

Example

curl -X POST https://support.sole-provider.example/api/v1/tickets/show \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ticket_number": "220009"
  }'

A light first read — the text of each response, at most 2,000 characters each, without the HTML:

{
  "ticket_number": "220009",
  "fields": ["plain_text", "attachments"],
  "max_body_chars": 2000
}

Successful response

The ticket header, its participants and linked_tickets, and a responses array (pinned first, then oldest to newest). Each response carries its body as raw stored HTML and as plain text, plus any attachment metadata; download an attachment’s bytes with Download attachment using its id. Numeric ids are returned as strings.

{
  "ok": true,
  "data": {
    "ticket": {
      "id": "1",
      "number": 220009,
      "subject": "Carbon plate cracked on first marathon",
      "status": "open",
      "priority": "20",
      "queue_id": "4",
      "queue": "Returns",
      "originator_email": "[email protected]",
      "originator_name": "Marcus Whitfield",
      "originator_is_staff": false,
      "merged_to_ticket_id": null,
      "assigned_to_email": "[email protected]",
      "assigned_to_name": "Priya Sharma",
      "resolved": null,
      "on_hold_until": null,
      "created_at": "2026-05-01T09:14:02+00:00",
      "updated_at": "2026-05-02T11:30:48+00:00"
    },
    "participants": [
      {
        "email": "[email protected]",
        "name": null,
        "is_staff": false,
        "is_originator": true,
        "is_temporary": false
      },
      {
        "email": "[email protected]",
        "name": "Priya Sharma",
        "is_staff": true,
        "is_originator": false,
        "is_temporary": false
      }
    ],
    "linked_tickets": [
      {
        "link_id": "7",
        "ticket_id": "12",
        "ticket_number": 220031,
        "subject": "Vapor Pro 3 batch QA",
        "status": "open",
        "link_type": "manual",
        "clone_direction": null
      }
    ],
    "responses": [
      {
        "id": "42",
        "is_internal": false,
        "is_pinned": false,
        "staff_response": true,
        "created_by_email": "[email protected]",
        "created_at": "2026-05-02T11:30:48+00:00",
        "updated_at": "2026-05-02T11:30:48+00:00",
        "is_email_sourced": false,
        "audit": { "status": "on-hold", "on_hold_until": "2026-05-08" },
        "is_audit_only": false,
        "body_chars": 29,
        "html": "<p>Your replacement has shipped.</p>",
        "plain_text": "Your replacement has shipped.",
        "attachments": [
          {
            "id": "14494",
            "response_id": "42",
            "name": "UPDD Diag.zip",
            "is_inline": false,
            "sha256": "cc9b8a68...608baf",
            "file_size": 1196962,
            "file_size_formatted": "1.14 MB",
            "extension_rule": "allowed"
          }
        ]
      }
    ]
  }
}

The ticket header

  1. queue_id, queue — the queue the ticket is in, by id and by name.
  2. originator_name, originator_is_staff — who raised the ticket, by name as staff see it (the email when the address has no account), and whether that is a staff member.
  3. assigned_to_email, assigned_to_name — the assignee: a staff email, a team key team:<id>, or Unassigned, with the person’s or team’s name.
  4. merged_to_ticket_id — for a ticket merged into another, the id of the ticket it was merged into; otherwise null.
  5. resolved — the resolution category id, or null.

Participants and linked tickets

Each entry in participants has the email, the staff member’s name (null for non-staff addresses), is_staff, is_originator, and is_temporary — true for a participant added for the time being, such as an inbox manager added when a customer’s mail arrived.

Each entry in linked_tickets describes one link: link_id, the other ticket’s ticket_id, ticket_number, subject and status, and link_type — manual for a link staff made, clone for the link between a ticket and its clone. For a clone link clone_direction is to when this ticket is the source and from when it is the clone; for a manual link it is null. Create and remove links with the Ticket operations API.

Responses

  1. is_internal — a staff-only note that was never sent to the customer.
  2. is_email_sourced — the body arrived as an email (so it may contain Outlook/Word markup) rather than being authored in the in-app editor.
  3. html — the raw stored body: inline images reference Tickiti’s own attachment route, and any cross-ticket “magic” links are left as stored — resolve them yourself if you re-render the HTML.
  4. plain_text — the text form of the body: paragraphs and other blocks separated by blank lines, line breaks kept, HTML entities decoded, and the content of <style>, <script> and <head> removed, so an email body reads as its message.
  5. body_chars — the length of the full plain_text in characters, whatever fields or max_body_chars returned — use it to decide whether to fetch a long body in full.
  6. audit — the ticket changes recorded on this response, or null when it carries none. Only the keys that changed are present: priority, assigned_to, queue_from, queue_to, status, on_hold_until, participants (one +email or -email line per change), subject ("old => new") and other (any further notes, such as a routing decision).
  7. is_audit_only — true for a response that records changes and has no message body, so it is not mistaken for a blank note.
  8. attachments[].extension_rule — how the administrator’s file-type rules treat the file: allowed, review or blocked.

To read one response by id, see the Ticket operations API.

Error responses

  1. 422 validation_failed — neither or both of ticket_number and ticket_id, or an invalid fields value or max_body_chars.
  2. 404 not_found — no ticket has that number or id.
  3. 401 unauthenticated — bad or missing token.
  4. 403 forbidden — token lacks the tickets:read (or tickets:write) ability, the user it acts as lacks access to the ticket, or the token owner is not a staff account.

What happens server-side

  1. Tickiti locates the ticket by ticket_number or ticket_id.
  2. It applies the same access check as the staff interface: the acting user must be the assignee (or a member of the assigned team), a participant, or hold view permission on the ticket’s queue.
  3. It returns the ticket header, participants, linked tickets and the complete response thread — public replies and internal staff notes — with attachment metadata for each response, projected per fields and max_body_chars.