The complete usage guide for the Tickets module of the REST API — every URL, method, parameter and response shape. This mirrors the interactive documentation built into the product (System → API → Documentation), where each endpoint also has a live "Try it" tester.

1. Create a key under System → API (grant it only what it needs — for the example below, just Tickets: create). 2. Copy the key when it's shown — that's the only time you'll see it. 3. Call the API:

curl -X POST "https://your-server/api/v1/tickets" \
  -H "Authorization: Bearer fitsm_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
        "subject": "Disk space low on SQL01",
        "requester_email": "[email protected]",
        "description": "C: drive below 5% free.",
        "priority": "High"
      }'

That's a ticket in the inbox — with the description as its opening message, an audit entry, and any matching workflows already fired. 🎉

Verifies authentication and returns what the key can do — its name, the analyst it acts as, its permission map, company scope and expiry. Any valid key can call it.

{ "data": { "ok": true,
    "key": { "name": "Monitoring", "acts_as": "Administrator",
             "permissions": { "tickets": ["read", "create"] },
             "companies": null, "expires_at": null },
    "server_time": "2026-07-02T22:18:09Z" } }

The API version and the full list of routes.

Trash is excluded unless deleted=true. Results are limited to the key's company scope.

GET /tickets?state=open&priority=High&updated_since=2026-07-01T00:00:00Z&sort=-updated_at&per_page=50

{ "data": [ { "id": 139, "ticket_number": "WBK-509-34271",
              "subject": "API test - printer jam",
              "status":   { "id": 2, "name": "In Progress", "is_closed": false },
              "priority": { "id": 3, "name": "High" },
              "ticket_type": null, "origin": null, "department": null,
              "assigned_analyst": { "id": 1, "name": "Administrator" },
              "requester": { "id": 173, "email": "[email protected]", "name": "Jane Smith" },
              "company":   { "id": 1, "name": "Default" },
              "first_time_fix": null, "it_training_provided": null,
              "created_at": "2026-07-02T22:18:22Z", "updated_at": "2026-07-02T22:18:47Z",
              "closed_at": null, "work_start_at": null, "deleted_at": null } ],
  "meta": { "page": 1, "per_page": 50, "total": 1, "total_pages": 1 } }

Creates a ticket exactly like the UI: the requester is found or created by email, the description becomes the ticket's opening message (so it reads like any other ticket in the inbox), an audit entry is written, and the workflow engine fires ticket.created. Defaults: status Open, priority Normal, unassigned, the key's default company. Returns 201 with the full ticket.

Everything in the list shape plus description_html — the original request body. Every ticket also carries sensitivity: normal or confidential.

Updates any combination of fields, with full UI parity: closing sets closed_at (and reopening clears it), assignment keeps the owner in sync and sends the assignment email, closing sends the closure email and can auto-trigger a CSAT survey, every change lands in the audit log, and the workflow engine fires ticket.status_changed / ticket.priority_changed / ticket.assigned. Returns the updated ticket.

{ "status": "In Progress", "priority": "High", "assigned_analyst_id": 1 }

Soft-deletes (moves to the trash — same as the UI, fully restorable). Already trashed → 409.

Brings a ticket back from the trash and returns it.

All notes, oldest first — is_internal: true marks private analyst notes.

The note is attributed to the analyst the key acts as. Returns 201.

The full conversation — inbound emails / channel messages (channel is email, whatsapp, …) and outbound replies — oldest first, with HTML bodies:

{ "data": [ { "id": 512, "direction": "Inbound", "is_initial": true, "channel": "email",
              "subject": "Printer jam", "from": { "address": "[email protected]", "name": "Jane Smith" },
              "to": "[email protected]", "cc": null,
              "body_preview": "Paper jam error, tray 2.", "body_html": "<p>Paper jam error, tray 2.</p>",
              "received_at": "2026-07-02T09:14:03Z" } ] }

Every audited change with old/new values and who made it:

{ "data": [ { "id": 120, "field": "Status", "old_value": "Open", "new_value": "In Progress",
              "analyst": { "id": 1, "name": "Administrator" },
              "created_at": "2026-07-02T22:18:47Z" } ] }

The live SLA computation — the same engine the UI uses: response/resolution targets from the ticket's priority, elapsed and remaining business minutes against the SLA calendar (with paused statuses honoured), percentages and breach flags.

Active time entries with analyst, minutes, notes and timestamp.

Soft-deletes the entry (same as the UI).

End users who raise tickets (distinct from analysts). POST /tickets creates requesters automatically — these endpoints are for lookups and directory sync.

One requester, plus their ticket counts (within the key's company scope):

{ "data": { "id": 173, "email": "[email protected]", "display_name": "Jane Smith",
            "preferred_name": null, "created_at": "2026-07-02T22:18:22Z",
            "tickets": { "total": 12, "open": 2 } } }

email (required, unique — duplicate → 409), display_name, preferred_name, cost_centre_id (3.5.0 — an active cost centre of their company; no company = the Default company's; 422 otherwise). Returns 201.

Change email (uniqueness enforced), display_name, preferred_name, is_active (3.5.0 - false = marked as left: kept on record, can't sign in to the portal by any route, and an open portal session ends), cost_centre_id (null clears; one they already hold may be kept after it's made inactive). Changing tenant_id while they hold a cost centre needs a cost_centre_id of the new company (or null) in the same request.

Every requester carries cost_centre: {id, code, name} or null (3.5.0).

Everything an integration needs to build valid writes — grab these once and cache them.

A typical "alert → ticket → auto-resolve" round trip using a key with just tickets: read, create, update:

B="https://your-server/api/v1"; K="Authorization: Bearer fitsm_…"

# 1. Alert fires → raise a High ticket
TICKET=$(curl -s -X POST "$B/tickets" -H "$K" -H "Content-Type: application/json" -d '{
  "subject": "[ALERT] SQL01 disk C: below 5%",
  "requester_email": "[email protected]",
  "description": "Datastore free space 4.2%. Threshold 5%.",
  "priority": "High"}' | jq -r '.data.id')

# 2. Alert recovers → find our open ticket and close it with a note*
curl -s -X PATCH "$B/tickets/$TICKET" -H "$K" -H "Content-Type: application/json" \
  -d '{"status": "Closed"}'

* closing via the API sends the closure email and fires your workflows, exactly as if an analyst clicked it. Give the key ticket_notes: create too if you want the recovery details on the ticket.

Under the hood: REST API — How It Works. Keys & permissions: System → API in the product (System module). Live tester: System → API → Documentation.