Version 2.4.7.20261116085428 · latest

Tickets tickets

Admins handle user tickets: list, details, replies, internal notes, closing and reopening.

Pick an endpoint to see its example call on the right.

TicketsAuthentication: Admin only8 endpoints

Authentication

Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.

X-API-Key

Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).

Conventions

Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.

Times are RFC 3339 (UTC); amounts are in cents.

Writes return 200/201/204 on success; duplicates of a unique key return 409.

GET/api/v2/ticketsList tickets

Authentication: Admin only

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
statusstring Tab: open, replied or closed; omit for all.
Values ["open","replied","closed"]
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
qstring Search: digits match the ticket number exactly, otherwise a title substring.
urgentboolean Only urgent (true) or only normal (false).
categorystring Filter by category (site, cert, security, l4, billing, other); comma-separated for several.
site_idinteger Filter by the related site or forwarding rule id.
created_fromstring Created at or after.
created_tostring Created before.
POST/api/v2/ticketsCreate a ticket on behalf of a user

Authentication: Admin only

Request body application/json

FieldTypeDescription
bodyRequiredstring Body, at most 2000 characters.
categoryRequiredstring Category: site, cert, security, l4, billing or other.
Values ["site","cert","security","l4","billing","other"]
image_idsinteger[] Image ids uploaded via POST /ticket-images, at most 5, unused and uploaded by the caller.
notifyboolean Whether to notify the user (in-site message plus subscriptions per reminder settings); default true, false creates silently.
rel_idinteger Related object id; 0 for none.
tenant_idRequiredinteger Submitting user (tenant) id.
titleRequiredstring Title, at most 60 characters.
urgentboolean Whether urgent.
GET/api/v2/tickets/{id}Get a ticket

Authentication: Admin only

PATCH/api/v2/tickets/{id}Update ticket urgency or category

Authentication: Admin only

Request body application/json

FieldTypeDescription
categorystring Category: site, cert, security, l4, billing or other.
Values ["site","cert","security","l4","billing","other"]
urgentboolean Whether urgent.
POST/api/v2/tickets/{id}/closeClose a ticket

Authentication: Admin only

Request body application/json

FieldTypeDescription
notestring Optional last staff reply, at most 2000 characters.
notifyboolean Whether to notify the user (in-site message plus subscriptions per reminder settings); default true, false creates silently.
POST/api/v2/tickets/{id}/notesAdd an internal note

Authentication: Admin only

Request body application/json

FieldTypeDescription
bodyRequiredstring Body, at most 2000 characters.
POST/api/v2/tickets/{id}/reopenReopen a ticket

Authentication: Admin only

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

Authentication: Admin only

Request body application/json

FieldTypeDescription
actionstring wait_user, close or none; default wait_user.
Values ["wait_user","close","none"]
bodystring Body, at most 2000 characters.
image_idsinteger[] Image ids uploaded via POST /ticket-images, at most 5, unused and uploaded by the caller.

Tickets object

FieldTypeDescription
actionstring wait_user, close or none; default wait_user.
Values ["wait_user","close","none"]
author_avatar_verinteger The author's avatar version, increases on every upload; omitted when there is no avatar or no author_id.
author_idinteger The author's user id, used to fetch the avatar. Admin side: set on user / staff / note messages; user side: only on the user's own messages (staff and system rows never carry it, so no admin identity leaks).
author_namestring Author name. Admin side: the user or admin name; user side: always the generic support name for staff and system rows.
auto_close_atstring When the ticket will be auto-closed: set only while waiting for the user and auto-close is on (reply time plus the configured days, recomputed after settings change); otherwise empty.
bodyRequiredstring Body, at most 2000 characters.
can_rateboolean User side only: closed or awaiting confirmation, not rated and rating enabled (decides whether the resolve dialog shows the rating section).
can_reopenboolean User side only: closed and still within the reopen window.
categorystring Category: site, cert, security, l4, billing or other.
Values ["site","cert","security","l4","billing","other"]
close_reasonstring Close reason: user, staff or timeout; empty while not closed.
Values ["","user","staff","timeout"]
closed_atstring Time the ticket was closed; empty while open.
created_atstring Created at
created_by_adminboolean Submitted by an admin on the user's behalf; admin side only.
eventstring Event of a system row: urgent, category, closed, reopened, timeout, reply (a reply changed the status; from/to are the old/new status), submitted, submitted_for (submitted by an admin on behalf of the user; to is the user name); empty otherwise.
Values ["","urgent","category","closed","reopened","timeout","reply","submitted","submitted_for"]
fromstring Previous value of a system row.
idinteger Ticket number.
image_idsinteger[] Image ids uploaded via POST /ticket-images, at most 5, unused and uploaded by the caller.
imagesTicketImage[] Attached images.
kindstring user, staff, note (admin only) or system.
Values ["user","staff","note","system"]
last_atstring Time of the last message or status change.
last_kindstring Sender of the last message: user, staff, or empty when none. The user-side list prefixes staff messages with a label.
Values ["","user","staff"]
last_snippetstring Snippet of the last user or staff message (whitespace collapsed, at most 80 characters, ellipsis when cut); internal notes and system rows excluded; empty when none.
messagesTicketMessage[] Messages by id ascending; the user side has no notes.
msg_countinteger Number of user and staff messages (including the initial description; internal notes and system rows excluded).
new_countinteger Messages from the other side after read_pos.
notestring Optional last staff reply, at most 2000 characters.
notifyboolean Whether to notify the user (in-site message plus subscriptions per reminder settings); default true, false creates silently.
ratingstring Rating: good, normal, bad, or empty if not rated.
Values ["","good","normal","bad"]
rating_enabledboolean User side only: the rating switch from ticket settings (when off, the resolve dialog hides the rating area).
rating_notestring Rating note.
read_posinteger This side's read position before opening (a message id).
rel_idinteger Related object id; 0 for none.
rel_namestring Related object name (snapshot at submit time).
rel_typestring Related object type: site, stream or empty.
Values ["","site","stream"]
reopen_untilstring User side only: when closed, the reopen deadline.
statusstring open, replied or closed.
Values ["open","replied","closed"]
tenant_idinteger Submitting user (tenant) id.
titlestring Title, at most 60 characters.
tostring New value of a system row.
unreadinteger Messages from the other side not read yet.
urgentboolean Whether urgent.
userobject Submitting user; admin side only.
user_namestring Submitting user's name; admin side only.

Responses and errors

Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.

Success
{
  "id": 1,
  "name": "example"
}
List
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
Error
{
  "code": "validation_failed",
  "detail": "Invalid request parameters",
  "errors": [
    {
      "code": "required",
      "field": "/name",
      "message": "name is required"
    }
  ],
  "request_id": "0123456789abcdef",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "about:blank"
}
Get started

Try the live demo

Open the live demo, or contact us for a quote and the install command