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

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

If the ticket is assigned to an agent then the ticket object in the response will contain:

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

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:

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

Get Ticket

GET /tickets/{id}

Retrieves the ticket specified by the id

Status Codes

Success: 200

Not Found: 404

Example

GET /tickets/1

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

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

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

Replying on behalf of an agent

Admins can reply on behalf of an agent

Status Code

Success: 201

Forbidden: 403

POST Data

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.

GET /tickets/{ticket_id}/comments

Retrieves all the comments of the ticket with id ticket_id

Example

GET /tickets/1/comments

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

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 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

GET /users?type=customer_group

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

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

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

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

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

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

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 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 Emails

GET /emails

Returns all the emails of the company

Status Codes

Success: 200

Example

GET /emails

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:

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

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

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" } }

Fetching Snippets

GET /snippets

Returns all the snippets of the company

Status Codes

Success: 200

Example

GET /snippets

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:

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

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.

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



