Helpdesk API

Get tickets for a customer (any status unless filtered), newest first. Failure: `customer not found`. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

GET /{api_key}/helpdesk/customer/{cid}/tickets

Parameters

Responses

• 200 — Customer tickets retrieved successfully (failures: HTTP 200 with the ErrorResponse envelope)

Get a specific note. Failure: `note not found`. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

GET /{api_key}/helpdesk/note/{noteid}

Responses

• 200 — Note retrieved successfully (failures: HTTP 200 with the ErrorResponse envelope)

Soft-delete a note (POST or DELETE, same behaviour). Failure: `note not found`. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

DELETE /{api_key}/helpdesk/note/{noteid}/delete

Responses

• 200 — Note deleted successfully (failures: HTTP 200 with the ErrorResponse envelope)

Soft-delete a note (POST or DELETE, same behaviour). Failure: `note not found`. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

POST /{api_key}/helpdesk/note/{noteid}/delete

Responses

• 200 — Note deleted successfully (failures: HTTP 200 with the ErrorResponse envelope)

Update a note (POST or PUT, same behaviour). The body is parsed by the shared extractDataFromRequest() helper: a raw JSON body is normal; a url-encoded JSON string or the legacy `json={...}` / `data={...}` form-encoded wrapper is also accepted. Failures: `note not found`, `no update data provided`. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

POST /{api_key}/helpdesk/note/{noteid}/update

Request body

Responses

• 200 — Note updated successfully (failures: HTTP 200 with the ErrorResponse envelope)

Update a note (POST or PUT, same behaviour). The body is parsed by the shared extractDataFromRequest() helper: a raw JSON body is normal; a url-encoded JSON string or the legacy `json={...}` / `data={...}` form-encoded wrapper is also accepted. Failures: `note not found`, `no update data provided`. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

PUT /{api_key}/helpdesk/note/{noteid}/update

Request body

Responses

• 200 — Note updated successfully (failures: HTTP 200 with the ErrorResponse envelope)

Get helpdesk statistics for the department. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

GET /{api_key}/helpdesk/stats

Responses

• 200 — Statistics retrieved successfully (failures: HTTP 200 with the ErrorResponse envelope)

Get helpdesk statistics for the department, filtered to one assignee. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

GET /{api_key}/helpdesk/stats/{uid}

Responses

• 200 — Statistics retrieved successfully (failures: HTTP 200 with the ErrorResponse envelope)

Create a new helpdesk ticket (status open). The body is parsed by the shared extractDataFromRequest() helper: a raw JSON body is normal; a url-encoded JSON string or the legacy `json={...}` / `data={...}` form-encoded wrapper is also accepted. Failures: `customer id (cid) is required`, `subject is required`, `customer not found`, `failed to create ticket`. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

POST /{api_key}/helpdesk/ticket/create

Request body

Responses

• 200 — Ticket created successfully (failures: HTTP 200 with the ErrorResponse envelope)

Get a ticket with its customer, assigned user, notes, attachments and contacts. Failure: `ticket not found`. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

GET /{api_key}/helpdesk/ticket/{htid}

Responses

• 200 — Ticket retrieved successfully (failures: HTTP 200 with the ErrorResponse envelope)

Assign a ticket to a user. Failures: `ticket not found`, `user not found`. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

POST /{api_key}/helpdesk/ticket/{htid}/assign/{uid}

Responses

• 200 — Ticket assigned successfully (failures: HTTP 200 with the ErrorResponse envelope)

Upload a single attachment to an existing helpdesk ticket. The request must be multipart/form-data with the binary in the `file` field; JSON or base64 bodies are not accepted. Files larger than 10MB are rejected. The new attachment is listed by the ticket detail endpoint and served by the attachment download endpoint.

POST /{api_key}/helpdesk/ticket/{htid}/attachment

Responses

• 200 — Attachment stored successfully, or a JSON error describing why it was rejected

Download a single attachment belonging to a helpdesk ticket. The file content is base64 encoded in the JSON response. Files larger than 10MB are not served.

GET /{api_key}/helpdesk/ticket/{htid}/attachment/{rdid}

Responses

• 200 — Attachment retrieved successfully, or a JSON error describing why it could not be served

Close a helpdesk ticket, optionally adding a note. The body is parsed by the shared extractDataFromRequest() helper: a raw JSON body is normal; a url-encoded JSON string or the legacy `json={...}` / `data={...}` form-encoded wrapper is also accepted. Failures: `ticket not found`, `ticket is already closed`. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

POST /{api_key}/helpdesk/ticket/{htid}/close

Request body

Responses

• 200 — Ticket closed successfully (failures: HTTP 200 with the ErrorResponse envelope)

Merge source tickets into the primary ticket {htid}, mirroring the helpdesk merge screen: each source's notes, helpdesk attachments (every legacy helpdesk module-type spelling; other modules' attachments sharing the numeric id never move) and ticket contacts move to the primary, the source gets an internal `Job Merged with: {htid}` note and is closed (status 1). The primary ticket is otherwise unchanged and no notification is sent. Sources must exist in the API key's department and belong to the primary ticket's customer. Every source is validated before anything is written, so a rejected request makes no changes. The body is parsed by the shared extractDataFromRequest() helper: a raw JSON body is normal; a url-encoded JSON string or the legacy `json={...}` / `data={...}` form-encoded wrapper is also accepted. Failures: `ticket not found` (primary or any source missing or in another department), `ticket_ids must be a non-empty array of ticket ids`, `ticket_ids must only contain positive integer ticket ids`, `ticket_ids contains duplicate ticket id {id}`, `a ticket cannot be merged into itself`, `ticket {id} belongs to a different customer`. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

POST /{api_key}/helpdesk/ticket/{htid}/merge

Request body

Responses

• 200 — Tickets merged successfully (failures: HTTP 200 with the ErrorResponse envelope)

Add a note to a ticket. Optionally stores base64 encoded file attachments against the ticket (up to 10, each at most 10MB decoded) and, with send_notification set, sends the standard helpdesk update email for the note with those files attached. Invalid attachment input is rejected before the note or any attachment is written. The body is parsed by the shared extractDataFromRequest() helper: a raw JSON body is normal; a url-encoded JSON string or the legacy `json={...}` / `data={...}` form-encoded wrapper is also accepted. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

POST /{api_key}/helpdesk/ticket/{htid}/note/add

Request body

Responses

• 200 — Note added successfully, or a failure envelope

Get all notes for a ticket (newest first). Failure: `ticket not found`. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

GET /{api_key}/helpdesk/ticket/{htid}/notes

Responses

• 200 — Notes retrieved successfully (failures: HTTP 200 with the ErrorResponse envelope)

Set ticket priority. Failures: `ticket not found`, `invalid priority (must be 1, 2, 3, 4)`. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

POST /{api_key}/helpdesk/ticket/{htid}/priority/{priority}

Responses

• 200 — Priority updated successfully (failures: HTTP 200 with the ErrorResponse envelope)

Reopen a helpdesk ticket, optionally adding a note. The body is parsed by the shared extractDataFromRequest() helper: a raw JSON body is normal; a url-encoded JSON string or the legacy `json={...}` / `data={...}` form-encoded wrapper is also accepted. Failures: `ticket not found`, `ticket is already open`. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

POST /{api_key}/helpdesk/ticket/{htid}/reopen

Request body

Responses

• 200 — Ticket reopened successfully (failures: HTTP 200 with the ErrorResponse envelope)

Update a helpdesk ticket (POST or PUT, same behaviour). The body is parsed by the shared extractDataFromRequest() helper: a raw JSON body is normal; a url-encoded JSON string or the legacy `json={...}` / `data={...}` form-encoded wrapper is also accepted. Failures: `ticket not found`, `invalid status` (a supplied `status` outside 0-4 rejects the whole request and nothing is written), `no update data provided`. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

POST /{api_key}/helpdesk/ticket/{htid}/update

Request body

Responses

• 200 — Ticket updated successfully (failures: HTTP 200 with the ErrorResponse envelope)

Update a helpdesk ticket (POST or PUT, same behaviour). The body is parsed by the shared extractDataFromRequest() helper: a raw JSON body is normal; a url-encoded JSON string or the legacy `json={...}` / `data={...}` form-encoded wrapper is also accepted. Failures: `ticket not found`, `invalid status` (a supplied `status` outside 0-4 rejects the whole request and nothing is written), `no update data provided`. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

PUT /{api_key}/helpdesk/ticket/{htid}/update

Request body

Responses

• 200 — Ticket updated successfully (failures: HTTP 200 with the ErrorResponse envelope)

Void a helpdesk ticket, optionally adding a note. The body is parsed by the shared extractDataFromRequest() helper: a raw JSON body is normal; a url-encoded JSON string or the legacy `json={...}` / `data={...}` form-encoded wrapper is also accepted. Failures: `ticket not found`, `ticket is already voided`. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

POST /{api_key}/helpdesk/ticket/{htid}/void

Request body

Responses

• 200 — Ticket voided successfully (failures: HTTP 200 with the ErrorResponse envelope)

Get a paginated list of helpdesk tickets (page 1). GET and POST behave identically. Filters are read from $_REQUEST, so they may be sent in the query string (GET) or as query/form-encoded parameters on a POST; a JSON body is not read. Results are scoped to the API key's department. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

GET /{api_key}/helpdesk/tickets

Parameters

Responses

• 200 — Tickets retrieved successfully (failures: HTTP 200 with the ErrorResponse envelope)

Get a paginated list of helpdesk tickets (page 1). GET and POST behave identically. Filters are read from $_REQUEST, so they may be sent in the query string (GET) or as query/form-encoded parameters on a POST; a JSON body is not read. Results are scoped to the API key's department. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

POST /{api_key}/helpdesk/tickets

Parameters

Responses

• 200 — Tickets retrieved successfully (failures: HTTP 200 with the ErrorResponse envelope)

Get all open (status 0) tickets across the department, ordered by priority DESC then lastupdate ASC. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

GET /{api_key}/helpdesk/tickets/outstanding

Responses

• 200 — Outstanding tickets retrieved successfully (failures: HTTP 200 with the ErrorResponse envelope)

Get open tickets assigned to a specific user. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

GET /{api_key}/helpdesk/tickets/outstanding/{uid}

Responses

• 200 — Outstanding tickets retrieved successfully (failures: HTTP 200 with the ErrorResponse envelope)

Get a paginated list of helpdesk tickets. GET and POST behave identically. Filters are read from $_REQUEST, so they may be sent in the query string (GET) or as query/form-encoded parameters on a POST; a JSON body is not read. Results are scoped to the API key's department. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

GET /{api_key}/helpdesk/tickets/page/{page_number}

Parameters

Responses

• 200 — Tickets retrieved successfully (failures: HTTP 200 with the ErrorResponse envelope)

Get a paginated list of helpdesk tickets. GET and POST behave identically. Filters are read from $_REQUEST, so they may be sent in the query string (GET) or as query/form-encoded parameters on a POST; a JSON body is not read. Results are scoped to the API key's department. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

POST /{api_key}/helpdesk/tickets/page/{page_number}

Parameters

Responses

• 200 — Tickets retrieved successfully (failures: HTTP 200 with the ErrorResponse envelope)

Search tickets by subject, company or htid. The body is parsed by the shared extractDataFromRequest() helper: a raw JSON body is normal; a url-encoded JSON string or the legacy `json={...}` / `data={...}` form-encoded wrapper is also accepted. Failure: `search query required` when `query` is empty. An invalid or unknown API key returns HTTP 200 with the `ErrorResponse` envelope `{"success": false, "description": "invalid key"}`; the handler's other failures use the same envelope with a different `description`.

POST /{api_key}/helpdesk/tickets/search

Request body

Responses

• 200 — Search results retrieved successfully (failures: HTTP 200 with the ErrorResponse envelope)