API Documentation

SupportBee's comprehensive API lets you customize every aspect of your customer support workflow.

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

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

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": "
Facebook
"
    }
  }]
}

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": "
Facebook
"
    },
    "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": "
Facebook
"
    }
  }
}

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.

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