Skip to content

Support tickets API ​

SaaS edition only. Customers open tickets (after the matching help articles) and talk with the team; administrators answer on the support desk with departments, tags, saved replies, internal notes and response-time targets.

All paths are relative to https://your-site.com/api/v1. Send Authorization: Bearer <token> and Accept: application/json; see authentication and errors.

MethodPathWhat it does
GET/tickets/optionsWhat a new ticket can say
GET/ticketsYour tickets
POST/ticketsOpen a ticket
GET/tickets/{ticket}One of your tickets with its messages
PATCH/tickets/{ticket}Close your ticket, or change its details
POST/tickets/{ticket}/messagesReply to your ticket
POST/tickets/{ticket}/ratingRate the answer (1–5 stars)
GET/ticket-files/{attachment}A ticket’s file
GET/desk/ticketsThe support desk queue (administrators)
GET/desk/tickets/{ticket}A ticket on the desk (administrators)
PATCH/desk/tickets/{ticket}Change status, priority, assignee or department (administrators)
DELETE/desk/tickets/{ticket}Delete a ticket with its files (administrators)
POST/desk/tickets/{ticket}/messagesAnswer, or add an internal note (administrators)
PUT/desk/tickets/{ticket}/tagsSet a ticket’s tags (administrators)
POST/desk/tickets/{ticket}/privateReveal the private access details (administrators)
POST/desk/tickets-bulkChange or delete several tickets (administrators)
GET/desk/staffThe support team with roles (administrators)
PUT/desk/staff/{user}Give someone a support role, or take it away (administrators)
GET/desk/catalogDepartments, tags and saved replies (administrators)
POST/desk/departmentsAdd a department (administrators)
PATCH/desk/departments/{department}Change a department (administrators)
DELETE/desk/departments/{department}Delete a department (administrators)
POST/desk/tagsAdd a tag (administrators)
PATCH/desk/tags/{tag}Change a tag (administrators)
DELETE/desk/tags/{tag}Delete a tag (administrators)
POST/desk/saved-repliesAdd a saved reply (administrators)
PATCH/desk/saved-replies/{reply}Change a saved reply (administrators)
DELETE/desk/saved-replies/{reply}Delete a saved reply (administrators)

GET /tickets/options ​

What a new ticket can say

Whether tickets are open, the active departments, the priorities and the file limits.

Responses ​

  • 200 — data:
bash
curl -X GET "https://your-site.com/api/v1/tickets/options" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

GET /tickets ​

Your tickets

Parameters ​

NameInTypeRequiredDescription
statusquerystringOne of: active, closed, all. Default "active".
pagequeryintegerMinimum 1.

Responses ​

  • 200 — data: tickets (id, reference, subject, status, priority, department, last_activity_at…); meta: page, total, open.
bash
curl -X GET "https://your-site.com/api/v1/tickets" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

POST /tickets ​

Open a ticket

Multipart. The team is told by email; you get a receipt.

Request body ​

multipart/form-data, required

FieldTypeRequiredDescription
subjectstringyesAt least 4 characters. At most 200 characters.
bodystringyesAt least 10 characters.
prioritystringOne of: low, normal, high, urgent.
department_idinteger
site_idintegerOne of your sites.
site_urlstring (uri)
session_urlstring (uri)
ccstringUp to 5 addresses, separated by commas.
private_detailsstringEncrypted; erased on close. At most 3000 characters.
files[]string (binary)[]

Responses ​

  • 201 — data: the ticket.
  • 403 — Tickets are closed.
  • 422 —
bash
curl -X POST "https://your-site.com/api/v1/tickets" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -F "subject=…" \
  -F "body=…" \
  -F "priority=…" \
  -F "department_id=…"

GET /tickets/{ticket} ​

One of your tickets with its messages

Parameters ​

NameInTypeRequiredDescription
ticketpathstring (uuid)yes

Responses ​

  • 200 — data: the ticket with messages and files (never the team’s internal notes).
  • 404 — Missing, or another account's.
bash
curl -X GET "https://your-site.com/api/v1/tickets/{ticket}" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

PATCH /tickets/{ticket} ​

Close your ticket, or change its details

An empty private_details erases them.

Parameters ​

NameInTypeRequiredDescription
ticketpathstring (uuid)yes

Request body ​

application/json, required

FieldTypeRequiredDescription
statusstringOne of: closed.
site_urlstring (uri)
session_urlstring (uri)
ccstringUp to 5 addresses, separated by commas.
private_detailsstringEncrypted; erased on close. At most 3000 characters.

Responses ​

  • 200 — data: the ticket.
  • 404 — Missing, or another account's.
  • 422 —
bash
curl -X PATCH "https://your-site.com/api/v1/tickets/{ticket}" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"status":"closed","site_url":"https://example.com","session_url":"https://example.com","cc":"text","private_details":"text"}'

POST /tickets/{ticket}/messages ​

Reply to your ticket

Multipart. A closed ticket opens again.

Parameters ​

NameInTypeRequiredDescription
ticketpathstring (uuid)yes

Request body ​

multipart/form-data, required

FieldTypeRequiredDescription
bodystringyes
files[]string (binary)[]

Responses ​

  • 201 — data: the ticket.
  • 404 — Missing, or another account's.
  • 422 —
bash
curl -X POST "https://your-site.com/api/v1/tickets/{ticket}/messages" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -F "body=…" \
  -F "files[]=…"

POST /tickets/{ticket}/rating ​

Rate the answer (1–5 stars)

Parameters ​

NameInTypeRequiredDescription
ticketpathstring (uuid)yes

Request body ​

application/json, required

FieldTypeRequiredDescription
ratingintegeryesMinimum 1. Maximum 5.
commentstringAt most 1000 characters.

Responses ​

  • 200 — data: the ticket.
  • 422 — Not answered yet, or an invalid rating.
bash
curl -X POST "https://your-site.com/api/v1/tickets/{ticket}/rating" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"rating":1,"comment":"text"}'

GET /ticket-files/{attachment} ​

A ticket’s file

For the ticket’s customer and the team (files of internal notes: the team only).

Parameters ​

NameInTypeRequiredDescription
attachmentpathstring (uuid)yes

Responses ​

  • 200 — The file.
  • 404 — Missing, or another account's.
bash
curl -X GET "https://your-site.com/api/v1/ticket-files/{attachment}" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

GET /desk/tickets ​

The support desk queue (administrators)

Overdue and urgent first. meta: page, counts per view, team, departments, tags, sla.

Parameters ​

NameInTypeRequiredDescription
viewquerystringOne of: active, mine, unassigned, overdue, open, answered, on_hold, closed, all.
priorityquerystringOne of: low, normal, high, urgent.
departmentqueryinteger
tagqueryinteger
qquerystringSubject, #reference, customer or message text. At most 200 characters.
pagequeryintegerMinimum 1.

Responses ​

  • 200 — data: tickets with customer, assignee, due_at, overdue, tags.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 422 —
bash
curl -X GET "https://your-site.com/api/v1/desk/tickets" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

GET /desk/tickets/{ticket} ​

A ticket on the desk (administrators)

With internal notes, activity and the customer’s other tickets; meta: team, departments, tags, saved replies, file limits.

Parameters ​

NameInTypeRequiredDescription
ticketpathstring (uuid)yes

Responses ​

  • 200 — data: the ticket; meta: the desk lists.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 404 — Missing, or another account's.
bash
curl -X GET "https://your-site.com/api/v1/desk/tickets/{ticket}" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

PATCH /desk/tickets/{ticket} ​

Change status, priority, assignee or department (administrators)

Parameters ​

NameInTypeRequiredDescription
ticketpathstring (uuid)yes

Request body ​

application/json, required

FieldTypeRequiredDescription
statusstringOne of: open, answered, on_hold, closed.
prioritystringOne of: low, normal, high, urgent.
assignee_idinteger, nullable
department_idinteger, nullable

Responses ​

  • 200 — data: the ticket.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 422 —
bash
curl -X PATCH "https://your-site.com/api/v1/desk/tickets/{ticket}" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"status":"open","priority":"low","assignee_id":1,"department_id":1}'

DELETE /desk/tickets/{ticket} ​

Delete a ticket with its files (administrators)

Parameters ​

NameInTypeRequiredDescription
ticketpathstring (uuid)yes

Responses ​

  • 204 — Deleted.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
bash
curl -X DELETE "https://your-site.com/api/v1/desk/tickets/{ticket}" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

POST /desk/tickets/{ticket}/messages ​

Answer, or add an internal note (administrators)

Multipart. An answer sets the status (default answered) and assigns an unassigned ticket to you.

Parameters ​

NameInTypeRequiredDescription
ticketpathstring (uuid)yes

Request body ​

multipart/form-data, required

FieldTypeRequiredDescription
bodystringyes
internalboolean
statusstringOne of: open, answered, on_hold, closed.
files[]string (binary)[]

Responses ​

  • 201 — data: the ticket.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 422 —
bash
curl -X POST "https://your-site.com/api/v1/desk/tickets/{ticket}/messages" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -F "body=…" \
  -F "internal=…" \
  -F "status=…" \
  -F "files[]=…"

PUT /desk/tickets/{ticket}/tags ​

Set a ticket’s tags (administrators)

Parameters ​

NameInTypeRequiredDescription
ticketpathstring (uuid)yes

Request body ​

application/json, required

FieldTypeRequiredDescription
tagsinteger[]yes

Responses ​

  • 200 — data: the ticket.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 422 —
bash
curl -X PUT "https://your-site.com/api/v1/desk/tickets/{ticket}/tags" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"tags":[1]}'

POST /desk/tickets/{ticket}/private ​

Reveal the private access details (administrators)

Each reading is logged in the activity.

Parameters ​

NameInTypeRequiredDescription
ticketpathstring (uuid)yes

Responses ​

  • 200 — data:
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 404 — None stored.
bash
curl -X POST "https://your-site.com/api/v1/desk/tickets/{ticket}/private" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

POST /desk/tickets-bulk ​

Change or delete several tickets (administrators)

No emails are sent for bulk changes.

Request body ​

application/json, required

FieldTypeRequiredDescription
idsstring (uuid)[]yesAt most 100 items.
actionstringyesOne of: status, priority, assignee_id, delete.
valuestring | integer, nullable

Responses ​

  • 200 — data:
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 422 —
bash
curl -X POST "https://your-site.com/api/v1/desk/tickets-bulk" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"ids":["text"],"action":"status","value":"text"}'

GET /desk/staff ​

The support team with roles (administrators)

Administrators (role admin), managers and agents, with their open tickets.

Responses ​

  • 200 — data: [{id, name, email, role, open_tickets}]
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
bash
curl -X GET "https://your-site.com/api/v1/desk/staff" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

PUT /desk/staff/{user} ​

Give someone a support role, or take it away (administrators)

Agents see and answer the tickets assigned to them; managers see every ticket and assign them.

Parameters ​

NameInTypeRequiredDescription
userpathintegeryes

Request body ​

application/json, required

FieldTypeRequiredDescription
rolestring, nullableyesOne of: agent, manager, null.

Responses ​

  • 200 — data:
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 422 — An administrator, or an invalid role.
bash
curl -X PUT "https://your-site.com/api/v1/desk/staff/{user}" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"role":"agent"}'

GET /desk/catalog ​

Departments, tags and saved replies (administrators)

Responses ​

  • 200 — data:
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
bash
curl -X GET "https://your-site.com/api/v1/desk/catalog" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

POST /desk/departments ​

Add a department (administrators)

Request body ​

application/json, required

FieldTypeRequiredDescription
namestringAt most 80 characters.
descriptionstring, nullableAt most 200 characters.
sortinteger
is_activeboolean

Responses ​

  • 201 — data: the new item.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 422 —
bash
curl -X POST "https://your-site.com/api/v1/desk/departments" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"text","description":"text","sort":1,"is_active":true}'

PATCH /desk/departments/{department} ​

Change a department (administrators)

Parameters ​

NameInTypeRequiredDescription
departmentpathintegeryes

Request body ​

application/json, required

FieldTypeRequiredDescription
namestringAt most 80 characters.
descriptionstring, nullableAt most 200 characters.
sortinteger
is_activeboolean

Responses ​

  • 200 — data: the item.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 422 —
bash
curl -X PATCH "https://your-site.com/api/v1/desk/departments/{department}" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"text","description":"text","sort":1,"is_active":true}'

DELETE /desk/departments/{department} ​

Delete a department (administrators)

Parameters ​

NameInTypeRequiredDescription
departmentpathintegeryes

Responses ​

  • 204 — Deleted.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
bash
curl -X DELETE "https://your-site.com/api/v1/desk/departments/{department}" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

POST /desk/tags ​

Add a tag (administrators)

Request body ​

application/json, required

FieldTypeRequiredDescription
namestringAt most 40 characters.
colorstringOne of: accent, up, warn, down, gray.

Responses ​

  • 201 — data: the new item.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 422 —
bash
curl -X POST "https://your-site.com/api/v1/desk/tags" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"text","color":"accent"}'

PATCH /desk/tags/{tag} ​

Change a tag (administrators)

Parameters ​

NameInTypeRequiredDescription
tagpathintegeryes

Request body ​

application/json, required

FieldTypeRequiredDescription
namestringAt most 40 characters.
colorstringOne of: accent, up, warn, down, gray.

Responses ​

  • 200 — data: the item.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 422 —
bash
curl -X PATCH "https://your-site.com/api/v1/desk/tags/{tag}" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"text","color":"accent"}'

DELETE /desk/tags/{tag} ​

Delete a tag (administrators)

Parameters ​

NameInTypeRequiredDescription
tagpathintegeryes

Responses ​

  • 204 — Deleted.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
bash
curl -X DELETE "https://your-site.com/api/v1/desk/tags/{tag}" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

POST /desk/saved-replies ​

Add a saved reply (administrators)

Request body ​

application/json, required

FieldTypeRequiredDescription
titlestringAt most 120 characters.
bodystring

Responses ​

  • 201 — data: the new item.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 422 —
bash
curl -X POST "https://your-site.com/api/v1/desk/saved-replies" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"title":"text","body":"text"}'

PATCH /desk/saved-replies/{reply} ​

Change a saved reply (administrators)

Parameters ​

NameInTypeRequiredDescription
replypathintegeryes

Request body ​

application/json, required

FieldTypeRequiredDescription
titlestringAt most 120 characters.
bodystring

Responses ​

  • 200 — data: the item.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 422 —
bash
curl -X PATCH "https://your-site.com/api/v1/desk/saved-replies/{reply}" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"title":"text","body":"text"}'

DELETE /desk/saved-replies/{reply} ​

Delete a saved reply (administrators)

Parameters ​

NameInTypeRequiredDescription
replypathintegeryes

Responses ​

  • 204 — Deleted.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
bash
curl -X DELETE "https://your-site.com/api/v1/desk/saved-replies/{reply}" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

Replora: see what your visitors see.