SupportBee's API Documentation

Introduction

This page documents the REST(like) API for SupportBee. Be sure to read the Authentication section in entirety before exploring available API endpoints.

We announce additions and breaking changes to the API in this Google group. If you are using the API, please subscribe to it.

API endpoint

https://{company}.supportbee.com/

Response format is JSON.

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

Response Status Codes

Success:            200
Created:            201  
Failure:            500  
Access Denied:      403  
Validation Failure: 400

We use Token Authentication to authenticate api requests.

The key to pass the authentication token is auth_token. For example: https://{company}.supportbee.com/users?auth_token=your_api_token

You can find your API token in Settings > API Token screen.

All API calls except Create Ticket require authentication.

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 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: requester_emails=test1@example.com,test2@example.com

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": "test@company.com"
    },
    "cc": [],
    "bcc": [],
    "labels": [],
    "requester": {
      "id":21,
      "email": "person37@example.com",
      "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": "person37@example.com",
    "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": "test@company.com"
    },
    "cc": [],
    "bcc": [],
    "labels": [],
    "current_user_assignee": {
      "user": {
        "id":19,
        "email": "person37@example.com",
        "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": "person37@example.com",
      "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

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": "john@example.com",
    "cc": [
      "Test1 <test1@example.com>",
      "Test2 <test2@example.com>"
    ],
    "bcc": [
      "Test3 <test3@example.com>",
      "Test4 <test4@example.com>"
    ],
    "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).
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": "test@company.com"
    },
    "cc": [{
      "id":20,
      "email": "test1@example.com",
      "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": "test2@example.com",
      "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": "test3@example.com",
      "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": "test4@example.com",
      "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": "john@example.com",
        "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": "person37@example.com",
    "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": "test@company.com"
    }
    "cc": [],
    "labels": [],
      "current_user_assignee": {
        "user": {
          "id":19,
          "email": "person37@example.com",
          "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": "person37@example.com",
      "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": "person4@example.com",
        "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": "person2@example.com",
      "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": "person2@example.com",
      "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": "agent@example.com"
    },
    "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": "person2@example.com",
      "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": "person2@example.com",
      "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 Agents

GET /users

Retrieves all confirmed agents of the company

Status Codes

Success: 200

Parameters

with_invited
If true, returns all the agents including invited(unconfirmed) agents.

Example

GET /users

{
  "users":[{
    "id": 1,
    "email": "person2@example.com",
    "name": "Agent, 1",
    "role": "agent",
    "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"
    }
  }]
}

Show User

GET /users/{id}

Example

GET /users/1

{
  "user": {
    "id": 1,
    "email": "person2@example.com",
    "name": "Agent, 1",
    "role": "agent",
    "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"
    }
  }
}  

Create Agent/Admin

POST /users

Creates a user for the company

Status Codes

Success: 201
Validation Errors: 400

Post Data

This specifies the data in JSON required to create an user. A sample JSON request object is

{
  "user": {
    "email": "test@example.com",
    "first_name": "Test",
    "last_name": "Name",
    "role": 10,
    "team_ids": []
  }
}

email
Specifies the email of the user.
Required

first_name
First name of the user.
Required

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
If not specified an user of role customer is created.

team_ids
Specifies the ids of the teams to which the user will belong.

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

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": "prateek@muziboo.com",
    "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": "rluwmwqanfrivrggh@supportbeemail.com",
    "from": "example@example.com",
    "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": "example@example.com",
    "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": "example@example.com",
    "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