API Documentation
SupportBee's comprehensive API lets you customize every aspect of your customer support workflow.
- Introduction
- Authentication Important
- Fetch Tickets
- Search Tickets
- Create Ticket
- Show Ticket
- Delete Trashed Ticket
- Actions on Tickets
- Fetch Replies for a Ticket
- Create Reply
- Fetching Comments
- Create Comment
- Fetching Users/Groups
- Show User/Group
- Create Users/Groups
- Update a User/Group
- Fetching Members of a Group
- Add a Member to a Group
- Fetching Teams
- Fetching Labels
- Add Label to Ticket
- Create Attachment
- Fetching Snippets
- Create Snippet
- Update Snippet
- Delete Snippet
- Create Filter
- Fetching Emails
- Create Email
- Reports
Introduction
This page documents SupportBee's REST(like) API.
Be sure to read the Authentication section in entirety before exploring available API endpoints.
API endpoint
https://{company}.supportbee.com/
Replace {company}
with the subdomain of your SupportBee desk.
Response format
Response format is JSON
Support
If you've any queries, feel free to reach out to us at [email protected]
Additions and breaking changes to the API are announced in this Google group. If you are using the API, please join the group.
Authentication
All API requests must have a Content-Type
header set to application/json
All API requests must have a Accept
header set to application/json
We use Token Authentication to authenticate api requests. Add the auth_token
query param before sending a HTTP request to an endpoint. For example:
https://{company}.supportbee.com/users?auth_token=your_api_token
To find your API token, click on your profile picture at the top left corner of your SupportBee desk and then click on "API Token".
All API endpoints except the Create Ticket endpoint require authentication.
Response Status Codes
The API will respond with a HTTP 2xx status upon success and a non 2x status upon failure.
Success: 200 Created: 201 Failure: 500 Access Denied: 403 Validation Failure: 400
Date Format
Some of the following API calls accept parameters which represent Date/Time. The date/time should be provided in UTC. The format to specify date is shown in the following examples:
2001-02-15T04:05:06+07:00 20010215T040506+0700 15th Feb 2001 04:05:06 PM 2001-02-15 20010215
Also you can use the date format returned in the results of our API.
Fetch Tickets
GET /tickets
Returns 15 tickets of the company in the order of their last activity. Only tickets that are not archived are returned (Please see optional parameters to get archived tickets).
Status Code
Success: 200
Parameters
per_page (optional)
Specifies the number of tickets to retrieve.
Must be less than 100.
Defaults to 15
page (optional)
Specifies the page of tickets to retrieve.
Defaults to 1
archived (optional)
If true, retrieves only archived tickets.
If false, it does not return any archived tickets.
If any, includes archived tickets in the result.
Defaults to false
spam (optional)
If true, retrieved tickets contain tickets marked as spam.
Defaults to false
trash (optional)
If true, retrieved tickets contain tickets that are trashed.
Defaults to false
replies (optional)
If true, retrieved tickets contain only tickets with replies.
If false, retrieved tickets contain only tickets without replies.
max_replies (optional)
Specifies the number of replies that a ticket must have.
This cannot be used with replies = false
assigned_user (optional)
If me, retrieves only tickets assigned to the current user
If agent_id, retrieves only tickets assigned to the Agent with id agent_id
If any, retrieves tickets that are assigned to any user
If none, retrieves tickets that aren't assigned to any user
assigned_team (optional)
If mine, retrieves only tickets assigned to the teams of the current user
If team_id, retrieves only tickets assigned to the team with id team_id
If none, retrieves tickets that aren't assigned to any team
starred (optional)
If true, retrieves only the starred tickets of the current user
If false, retrieves only the non starred tickets assigned to the current user
label (optional)
Set to label_name, retrieves only the tickets with the label label_name
since (optional)
Can be used to retrieve tickets whose last activity timestamp is greater than the time specified in this parameter. The last activity timestamp of a ticket is updated whenever there is a new reply or a new comment on the ticket. To retrieve tickets sorted by creation time, instead of last activity, send the sort_by
parameter along with the since
parameter.
See here for the accepted date/time formats
until (optional)
Can be used to retrieve tickets whose last activity timestamp is lesser than the time specified in this parameter. The last activity timestamp of a ticket is updated whenever there is a new reply or a new comment on the ticket. To retrieve tickets sorted by creation time, instead of last activity, send the sort_by
parameter along with the until
parameter.
See here for the accepted date/time formats
sort_by (optional)
If last_activity, retrieves tickets sorted by last activity
If creation_time, retrieves tickets sorted by creation time
Defaults to last_activity
requester_emails (optional)
Can be used to filter tickets by requester email addresses.
Accepts a string of comma separated email addresses. For Example: [email protected],[email protected]
total_only (optional)
Can be used in conjunction with any other parameters to return only the total number of tickets.
Accepts any truthy value. For example: total_only=true
Defaults to false.
Example
GET /tickets?per_page=10&assigned_user=none&label=unanswered
{ "total": 1, "current_page": 1, "per_page": 10, "total_pages": 1, "tickets": [{ "id": 1, "subject": "Welcome to SupportBee", "replies_count": 0, "comments_count": 0, "last_activity_at": "2012-01-18T15:17:33Z", "created_at": "2012-01-18T15:17:32Z", "unanswered": true, "archived": false, "spam": false, "starred": false, "summary": "test -- Regards, Agent", "source": { "email": "[email protected]" }, "cc": [], "bcc": [], "labels": [], "requester": { "id":21, "email": "[email protected]", "name": "Requester", "role": "customer", "agent": false, "picture": { "thumb20": "https://secure.gravatar.com/user.png?r=PG&s=20", "thumb24": "https://secure.gravatar.com/user.png?r=PG&s=24", "thumb32": "https://secure.gravatar.com/user.png?r=PG&s=32", "thumb48": "https://secure.gravatar.com/user.png?r=PG&s=48", "thumb64": "https://secure.gravatar.com/user.png?r=PG&s=64", "thumb128": "https://secure.gravatar.com/user.png?r=PG&s=128" } }, "content": { "text": "test\n\n-- \nRegards,\nAgent", "html": "test<br>-- <br>Regards,<div>Agent</div>", "attachments": [{ "id":2, "created_at": "2012-01-18T15:17:33Z", "filename": "logo.jpg", "content_type": "image/jpeg; charset=UTF-8; name=logo.jpg", "url": { "original": "http://company.example.com/attachments/2", "thumb": "http://company.example.com/attachments/2?version=thumb" } }] } }] }
If the ticket is assigned to an agent then the ticket object in the response will contain:
... "current_user_assignee": { "user": { "id": 19, "email": "[email protected]", "name": "Agent,10", "role": "agent", "agent": true, "picture": { "thumb20": "https://secure.gravatar.com/user.png?r=PG&s=20", "thumb24": "https://secure.gravatar.com/user.png?r=PG&s=24", "thumb32": "https://secure.gravatar.com/user.png?r=PG&s=32", "thumb48": "https://secure.gravatar.com/user.png?r=PG&s=48", "thumb64": "https://secure.gravatar.com/user.png?r=PG&s=64", "thumb128": "https://secure.gravatar.com/user.png?r=PG&s=128" } } } ...
If the ticket is assigned to a team then the ticket object in the response will contain:
... "current_team_assignee": { "team": { "id": 1, "name": "Team 1", "picture": { "thumb20": "/images/teams/speech-balloon-orange-g20.png", "thumb24": "/images/teams/speech-balloon-orange-g24.png", "thumb32": "/images/teams/speech-balloon-orange-g32.png", "thumb48": "/images/teams/speech-balloon-orange-g48.png", "thumb256": "/images/teams/speech-balloon-orange-g256.png" } } } ...
Search Tickets
GET /tickets/search
Returns 15 tickets of the company in the order of their last activity matching the search query
Status Codes
Success: 200
Query Missing: 400
Parameters
query
Specifies the query or keywords to searched.
per_page (optional)
Specifies the number of tickets to retrieve.
Must be less than 100.
Defaults to 15
page (optional)
Specifies the page of tickets to retrieve.
Defaults to 1
spam (optional)
If true, retrieved tickets contain tickets marked as spam.
Defaults to false
trash (optional)
If true, retrieved tickets contain tickets marked as trash.
Defaults to false
Example
GET /tickets/search?per_page=10&query=SupportBee
The response is similar to GET /tickets
{ "total": 1, "current_page": 1, "per_page": 10, "total_pages": 1, "tickets": [{ "id": 1, "subject": "Welcome to SupportBee", "replies_count": 0, "comments_count": 0, "last_activity_at": "2012-01-18T15:17:33Z", "created_at": "2012-01-18T15:17:32Z", "unanswered": true, "archived": false, "spam": false, "starred": false, "summary": "test -- Regards, Agent", "source": { "email": "[email protected]" }, "cc": [], "bcc": [], "labels": [], "current_user_assignee": { "user": { "id":19, "email": "[email protected]", "name": "Agent,10", "role": "agent", "agent": true, "picture": { "thumb20": "https://secure.gravatar.com/user.png?r=PG&s=20", "thumb24": "https://secure.gravatar.com/user.png?r=PG&s=24", "thumb32": "https://secure.gravatar.com/user.png?r=PG&s=32", "thumb48": "https://secure.gravatar.com/user.png?r=PG&s=48", "thumb64": "https://secure.gravatar.com/user.png?r=PG&s=64", "thumb128": "https://secure.gravatar.com/user.png?r=PG&s=128" } } }, "requester": { "id":21, "email": "[email protected]", "name": "Requester", "role": "customer", "agent": false, "picture": { "thumb20": "https://secure.gravatar.com/user.png?r=PG&s=20", "thumb24": "https://secure.gravatar.com/user.png?r=PG&s=24", "thumb32": "https://secure.gravatar.com/user.png?r=PG&s=32", "thumb48": "https://secure.gravatar.com/user.png?r=PG&s=48", "thumb64": "https://secure.gravatar.com/user.png?r=PG&s=64", "thumb128": "https://secure.gravatar.com/user.png?r=PG&s=128" } }, "content": { "text": "test\n\n-- \nRegards,\nAgent", "html": "test<br>-- <br>Regards,<div>Agent</div>", "attachments": [{ "id": 2, "created_at": "2012-01-18T15:17:33Z", "filename": "logo.jpg", "content_type": "image/jpeg; charset=UTF-8; name=logo.jpg", "url": { "original": "http://company.example.com/attachments/2", "thumb": "http://company.example.com/attachments/2?version=thumb" } }] } }] }
Create Ticket
POST /tickets
Creates a ticket for the company
This API endpoint doesn't require Authentication and can be used directly in your website's javascript (to create a ticket in your SupportBee desk upon a form submission for example). When Authentication information not provided, the endpoint is rate limited to 5 API requests per hour per IP address to prevent abuse by spammers. When the rate limit is hit, the endpoint will respond with a 429
status code.
If you use the API endpoint in your website's backend, we recommended that you provide Authentication information. When Authentication information is provided, the rate limit is 8 tickets per minute.
Status Codes
Success: 201
Validation Errors: 400
Post Data
This specifies the data in JSON required to create a ticket. A sample JSON request object is:
{ "ticket": { "subject": "Subject", "requester_name": "John Doe", "requester_email": "[email protected]", "cc": [ "Test1 <[email protected]>", "Test2 <[email protected]>" ], "bcc": [ "Test3 <[email protected]>", "Test4 <[email protected]>" ], "content": { "text": "Creating a ticket", "html": "<p>Creating a ticket</p>", "attachment_ids": [1240, 1241] } } }
subject
Specifies the subject of the ticket.
Defaults to "No Subject"
requester_name
Specifies the name of the requester of the ticket.
requester_email
Specifies the email of the requester of the ticket.
Required
cc
or copied_emails (optional)
Specifies the CC email addresses included in the ticket. If there are multiple emails, pass them comma separated.
Up to 25 addresses are allowed.
bcc (optional)
Specifies the BCC email addresses included in the ticket. If there are multiple emails, pass them comma separated.
Up to 25 addresses are allowed.
notify_requester (optional)
If true, a copy of the ticket is sent to the requester and all email addresses in CC and BCC. An auto-response is not sent when this parameter is true (even if it's enabled in the settings). The sender name in this copy is taken from the forwarding address used to create the ticket.
Defaults to false.
content
Specifies the content of the ticket. Either text or html must be present. Please look at the example above.
Required
attachment_ids
Specifies the attachments of the ticket. See Attachment API to upload attachments to SupportBee.
forwarding_address_id
This optional parameter lets you specify the email address/name to be used for sending out replies/auto-responses to the customer. You can find the forwarding address id by editing the desired forwarding address and copying the id from the URL once you are on the edit page (we are working on making this more straight forward).
If you are using a SMTP server for delivering emails, it's important that you send this parameter and use the correct email address to avoid any delivery issues.
Example Response
{ "ticket": { "id": 1, "subject": "Subject", "replies_count": 0, "comments_count": 0, "last_activity_at": "2012-01-18T15:17:33Z", "created_at": "2012-01-18T15:17:32Z", "unanswered": true, "archived": false, "spam": false, "starred": false, "summary": "Subject", "source": { "email": "[email protected]" }, "cc": [{ "id":20, "email": "[email protected]", "name": "Test1", "role": "agent", "agent": true, "picture": { "thumb20": "https://secure.gravatar.com/user.png?r=PG&s=20", "thumb24": "https://secure.gravatar.com/user.png?r=PG&s=24", "thumb32": "https://secure.gravatar.com/user.png?r=PG&s=32", "thumb48": "https://secure.gravatar.com/user.png?r=PG&s=48", "thumb64": "https://secure.gravatar.com/user.png?r=PG&s=64", "thumb128": "https://secure.gravatar.com/user.png?r=PG&s=128" } }, { "id":21, "email": "[email protected]", "name": "Test2", "role": "customer", "agent": false, "picture": { "thumb20": "https://secure.gravatar.com/user.png?r=PG&s=20", "thumb24": "https://secure.gravatar.com/user.png?r=PG&s=24", "thumb32": "https://secure.gravatar.com/user.png?r=PG&s=32", "thumb48": "https://secure.gravatar.com/user.png?r=PG&s=48", "thumb64": "https://secure.gravatar.com/user.png?r=PG&s=64", "thumb128": "https://secure.gravatar.com/user.png?r=PG&s=128" } }], "bcc": [{ "id":22, "email": "[email protected]", "name": "Test3", "role": "customer", "agent": false, "picture": { "thumb20": "https://secure.gravatar.com/user.png?r=PG&s=20", "thumb24": "https://secure.gravatar.com/user.png?r=PG&s=24", "thumb32": "https://secure.gravatar.com/user.png?r=PG&s=32", "thumb48": "https://secure.gravatar.com/user.png?r=PG&s=48", "thumb64": "https://secure.gravatar.com/user.png?r=PG&s=64", "thumb128": "https://secure.gravatar.com/user.png?r=PG&s=128" } }, { "id":23, "email": "[email protected]", "name": null, "role": "customer", "agent": false, "picture": { "thumb20": "https://secure.gravatar.com/user.png?r=PG&s=20", "thumb24": "https://secure.gravatar.com/user.png?r=PG&s=24", "thumb32": "https://secure.gravatar.com/user.png?r=PG&s=32", "thumb48": "https://secure.gravatar.com/user.png?r=PG&s=48", "thumb64": "https://secure.gravatar.com/user.png?r=PG&s=64", "thumb128": "https://secure.gravatar.com/user.png?r=PG&s=128" } }], "labels": [], "current_user_assignee": { "user": { "id": 19, "email": "[email protected]", "name": "John Doe", "agent": true, "picture": { "thumb20": "https://secure.gravatar.com/user.png?r=PG&s=20", "thumb24": "https://secure.gravatar.com/user.png?r=PG&s=24", "thumb32": "https://secure.gravatar.com/user.png?r=PG&s=32", "thumb48": "https://secure.gravatar.com/user.png?r=PG&s=48", "thumb64": "https://secure.gravatar.com/user.png?r=PG&s=64", "thumb128": "https://secure.gravatar.com/user.png?r=PG&s=128" } } }, "requester": { "id": 21, "email": "[email protected]", "name": "Requester", "agent": false, "picture": { "thumb20": "https://secure.gravatar.com/user.png?r=PG&s=20", "thumb24": "https://secure.gravatar.com/user.png?r=PG&s=24", "thumb32": "https://secure.gravatar.com/user.png?r=PG&s=32", "thumb48": "https://secure.gravatar.com/user.png?r=PG&s=48", "thumb64": "https://secure.gravatar.com/user.png?r=PG&s=64", "thumb128": "https://secure.gravatar.com/user.png?r=PG&s=128" } }, "content": { "text": "test\n\n-- \nRegards,\nAgent", "html": "test<br>-- <br>Regards,<div>Agent</div>", "attachments": [{ "id":2, "created_at": "2012-01-18T15:17:33Z", "filename": "logo.jpg", "content_type": "image/jpeg; charset=UTF-8; name=logo.jpg", "url": { "original": "http://company.example.com/attachments/2", "thumb": "http://company.example.com/attachments/2?version=thumb" } }] } }
Get Ticket
GET /tickets/{id}
Retrieves the ticket specified by the id
Status Codes
Success: 200
Not Found: 404
Example
GET /tickets/1
{ "ticket": { "id":1, "subject": "Welcome to SupportBee", "replies_count":0, "comments_count":0, "last_activity_at": "2012-01-18T15:17:33Z", "created_at": "2012-01-18T15:17:32Z", "unanswered": true, "archived": false, "spam": false, "starred": false, "summary": "test -- Regards, Agent", "source": { "email": "[email protected]" } "cc": [], "labels": [], "current_user_assignee": { "user": { "id":19, "email": "[email protected]", "name": "Agent,10", "agent": true, "picture": { "thumb20": "https://secure.gravatar.com/user.png?r=PG&s=20", "thumb24": "https://secure.gravatar.com/user.png?r=PG&s=24", "thumb32": "https://secure.gravatar.com/user.png?r=PG&s=32", "thumb48": "https://secure.gravatar.com/user.png?r=PG&s=48", "thumb64": "https://secure.gravatar.com/user.png?r=PG&s=64", "thumb128": "https://secure.gravatar.com/user.png?r=PG&s=128" } } }, "requester": { "id":21, "email": "[email protected]", "name": "Requester", "agent": false, "picture": { "thumb20": "https://secure.gravatar.com/user.png?r=PG&s=20", "thumb24": "https://secure.gravatar.com/user.png?r=PG&s=24", "thumb32": "https://secure.gravatar.com/user.png?r=PG&s=32", "thumb48": "https://secure.gravatar.com/user.png?r=PG&s=48", "thumb64": "https://secure.gravatar.com/user.png?r=PG&s=64", "thumb128": "https://secure.gravatar.com/user.png?r=PG&s=128" } }, "content": { "text": "test\n\n-- \nRegards,\nAgent", "html": "test<br>-- <br>Regards,<div>Agent</div>", "attachments": [ { "id":2, "created_at": "2012-01-18T15:17:33Z", "filename": "logo.jpg", "content_type": "image/jpeg; charset=UTF-8; name=logo.jpg", "url": { "original": "http://company.example.com/attachments/2", "thumb": "http://company.example.com/attachments/2?version=thumb" } } ] } } }
Delete Trashed Ticket
DELETE /tickets/{id}
Deletes a trashed ticket.
Returns 404 with an error message if {id} is an untrashed ticket.
Only Admins can delete a trashed ticket.
Status Codes
Success: 204
Example
DELETE /tickets/1
Actions On Tickets
Archive a Ticket
POST /tickets/{ticket_id}/archive
Archives an unarchived ticket specified by ticket_id
Status Code
Success: 204
Unarchive Ticket
DELETE /tickets/{ticket_id}/archive
Un-archives an archived ticket specified by ticket_id
Status Code
Success: 204
Mark ticket as Answered
POST /tickets/{ticket_id}/answered
Marks the ticket specified by ticket_id
as answered
Status Code
Success: 204
Mark ticket as Unanswered
DELETE /tickets/{ticket_id}/answered
Marks the ticket specified by ticket_id
as unanswered
Status Code
Success: 204
Assigning a ticket to a User/Team
POST /tickets/{ticket_id}/user_assignment
Assign a ticket to a user
Note: If the ticket is already assigned to a team, then the given user must be a member of that team.
Status Code
Success: 201
Validation Errors: 400
POST Data
{ "user_assignment" : { "user_id": 1 } }
Response
{ "user_assignment": { "id": 2, "created_at": "2012-01-19T16:53:40Z", "ticket": { "id": 1 }, "assignee": { "user": { "id":3, "email": "[email protected]", "name": "Agent,2", "agent": true, "picture": { "thumb20": "https://secure.gravatar.com/avatar/user.png?r=PG&s=20", "thumb24": "https://secure.gravatar.com/avatar/user.png?r=PG&s=24", "thumb32": "https://secure.gravatar.com/avatar/user.png?r=PG&s=32", "thumb48": "https://secure.gravatar.com/avatar/user.png?r=PG&s=48", "thumb64": "https://secure.gravatar.com/avatar/user.png?r=PG&s=64", "thumb128": "https://secure.gravatar.com/avatar/user.png?r=PG&s=128" } } } } }
DELETE /tickets/{ticket_id}/user_assignment
Unassign the ticket from the assigned user
Status Code
Success: 204
POST /tickets/{ticket_id}/team_assignment
Assign a ticket to a team
Note: If the ticket is already assigned to a team and a user, reassigning the ticket to another team will remove the user assignee
POST Data
{ "team_assignment": { "team_id": 1 } }
Response
{ "team_assignment": { "id": 2, "created_at": "2012-01-19T17:29:50Z", "ticket": { "id":1 }, "assignee": { "team": { "id":1, "name": "Team 1", "picture": { "thumb20": "/images/teams/speech-balloon-orange-g20.png", "thumb24": "/images/teams/speech-balloon-orange-g24.png", "thumb32": "/images/teams/speech-balloon-orange-g32.png", "thumb48": "/images/teams/speech-balloon-orange-g48.png", "thumb256": "/images/teams/speech-balloon-orange-g256.png" } } } } }
DELETE /tickets/{ticket_id}/team_assignment
Unassign the ticket from the assigned team
Status Code
Success: 204
Star Ticket
POST /tickets/{ticket_id}/star
Stars an un-starred ticket specified by ticket_id
Status Code
Success: 204
Un-Star Tickets
DELETE /tickets/{ticket_id}/star
Un-stars a starred ticket specified by ticket_id
Status Code
Success: 204
Mark a Ticket as Spam
POST /tickets/{ticket_id}/spam
Spams an un-spammed ticket specified by ticket_id
Status Code
Success: 204
Un-Spamming Tickets
DELETE /tickets/{ticket_id}/spam
Un-spam a spammed ticket specified by ticket_id
Status Code
Success: 204
Trash Ticket
POST /tickets/{ticket_id}/trash
Trashes' an un-trashed ticket specified by ticket_id
Status Code
Success: 204
Un-Trash Ticket
DELETE /tickets/{ticket_id}/trash
Un-trashes' a trashed ticket specified by ticket_id
Status Code
Success: 204
Fetching Replies
GET /tickets/{ticket_id}/replies
Retrieves all the replies of the ticket with id ticket_id
Example
GET /tickets/1/replies
{ "replies": [{ "id":1, "created_at": "2012-01-20T03:45:51Z", "summary": "Reply Content", "cc":[], "bcc":[], "ticket":{ "replies_count":2, "comments_count":0 }, "replier":{ "id":1, "email": "[email protected]", "name": "Agent,1", "agent":true, "picture":{ "thumb20": "https://secure.gravatar.com/avatar/user.png?r=PG&s=20", "thumb24": "https://secure.gravatar.com/avatar/user.png?r=PG&s=24", "thumb32": "https://secure.gravatar.com/avatar/user.png?r=PG&s=32", "thumb48": "https://secure.gravatar.com/avatar/user.png?r=PG&s=48", "thumb64": "https://secure.gravatar.com/avatar/user.png?r=PG&s=64", "thumb128": "https://secure.gravatar.com/avatar/user.png?r=PG&s=128" } }, "content":{ "body": "Reply Content", "html":null, "attachments":[] } }] }
Create Reply
POST /tickets/{ticket_id}/replies
Posts a reply to the ticket with id ticket_id
Status Code
Success: 201
POST Data
{ "reply": { "cc": [], "bcc": [], "content": { "html": "<p>Reply content</p>", "text": "Reply content", "attachment_ids":[] } } }
content
Specifies the content of the reply. Either text or html must be present. Please look at the example above. Take a look at Attachment API to see how to upload attachments to SupportBee.
Required
cc (optional)
Specifies the CC email addresses included in the reply. If there are multiple emails, pass them comma separated.
Up to 25 addresses are allowed.
bcc (optional)
Specifies the BCC email addresses included in the reply. If there are multiple emails, pass them comma separated.
Up to 25 addresses are allowed.
Example
POST /tickets/1/replies
{ "reply":{ "id":3, "created_at": "2012-01-20T04:03:09Z", "summary": "This is the body", "cc": [], "bcc": [], "ticket":{ "replies_count":3, "comments_count":0 }, "replier":{ "id":1, "email": "[email protected]", "name": "Agent,1", "agent":true, "picture":{ "thumb20": "https://secure.gravatar.com/avatar/user.png?r=PG&s=20", "thumb24": "https://secure.gravatar.com/avatar/user.png?r=PG&s=24", "thumb32": "https://secure.gravatar.com/avatar/user.png?r=PG&s=32", "thumb48": "https://secure.gravatar.com/avatar/user.png?r=PG&s=48", "thumb64": "https://secure.gravatar.com/avatar/user.png?r=PG&s=64", "thumb128": "https://secure.gravatar.com/avatar/user.png?r=PG&s=128" } }, "content":{ "text": "Reply Content", "html": "<p>Reply Content</p>", "attachments": [] } } }
Replying on behalf of an agent
Admins can reply on behalf of an agent
Status Code
Success: 201
Forbidden: 403
POST Data
{ "reply": { "on_behalf_of": { "id": 1, "email": "[email protected]" }, "content": { "html": "<p>Reply content</p>", "text": "Reply content", "attachment_ids": [] } } }
on_behalf_of
Specifies the agent on whose behalf the reply is going to be posted. The data must contain "id" or "email".
If both are present, email will be ignored.
Show Reply
GET /tickets/{ticket_id}/replies/{id}
Retrieves the reply for ticket specified by the ticket_id
with id id
Status Codes
Success: 200
Not Found: 404
Example
GET /tickets/1/replies/1
The response is similar to response for creation of a reply.
Fetching Comments
GET /tickets/{ticket_id}/comments
Retrieves all the comments of the ticket with id ticket_id
Example
GET /tickets/1/comments
{ "comments":[{ "id":1, "created_at": "2012-01-20T04:13:26Z", "ticket": { "replies_count": 0, "comments_count": 1 }, "commenter":{ "id":1, "email": "[email protected]", "name": "Agent,1", "agent": true, "picture":{ "thumb20": "https://secure.gravatar.com/avatar/user.png?r=PG&s=20", "thumb24": "https://secure.gravatar.com/avatar/user.png?r=PG&s=24", "thumb32": "https://secure.gravatar.com/avatar/user.png?r=PG&s=32", "thumb48": "https://secure.gravatar.com/avatar/user.png?r=PG&s=48", "thumb64": "https://secure.gravatar.com/avatar/user.png?r=PG&s=64", "thumb128": "https://secure.gravatar.com/avatar/user.png?r=PG&s=128" } }, "content":{ "text": "Reply Content", "html": null, "attachments": [] } }] }
Create Comment
POST /tickets/{ticket_id}/comments
Posts a comment to the ticket with id ticket_id
Status Code
Success: 201
POST Data
{ "comment": { "content": { "html": "<p>Comment content</p>", "text": "Comment content", "attachment_ids": [] } } }
The POST data must contain either "text" or "html". Take a look at Attachment API to see how to upload attachments to SupportBee.
Example
POST /tickets/1/comments
{ "comment": { "id":1, "created_at": "2012-01-20T04:13:26Z", "ticket": { "replies_count": 0, "comments_count": 1 }, "commenter": { "id":1, "email": "[email protected]", "name": "Agent,1", "agent": true, "picture": { "thumb20": "https://secure.gravatar.com/avatar/user.png?r=PG&s=20", "thumb24": "https://secure.gravatar.com/avatar/user.png?r=PG&s=24", "thumb32": "https://secure.gravatar.com/avatar/user.png?r=PG&s=32", "thumb48": "https://secure.gravatar.com/avatar/user.png?r=PG&s=48", "thumb64": "https://secure.gravatar.com/avatar/user.png?r=PG&s=64", "thumb128": "https://secure.gravatar.com/avatar/user.png?r=PG&s=128" } }, "content": { "html": "<p>Comment Content</p>", "text": "Comment Content", "attachments": [] } } }
Fetching Teams
GET /teams
Retrieves all the teams of the company
Parameters
with_users
If true, retrieves only the teams with users.
user
When me, retrives only the teams of the current user. All other
values passed to this parameter is ignored
Example
GET /teams
{ "teams": [{ "id":1, "name": "Team 1", "picture": { "thumb20": "/images/teams/speech-balloon-orange-g20.png", "thumb24": "/images/teams/speech-balloon-orange-g24.png", "thumb32": "/images/teams/speech-balloon-orange-g32.png", "thumb48": "/images/teams/speech-balloon-orange-g48.png", "thumb256": "/images/teams/speech-balloon-orange-g256.png" } }] }
Fetching Labels
GET /labels
Retrieves all the custom labels of a company
Status Codes
Success: 200
Example
GET /labels
{ "labels": [{ "name": "label1", "color": "#ffffff" }] }
Adding Label to a Ticket
POST /tickets/{ticket_id}/labels/{label_name}
Adds the label with {label_name} to the ticket with id ticket_id
Status Codes
Success: 201
Example
POST /tickets/1/labels/imp
{ "label": { "id": 2, "label": "imp", "ticket": 1 } }
Removing Label from a Ticket
DELETE /tickets/{ticket_id}/labels/{label_name}
Status Codes
Success: 204
Example
DELETE /tickets/1/labels/imp
Response is Success with no body.
Fetching Users and Customer Groups
GET /users
Retrieves all users of the company
Status Codes
Success: 200
Parameters
with_invited
If true, returns all the agents, including invited (unconfirmed) agents.
Defaults to false.
with_roles
Specifies the role of the users you want to get. The role must be one of these: admin, agent, collaborator, customer. Several or all of these values can be used.
Defaults to admin,agent,collaborator.
type
Specifies the type of the users you want to get. The type must be one of these: user, customer_group.
Defaults to user.
Examples
GET /users?with_roles=agent
{ "users":[{ "id": 1, "type": "user", "email": "[email protected]", "first_name": "Agent,", "last_name": "1", "name": "Agent, 1", "role": "agent", "agent": true, "two_factor_authentication_enabled": true, "picture": { "thumb20":"https://secure.gravatar.com/avatar/user.png?r=PG&s=20", "thumb24":"https://secure.gravatar.com/avatar/user.png?r=PG&s=24", "thumb32":"https://secure.gravatar.com/avatar/user.png?r=PG&s=32", "thumb48":"https://secure.gravatar.com/avatar/user.png?r=PG&s=48", "thumb64":"https://secure.gravatar.com/avatar/user.png?r=PG&s=64", "thumb128":"https://secure.gravatar.com/avatar/user.png?r=PG&s=128" }, "can_members_access_group_tickets": null, "email_domains": [], "members_count": 0, "active_tickets_count": 0, "teams": [] }] }
GET /users?type=customer_group
{ "users":[{ "id": 2, "type": "customer_group", "email": "[email protected]", "first_name": "Test", "last_name": "Group", "name": "Test Group", "role": "customer", "agent": false, "two_factor_authentication_enabled": false, "picture": { "thumb20":"https://secure.gravatar.com/avatar/user.png?r=PG&s=20", "thumb24":"https://secure.gravatar.com/avatar/user.png?r=PG&s=24", "thumb32":"https://secure.gravatar.com/avatar/user.png?r=PG&s=32", "thumb48":"https://secure.gravatar.com/avatar/user.png?r=PG&s=48", "thumb64":"https://secure.gravatar.com/avatar/user.png?r=PG&s=64", "thumb128":"https://secure.gravatar.com/avatar/user.png?r=PG&s=128" }, "can_members_access_group_tickets": true, "email_domains": [], "members_count": 5, "requested_tickets_count": 0 }] }
Show User
GET /users/{id}
Retrieves the user specified by id
.
Parameters
max_tickets
Specify the maximum number of recent tickets you want to retrieve that this user created. If false returns all tickets.
Defaults to 5.
Example
GET /users/1
{ "user": { "id": 1, "type": "user", "email": "[email protected]", "first_name": "Agent,", "last_name": "1", "name": "Agent, 1", "role": "agent", "agent": true, "two_factor_authentication_enabled": true, "picture": { "thumb20":"https://secure.gravatar.com/avatar/user.png?r=PG&s=20", "thumb24":"https://secure.gravatar.com/avatar/user.png?r=PG&s=24", "thumb32":"https://secure.gravatar.com/avatar/user.png?r=PG&s=32", "thumb48":"https://secure.gravatar.com/avatar/user.png?r=PG&s=48", "thumb64":"https://secure.gravatar.com/avatar/user.png?r=PG&s=64", "thumb128":"https://secure.gravatar.com/avatar/user.png?r=PG&s=128" }, "can_members_access_group_tickets": null, "email_domains": [], "members_count": 0, "active_tickets_count": 0, "teams": [] } }
Create users
POST /users
Creates a user for the company.
Also used to create customer groups, which are treated as users.
Status Codes
Success: 201
Validation Errors: 400
Post Data
This specifies the data in JSON required to create a user. Some sample JSON request objects are
{ "user": { "email": "[email protected]", "name": "Test Name", "role": 10, "team_ids": [], "type": "user", } }
or
{ "user": { "name": "Test Group", "type": "customergroup", "canmembersaccessgroup_tickets": true } }
email
Specifies the email of the user.
Required for standard users. Not allowed for customer groups.
name
Name of the user.
Will be broken down into first and last name at first space.
Required
role
Specifies if the user is a Collaborator, Agent or Admin
* 20 for Admin
* 10 for Agent
* 9 for Collaborator
If not specified a user of role customer is created.
team_ids
Specifies the ids of the teams to which the user will belong.
type
Specifies whether the user is a standard user or a customer group.
* "user" for user
* "customer_group" for customer group
If not specified a user of type user is created.
can_members_access_group_tickets
Only valid if type
is customergroup.
Specifies whether members of the group can access group tickets from the portal.
Can be _true, false, or null.
Defaults to null.
email_domains
Only valid if type
is customergroup_.
Array of email domains. Anyone with email addresses at these domains will automatically join the customer group.
For example:
["examplecorp.com", "othercorp.com"]
Example Response
The response is similar to Show User
response
Update a User
PUT /users/{id}
Updates a user specified by id
.
Cannot update the user whose API Token is being used.
You must use the UI or submit a form to /users/{id}/settings
to do that.
Status Codes
Success: 200
Validation Errors: 400
Post Data
This specifies the data in JSON required to update a user. All fields are optional. Any fields not provided will not be updated. A sample JSON request object is
{ "user": { "email": "[email protected]", "first_name": "Test", "last_name": "Name", "role": 10 } }
email
Specifies the email of the user.
Not allowed if the user is a customer group.
first_name
First name of the user.
last_name
Last name of the user.
role
Specifies if the user is a Collaborator, Agent or Admin
* 20 for Admin
* 10 for Agent
* 9 for Collaborator
team_ids
Specifies the ids of the teams to which the user will belong.
type
Specifies whether the user is a standard user or a customer group.
* "user" for user
* "customer_group" for customer group
can_members_access_group_tickets
Only valid if type
is customergroup.
Specifies whether members of the group can access group tickets from the portal.
Can be _true, false, or null.
email_domains
Only valid if type
is customergroup_.
Array of email domains. Anyone with email addresses at these domains will automatically join the customer group.
For example:
["examplecorp.com", "othercorp.com"]
Example Response
The response is similar to the Show User
response
Fetching Members of a Customer Group
GET /users/{group_id}/members
Retrieves all members of the customer group
Status Codes
Success: 200
Examples
GET /users/2/members
{ "users":[{ "id": 1, "type": "user", "email": "[email protected]", "first_name": "Agent,", "last_name": "1", "name": "Agent, 1", "role": "agent", "agent": true, "two_factor_authentication_enabled": true, "picture": { "thumb20":"https://secure.gravatar.com/avatar/user.png?r=PG&s=20", "thumb24":"https://secure.gravatar.com/avatar/user.png?r=PG&s=24", "thumb32":"https://secure.gravatar.com/avatar/user.png?r=PG&s=32", "thumb48":"https://secure.gravatar.com/avatar/user.png?r=PG&s=48", "thumb64":"https://secure.gravatar.com/avatar/user.png?r=PG&s=64", "thumb128":"https://secure.gravatar.com/avatar/user.png?r=PG&s=128" }, "can_members_access_group_tickets": null, "email_domains": [], "members_count": 0, "active_tickets_count": 0, "teams": [] }] }
Add a Member to a Customer Group
POST /users/{group_id}/members
Adds a user to a customer group as a member.
The customer group is specified by group_id
.
Status Codes
Success: 201
Validation Errors: 400
Post Data
This specifies the data in JSON required to associate a user with a group. A sample JSON request object is
{ "member": { "id": 1 } }
id
Specifies the id of the user to add to the group.
Required
Example Response
The response is similar to Show User
response
{ "member": { "id": 1, "type": "user", "email": "[email protected]", "first_name": "Agent,", "last_name": "1", "name": "Agent, 1", "role": "agent", "agent": true, "two_factor_authentication_enabled": true, "picture": { "thumb20":"https://secure.gravatar.com/avatar/user.png?r=PG&s=20", "thumb24":"https://secure.gravatar.com/avatar/user.png?r=PG&s=24", "thumb32":"https://secure.gravatar.com/avatar/user.png?r=PG&s=32", "thumb48":"https://secure.gravatar.com/avatar/user.png?r=PG&s=48", "thumb64":"https://secure.gravatar.com/avatar/user.png?r=PG&s=64", "thumb128":"https://secure.gravatar.com/avatar/user.png?r=PG&s=128" }, "can_members_access_group_tickets": null, "email_domains": [], "members_count": 0, "active_tickets_count": 0, "teams": [] } }
Create Attachment
An attachment can be created by multipart/form-data
POST request to /attachments
. The name of the POST parameter should be files[]
. This call requires authentication.
Example Code in Ruby
require 'rest_client' RestClient.post( 'https://<your_company_subdomain>.supportbee.com/attachments?auth_token=<user_auth_token>', 'files[]' => File.new('path/to/file') )
Status Code
Success: 201
Example Response
{ "attachment": { "id": 1364, "created_at": "2012-02-17T19:23:18Z", "filename": "wow.jpeg", "content_type": "image/jpeg", "url": { "original": "", "thumb": " " } } }
Fetching Emails
GET /emails
Returns all the emails of the company
Status Codes
Success: 200
Example
GET /emails
{ "forwarding_addresses": [{ "id": 1, "forward_to": "[email protected]", "from": "[email protected]", "name": "Company Inc" }] }
Create Email
POST /emails
Creates an email for the company
Status Codes
Success: 201
Validation Errors: 400
Post Data
This specifies the data in JSON required to create an email. A sample JSON request object is:
{ "forwarding_address": { "name" : "Company Inc", "email": "[email protected]", "filter_spam": true, "use_agent_name": true } }
name (optional)
Specifies the name in replies to customers.
email
Specifies the email you will forward mails from.
Required
filter_spam (optional)
Specifies if a spam filter should run on all incoming emails.
use_agent_name (optional)
Specifies if the agent's name should be used in replies.
Example Response
{ "forwarding_address": { "id": 1, "name": "Company Inc", "company_id": 1, "email": "[email protected]", "filter_spam": false, "forwarding_hash": "rluwmwqanfrivrggh", "global_bcc": null, "created_at": "2015-01-01T17:03:01Z", "updated_at": "2016-08-23T17:03:01Z", "use_agent_name": true } }
Fetching Snippets
GET /snippets
Returns all the snippets of the company
Status Codes
Success: 200
Example
GET /snippets
{ "snippets": [{ "id": 4, "created_at": "2012-01-06T20:18:08Z", "name": "Facebook Link", "tags": "facebook, link", "content":{ "text": "Facebook", "html": "" } }] }
Create Snippet
POST /snippets
Creates a snippet for the company
Status Codes
Success: 201
Validation Errors: 400
Post Data
This specifies the data in JSON required to create a snippet. A sample JSON request object is:
{ "snippet":{ "name": "Facebook Link", "content": { "text": "Facebook", "html": "" }, "tags": "facebook, link" } }
name
Specifies the name for the snippet.
Required
text/html
Specifies the content of the snippet. Either text or html must be present.
tags
Specifies the tags for the snippet.
Example Response
{ "snippet": { "id": 4, "created_at": "2012-01-06T20:18:08Z", "name": "Facebook Link", "tags": "facebook, link", "content": { "text": "Facebook", "html": "" } } }
Update Snippet
PUT /snippet/{id}
Updates a snippet with id {id}
Status Codes
Success: 200
Validation Errors: 400
PUT Data
Same as the POST Data for creating a snippet.
Example Response
Same as the response for creating a snippet.
Delete Snippet
DELETE /snippets/{id}
Deletes a snippet with id: {id}
Status Codes
Success: 204
Example
DELETE /snippets/1
Response is Success with no body.
Creating Filters
A filter is composed of two parts - A rule and a consequence. Rule dictates which tickets are matched and consequence decides what action is taken on the ticket. To create a filter, you need to create a rule, a consequence and then associate them together.
POST /rules
Creates a new rule
Status Codes
Success: 201
Example
POST /rules
{ "rule": { "requester_email": "[email protected]", "delivered_to": "", "subject": "", "body": "" } }
Sample Response
{ "rule": { "id": "5_20130430051603" } }
POST /consequences
Creates a new consequence
Status Codes
Success: 201
Validation Errors: 400
POST Data
This specifies the data in JSON required to create a snippet. A sample JSON request object is:
{ "consequence": { "label": "desktop_uploader", "assign_user": "22102" } }
archive
true
if you want the ticket to be archived
spam
true
if you want the ticket to be marked as spam
trash
true
if you want the ticket to be trashed
label
Name of the label
assign_user
ID of the user that you want the ticket to be assigned to
assign_team
ID of the team that you want the ticket to be assigned to. The ticket can only be assigned to a user or team but not both
Sample Response
{ "consequence": { "id": "5_20130430051603" } }
POST /filters
Finally, to create a filter, use the consequence_id
and rule_id
POST Data
{ "filter": { "consequence_id": "5_20130430051603", "rule_id": "5_20130430051601" } }
Reports
Reports are only available to admins. Please use the API token of an admin when hitting any of the API endpoints below.
GET /reports/avg_first_response_time
Returns data points for average first response time
GET /reports/tickets_count
Returns data points for tickets' count
GET /reports/replies_count
Returns data points for replies' count
Status Codes
Success: 200
Example
GET /reports/avg_first_response_time
{ "data_points":[{ "value":"36200.5", "timestamp":"1360627200" },{ "value":"27300.0", "timestamp":"1360713600" }] }
Both value and timestamp are in seconds. Timestamp is unix time.
Parameters
user (optional)
ID of the agent to filter data points on
team (optional)
ID of the team to filter data points on
label (optional)
Name of the label to filter data points on
since (optional)
Retrieve data points after the timestamp. Data points are returned for a maximum of 30 days' window.
See here for the accepted date/time formats
until (optional)
Retrieve data points before the timestamp. Data points are returned for a maximum of 30 days' window.
See here for the accepted date/time formats