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, and workspace: true when someone has turned it into a workspace (false before Database Verification has added the column).

So you know which of the endpoints below are worth calling - without calling five of them to find four empty:

"related": {
  "counts": { "notes": 3, "messages": 5, "attachments": 2, "forms": 1,
              "checklists": 0, "watchers": 2, "time_entries": 0 },
  "links": [
    { "type": "task",    "id": 41,  "name": "Order laptop" },
    { "type": "problem", "id": 7,   "reference": "PRB-0007", "name": "VPN drops" },
    { "type": "ticket",  "id": 990, "reference": "TKT-0990", "relation": "duplicate_of" },
    { "type": "external_issue", "provider": "jira", "reference": "OPS-12",
      "url": "https://example.atlassian.net/browse/OPS-12", "status": "In Progress" }
  ]
}

The same related block is on the ticket's Full record webhook (with every count and link - whoever set up the workflow chose to send the record). On GET /tickets it is there only with ?include=related, because a page of 100 tickets would otherwise run 100 sets of counts.

Change the requester (5.2.0, #308): send user_id - a person the key's analyst can see, in the ticket's company. It is always written to the ticket's history, as Requester.

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 }

GET /tickets/{id}, POST /tickets and PATCH /tickets/{id} carry custom_fields: an object keyed by each field's key (shown under each field's name on Tickets → Settings → Custom fields: the name lower-cased with underscores when it was created, e.g. start_date, and it never changes), holding every field this ticket has, null when unanswered. See Custom ticket fields.

"custom_fields": { "start_date": "2026-11-03", "username": "amorgan", "remote_worker": true }

• POST: a field the ticket's type requires when logged must be sent, or the call is refused with 422 missing_field. Fields that do not apply to the type, or a value of the wrong kind, are 422 invalid_field.
• PATCH: only the keys you send are touched; "" clears one (not one required when logging). A field required before closing that is still empty follows the Mandatory fields rule when the PATCH closes the ticket - and filling it in the same PATCH counts.

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" } ] }

Everything attached to the ticket: files on its messages and documents on its notes. Inline pictures inside an email body (a signature's logo) are left out.

{ "data": [
  { "source": "message", "source_id": 512, "id": 88, "kind": "file", "name": "quote.xlsx",
    "content_type": "application/vnd.ms-excel", "size_bytes": 20480, "created_at": "2026-11-13T09:14:03Z" },
  { "source": "note", "source_id": 301, "id": 54, "kind": "file", "name": "diagram.pdf",
    "content_type": "application/pdf", "size_bytes": 1234, "created_at": "2026-11-13T10:02:11Z" }
] }

source_id is the message id from /thread or the note id from /notes. kind is file, link (with its url) or files - a link to a file in the Files module, given without its name because the API does not check Files permissions. This lists what is there; it does not download it.

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.

Analysts watching a ticket are told about it as if it were theirs, through their own notification settings, for the events chosen under Tickets → Settings → General → Watching tickets.

{ "data": [ { "analyst": { "id": 7, "name": "Sam Patel" }, "added_by": { "id": 3, "name": "Ed" }, "added_at": "2026-11-11T10:02:00Z" } ] }

Active analysts only. A deactivated analyst is never listed or notified; whether their watches are kept for if they come back or removed is Tickets → Settings → General → When a watcher is deactivated (5.0.0).

{ "analyst_id": 7 } - or no body for the key's own analyst. 201 when added, 200 when they were already watching (it returns the watcher either way). 422 invalid_field when the analyst does not exist, is inactive, or cannot see the ticket.

Takes them off. 404 when they were not watching.

The forms on a ticket - the ticket twin of the forms a task needs, with the same shapes. Empty while Tickets → Settings → Checklists → Forms on tickets is off. Both need the Tickets and Forms modules switched on.

{ "data": [ { "id": 7, "form_id": 88, "title": "New starter equipment", "required": true, "requirement": "block",
              "submission_id": 512, "submitted_by": "Sam Patel", "submitted_at": "2026-11-11T10:02:00Z",
              "has_draft": false, "revision": 3,
              "answers": [ { "field_id": 901, "question": "Device", "answer": "Laptop", "exception": false } ] } ] }

requirement is block, warn or optional. answers is absent (not empty) unless the key's analyst may read form answers: Forms access, or the Read the form answers on tickets you can see permission.

{ "data": { "901": "Laptop", "902": "2026-11-16" }, "client_reference": "starter-1042", "revision": 3 } - the same validation as the Forms page. 201 with { ticket_id, ticket_form_id, submission_id, revision, replayed: false }; the same client_reference again is 200 with replayed: true and the same submission. revision is optional; sent, a save made since is 409. A requirement that is not on this ticket is 404. The key's analyst needs write access to Forms. Submitting again replaces the earlier submission on the ticket, which is kept in Forms.

The checklists on a ticket, and answering their steps. The same shape as on tasks - since #271 tickets and tasks share one checklist engine, so an integration reads and answers a step the same way on either. Writes go through the same rules as the app: a step that asks for a value needs one, a step that asks for a result is answered rather than ticked, and a fail needs a note.

Each change writes the step's note on the ticket - ✅ Checklist step completed: [New starter] "Asset tag" — Response: AT-4471 (via the API) - as the key's analyst, exactly as a tick in the ticket's panel does (and it fires ticket.note_added the same way).

{ "data": [ {
    "id": 31, "title": "New starter", "template_id": 4, "template_version": 3,
    "closure": "block", "steps_done": 1, "steps_total": 3,
    "steps": [
      { "id": 318, "title": "Asset tag", "description": null, "mandatory": true, "suggested_role": "Desktop",
        "asks_for": "value", "value_prompt": "The laptop's tag", "completed": true, "value": "AT-4471",
        "result": null, "note": null, "completed_by": "Sam Patel", "completed_at": "2026-11-11T10:02:00Z" },
      { "id": 319, "title": "Backups verified", "description": "Check last night's job.", "mandatory": true,
        "suggested_role": null, "asks_for": "result", "value_prompt": null, "completed": false, "value": null,
        "result": null, "note": null, "completed_by": null, "completed_at": null }
    ] } ] }

• asks_for is how the step is answered: tick, value (a tick with a text answer) or result (pass, fail or na).
• closure is what closing / completing does with mandatory steps still outstanding, after the company setting: warn (allowed, and recorded) or block (refused). A step with a result - including a fail - is not outstanding.

Send either completed or result:

Returns the step as it now stands. Errors: 404 - the ticket or step does not exist, is outside the key's companies, or the step is on another ticket; 422 missing_field - a value or a fail's note is missing, or a result step was sent completed; 422 invalid_field - neither or both of completed and result, a completed that is not true / false, or an unknown result.

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.

• 🛠️ Checklists in the REST API - Developer Guide