Attachments
create
attachments.create
Upload one file and get the id to attach to a reply, comment, draft or ticket
Risk: write
multipart/form-data with the file under files[], which is the field name the route documents. content is base64, with or without a data URI prefix. The answer carries the id to pass in content.attachment_ids on a reply, comment, draft or ticket.
Output
url full type
url full type
Comments
create
comments.create
Add an internal comment to a ticket. Only staff see it; the requester is not notified
Risk: write
comment and answers the created comment. Nothing leaves SupportBee.
content full type
content full type
comment full type
comment full type
list
comments.list
List the internal comments on one ticket
Risk: read
{ comments }. A comment is internal: only staff see it, and the requester is not notified.
Output
comments full type
comments full type
Drafts
create
drafts.create
Save a reply draft on a ticket
Risk: write
draft and answers the created draft. content needs text or html. cc and bcc are comma-separated strings on this route, not the arrays the reply route takes.
content full type
content full type
draft full type
draft full type
delete
drafts.delete
Delete the reply draft on a ticket. The draft text is not returned anywhere afterwards
Risk: destructive · Irreversible
{ ticket_id, deleted: true }. The draft text is gone; nothing returns it.
Output
get
drafts.get
Read the reply draft on a ticket, or a new one quoting the last message when none exists
Risk: read
{ draft }. When no draft exists the route returns a new one quoting the last message, so quote: false gives an empty draft instead. time_zone changes how the quoted date is written.
Output
draft full type
draft full type
update
drafts.update
Replace the reply draft on a ticket
Risk: write
draft wrapper. Answers 404 when no draft exists, so create before updating.
content full type
content full type
draft full type
draft full type
Emails
create
emails.create
Add a forwarding address. SupportBee generates the address that mail is forwarded to
Risk: write
forwarding_address. email is the address you will forward from. filter_spam runs a spam filter on incoming mail, and use_agent_name puts the agent’s name in replies instead of the address name.
Output
forwarding_address full type
forwarding_address full type
list
emails.list
List the forwarding addresses that turn mail into tickets
Risk: read
{ forwarding_addresses }. Each one has the from address a mailbox forwards and the generated forward_to address SupportBee reads. Despite the route name, this manages forwarding, not mail.
Output
forwarding_addresses full type
forwarding_addresses full type
Filters
create
filters.create
Link a rule to a consequence, which is what makes the filter act on matching tickets
Risk: write
{ rule_id, consequence_id, created: true }.
Output
createConsequence
filters.createConsequence
Create the action half of a filter: archive, spam, trash, label or assign
Risk: write
{ consequence: { id } }. It can archive, spam, trash, label or assign, and a consequence assigns a user or a team, not both, so the schema rejects that pair. assign_user and assign_team are strings, not numbers.
Output
consequence full type
consequence full type
createRule
filters.createRule
Create the matching half of a filter. It does nothing until a filter links it to a consequence
Risk: write
{ rule: { id } }. A rule matches on requester_email, delivered_to, subject or body. It does nothing until filters.create links it to a consequence.
Output
rule full type
rule full type
Labels
list
labels.list
List the company label names and colours
Risk: read
{ labels: [{ name, color }] }. A ticket can only be given a label that exists here, so read this before tickets.addLabel.
Output
labels full type
labels full type
Replies
create
replies.create
Send a reply to the requester. The mail leaves SupportBee, so this reaches the real customer
Risk: destructive
reply. content takes text, html or both plus attachment_ids. on_behalf_of lets an admin reply as another agent, and a user trying that gets a 403.
content full type
content full type
on_behalf_of full type
on_behalf_of full type
get
replies.get
Read one reply on one ticket
Risk: read
/tickets/{ticket_id}/replies/{id}, so both ids are needed even though the reply id is unique.
Output
ticket full type
ticket full type
replier full type
replier full type
content full type
content full type
list
replies.list
List the replies on one ticket
Risk: read
{ replies } with no paging. Each reply carries its replier and the ticket’s reply and comment counts.
Output
replies full type
replies full type
Reports
avgFirstResponseTime
reports.avgFirstResponseTime
Daily average first-response time, as string data points with timestamps
Risk: read
{ data_points: [{ value, timestamp }] }. value arrives as a string even when it is a number, so parse it before doing arithmetic. user, team and label narrow the window and since takes any documented date format.
Output
data_points full type
data_points full type
repliesCount
reports.repliesCount
Daily reply count, as string data points with timestamps
Risk: read
{ data_points }, one point per day, with value as a string. A since date sets the start of the window.
Output
data_points full type
data_points full type
ticketsCount
reports.ticketsCount
Daily ticket count, as string data points with timestamps
Risk: read
{ data_points }, one point per day, with value as a string. A since date sets the start of the window.
Output
data_points full type
data_points full type
Snippets
create
snippets.create
Create a reply snippet with plain text or HTML
Risk: write
snippet. content needs text or html; tags is one comma-separated string.
content full type
content full type
snippet full type
snippet full type
delete
snippets.delete
Delete a reply snippet. The text is not returned anywhere afterwards
Risk: destructive · Irreversible
{ id, deleted: true }. The snippet text is gone.
Output
list
snippets.list
List the reply snippets of the desk
Risk: read
{ snippets } with no paging.
Output
snippets full type
snippets full type
update
snippets.update
Change a snippet name, tags or content
Risk: write
snippet wrapper, and the whole record is replaced.
content full type
content full type
snippet full type
snippet full type
Teams
list
teams.list
List the teams of the desk, optionally with their members
Risk: read
{ teams }. with_users: true adds each team’s members, and user narrows to the teams one user belongs to.
Output
teams full type
teams full type
Tickets
addLabel
tickets.addLabel
Add a label to a ticket. The label has to exist on the company first
Risk: write
labels.list first. Answers { label }.
Output
label full type
label full type
archive
tickets.archive
Archive a ticket, which takes it out of the default list. The ticket stays readable
Risk: write
{ id, updated: true }. Archiving takes the ticket out of the default list; it stays readable by id.
Output
assignTeam
tickets.assignTeam
Assign a ticket to a team. Reassigning to another team clears the user assignee
Risk: write
team_assignment and answers that record. Reassigning a ticket that already has a team and a user clears the user assignee.
Output
team_assignment full type
team_assignment full type
asignee full type
asignee full type
assignUser
tickets.assignUser
Assign a ticket to a user. If the ticket is already assigned to a team, the user must be a member of it
Risk: write
user_assignment and answers that record plus an asignee object. If the ticket is already assigned to a team, the user must be a member of that team.
Output
user_assignment full type
user_assignment full type
asignee full type
asignee full type
audit
tickets.audit
Read the audit trail of one ticket, oldest action first
Risk: read
{ audit }, the actions on the ticket oldest first. Each entry has an action, an actor (null for a system action), a severity of info or error, and a happened_at.
Output
audit full type
audit full type
create
tickets.create
Open a ticket for a requester, which emails them when notify_requester is set. This plugin always sends the API token
Risk: destructive
ticket and answers the created ticket. SupportBee also accepts this route without a token, but this plugin always sends the account’s token, so the 8-a-minute token limit applies. content takes text, html or both, plus attachment_ids from attachments.create. notify_requester: true sends a copy and suppresses the auto-response.
content full type
content full type
labels full type
labels full type
requester full type
requester full type
content full type
content full type
current_user_asignee full type
current_user_asignee full type
current_team_asignee full type
current_team_asignee full type
current_user_assignee full type
current_user_assignee full type
current_team_assignee full type
current_team_assignee full type
delete
tickets.delete
Delete a trashed ticket for good. Only an admin can delete, and only a ticket already in the trash
Risk: destructive · Irreversible
{ id, deleted: true }. Only a trashed ticket can be deleted, and only an admin can call it; anything else answers 404. This is the permanent one: tickets.trash is the restorable step before it.
Output
get
tickets.get
Read one ticket with its requester, content and assignment
Risk: read
{ ticket }. The ticket carries its requester, content, labels, and its current user and team assignee. The API spells those two current_user_asignee and current_team_asignee, with one g.
Output
ticket full type
ticket full type
list
tickets.list
List unarchived tickets in last-activity order, filtered by assignee, team, label, requester or date
Risk: read
{ tickets, total, current_page, per_page, total_pages }, 15 a page in last-activity order. Only unarchived tickets are returned unless archived sets another scope. sort_by takes last_activity_at or created_at, and requester_emails takes a comma-separated list. total_only: true returns the count and no tickets.
Output
tickets full type
tickets full type
markAnswered
tickets.markAnswered
Mark a ticket answered without sending a reply, which is how an off-system answer is recorded
Risk: write
markSpam
tickets.markSpam
Mark a ticket as spam
Risk: write
markUnanswered
tickets.markUnanswered
Mark a ticket unanswered so it returns to the open queue
Risk: write
removeLabel
tickets.removeLabel
Remove one label from a ticket
Risk: write
{ ticket_id, label_name, removed: true }. The ticket keeps existing; only the label link goes.
Output
search
tickets.search
Search tickets by text across subjects, bodies and requesters
Risk: read
query, not q. Answers the same wrapper as the list route. spam and trash widen the search to those scopes, and a blank query is rejected before the request is sent.
Output
tickets full type
tickets full type
trash
tickets.trash
Move a ticket to the trash. It stays restorable until an admin deletes it
Risk: write
tickets.untrash until an admin deletes it.
Output
unarchive
tickets.unarchive
Return an archived ticket to the default list
Risk: write
unassignTeam
tickets.unassignTeam
Remove the ticket team assignee
Risk: write
unassignUser
tickets.unassignUser
Remove the ticket assignee
Risk: write
unmarkSpam
tickets.unmarkSpam
Clear the spam flag from a ticket
Risk: write
untrash
tickets.untrash
Restore a trashed ticket
Risk: write
Users
addMember
users.addMember
Add a user to a customer group
Risk: write
member and answers the updated group. There is no route to remove a member; the document has only GET and POST on this path.
Output
user full type
user full type
create
users.create
Create a user or a customer group. A new agent or admin gets an invitation email; a group is a user with type customer_group
Risk: destructive
user. name is the one required field because a customer group has no email. role is 9 for collaborator, 10 for agent and 20 for admin; omit it for a customer. type: 'customer_group' creates a group instead of a user.
Output
user full type
user full type
get
users.get
Read one user or customer group
Risk: read
{ user }. max_tickets caps the tickets listed on the record.
Output
user full type
user full type
list
users.list
List the users and customer groups of the desk, optionally with invited members or roles
Risk: read
{ users }, which are the desk’s users and its customer groups. type: 'customer_group' narrows it to groups, with_invited: true adds members who have not accepted yet, and with_roles takes a comma-separated list.
Output
users full type
users full type
listMembers
users.listMembers
List the members of a customer group
Risk: read
{ users }, the members of one customer group. Answers 404 when the id is not a group.
Output
users full type
users full type
update
users.update
Change a user name, email, role, teams or group settings. The caller cannot update their own account here
Risk: write
user wrapper, and only the fields you pass change. The token’s own user cannot be updated here; SupportBee says to use the UI for that.
Output
user full type
user full type