Tickets API

List, read, open, reply to, note on, assign and update support tickets over the REST API, with query filters, fields and file attachments.

The Tickets API lets you list and read support tickets and their threads, and open, reply to, note on, assign and update tickets from your own systems. Use it for reporting, syncing to a data warehouse, or creating tickets from another tool. This article summarizes the endpoints. For full schemas, use your workspace's API reference at /api/v1/docs.

Note: Ticket endpoints need an API key with Conversations access (the read:chat scope to read, write:chat to write), created by a teammate whose role allows the matching ticket permission. Tickets must be turned on in your workspace (the Support module). See the API overview for authentication.

Endpoints

Method	Path	Does
`GET`	`/api/v1/tickets`	List tickets
`POST`	`/api/v1/tickets`	Open a ticket
`GET`	`/api/v1/tickets/{ticketId}`	Get one ticket
`GET`	`/api/v1/tickets/{ticketId}/messages`	Get the ticket's thread
`POST`	`/api/v1/tickets/{ticketId}/reply`	Reply to the requester
`POST`	`/api/v1/tickets/{ticketId}/note`	Add an internal note
`POST`	`/api/v1/tickets/{ticketId}/status`	Change the status
`POST`	`/api/v1/tickets/{ticketId}/priority`	Change the priority
`POST`	`/api/v1/tickets/{ticketId}/assign`	Assign to a teammate or team

List tickets

curl "https://feedback.example.com/api/v1/tickets?statusCategory=open&type=customer" \
  -H "Authorization: Bearer qb_your_api_key"

Query parameter	Values
`type`	`customer`, `back_office` or `tracker`
`ticketTypeId`	A ticket type id
`statusCategory`	`open`, `pending` or `closed`
`stage`	`received`, `in_progress`, `awaiting_requester` or `resolved` (the customer-facing stage)
`requesterPrincipalId`	Only tickets from this requester
`companyId`	Only tickets for this company
`sort`	`recent` (default), `oldest`, `created` or `priority`
`limit`	1 to 100 (default 20)

An API key sees every ticket in the workspace.

Ticket fields

Field	Description
`id`, `number`, `reference`	Ticket id, sequential number and display reference
`type`	`customer`, `back_office` or `tracker`
`title`	Short summary
`status.name`, `status.category`	Status name and its category (`open`, `pending`, `closed`)
`stage`	Customer-facing stage
`priority`	`none`, `low`, `medium`, `high` or `urgent`
`requesterPrincipalId`	The requester, or `null`
`assigneePrincipalId`, `assigneeTeamId`	The assigned teammate and team
`companyId`	The associated company, or `null`
`firstResponseAt`, `dueAt`, `resolvedAt`	Lifecycle timestamps
`createdAt`, `updatedAt`	Standard timestamps
`reopenedCount`	How many times the ticket was reopened

Read a ticket's thread

curl "https://feedback.example.com/api/v1/tickets/ticket_01h455vb4pex5vsknk084sn02q/messages?includeInternal=true" \
  -H "Authorization: Bearer qb_your_api_key"

The thread is returned oldest first. Internal notes are left out unless you pass includeInternal=true. Pass before (a message id from a previous response) to page back through older messages.

Each message has id, ticketId, senderType (agent or visitor), isInternal, authorPrincipalId, authorName, content (Markdown), contentJson, attachments and createdAt.

Open a ticket

curl -X POST https://feedback.example.com/api/v1/tickets \
  -H "Authorization: Bearer qb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "customer",
    "title": "Refund not received",
    "description": "Customer reports a missing refund for order 1234.",
    "priority": "high",
    "requesterPrincipalId": "principal_01h..."
  }'

Field	Notes
`title`	Required, up to 300 characters
`type`	`customer` (default), `back_office` or `tracker`. Can be derived from `ticketTypeId`.
`ticketTypeId`	Optional ticket type
`description`	Optional opening message in Markdown, up to 4,000 characters
`priority`	`none`, `low`, `medium`, `high` or `urgent`
`requesterPrincipalId`, `companyId`	Optional requester and company
`attachments`	Optional files (see below)

A customer ticket created with a requester also gets a linked conversation, so the requester can follow it.

Reply, note, status, priority and assignment

Endpoint	Body
`reply`	`content` (Markdown, up to 4,000 characters), optional `attachments`. Visible to the requester.
`note`	`content`, optional `attachments`. Internal only.
`status`	`statusId` (one of your ticket statuses)
`priority`	`priority`
`assign`	`assigneePrincipalId` and/or `assigneeTeamId` (`null` to unassign)

curl -X POST https://feedback.example.com/api/v1/tickets/ticket_01h.../reply \
  -H "Authorization: Bearer qb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "We have issued your refund." }'

Attach files

Upload the file first with POST /api/v1/files?name=<file name>, sending the raw file as the request body. Then pass the returned id in attachments as [{ "fileId": "file_..." }].