SupportBee API documentation (1.0.0)
Download OpenAPI specification:
SupportBee's support ticket system enables teams to organize, prioritize and collaborate on customer support emails.
This page documents SupportBee's REST(like) API and how to access SupportBee's functionality programatically.
- 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.
The API will respond with a HTTP 2xx status upon success and a non 2x status upon failure.
| Description | Status Code |
|---|---|
| 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
An attachment can be created by multipart/form-data POST request to /attachments.
Example (using curl):
curl -v -X POST '<company>.supportbee.com/attachments?auth_token=<auth_token>' -F 'files[]=@/location/of/the/file'
Create Attachment
An attachment can be created by multipart/form-data POST request to /attachments.
The name of the POST parameter should be files[].
Authorizations:
Request Body schema: multipart/form-datarequired
| files[] | string <binary> |
Responses
Response samples
- 201
{- "id": 2,
- "created_at": "2001-02-15T04:05:06+07:00",
- "filename": "logo.jpg",
- "content_type": "image/jpeg; charset=UTF-8; name=logo.jpg",
- "url": {
}
}Fetch Comments
Retrieves all the comments on the ticket specified by the ticket ID.
Authorizations:
path Parameters
| id required | integer The tickets ID |
Responses
Response samples
- 200
{- "comments": [
- {
- "id": 1,
- "created_at": "2001-02-15T04:05:06+07:00",
- "ticket": {
- "replies_count": 0,
- "comments_count": 1
}, - "commenter": {
- "id": 1,
- "name": "Agent1",
- "agent": true,
- "picture": {
}
}, - "content": {
- "text": "test\\n\\n-- \\nRegards,\\nAgent",
- "html": "test<br>-- <br>Regards,<div>Agent</div>",
- "attachments": [
- {
- "id": 2,
- "created_at": "2001-02-15T04:05:06+07:00",
- "filename": "logo.jpg",
- "content_type": "image/jpeg; charset=UTF-8; name=logo.jpg",
- "url": {
}
}
]
}
}
]
}
Create Comment
Creates a comment on a ticket specified by the ticket ID.
Authorizations:
path Parameters
| id required | integer The tickets ID |
Request Body schema: application/jsonrequired
A comment for a ticket
object |
Responses
Request samples
- Payload
{- "comment": {
- "content": {
- "text": "test\\n\\n-- \\nRegards,\\nAgent",
- "html": "test<br>-- <br>Regards,<div>Agent</div>",
- "attachments": [
- {
- "id": 2,
- "created_at": "2001-02-15T04:05:06+07:00",
- "filename": "logo.jpg",
- "content_type": "image/jpeg; charset=UTF-8; name=logo.jpg",
- "url": {
}
}
]
}
}
}Response samples
- 201
{- "comment": {
- "id": 1,
- "created_at": "2001-02-15T04:05:06+07:00",
- "ticket": {
- "replies_count": 0,
- "comments_count": 1
}, - "commenter": {
- "id": 1,
- "name": "Agent1",
- "agent": true,
- "picture": {
}
}, - "content": {
- "text": "test\\n\\n-- \\nRegards,\\nAgent",
- "html": "test<br>-- <br>Regards,<div>Agent</div>",
- "attachments": [
- {
- "id": 2,
- "created_at": "2001-02-15T04:05:06+07:00",
- "filename": "logo.jpg",
- "content_type": "image/jpeg; charset=UTF-8; name=logo.jpg",
- "url": {
}
}
]
}
}
}Fetching Users and Customer Groups
Retrieves all users of the company
Authorizations:
query Parameters
| with_invited | boolean Default: false If true, returns all the agents, including invited (unconfirmed) agents. |
| with_roles | string Default: "admin,agent,collaborator" Enum: "admin" "agent" "collaborator" "customer" |
| type | string Default: "user" Enum: "user" "customer_group" |
Responses
Response samples
- 200
{- "users": [
- {
- "id": 1,
- "type": "user",
- "first_name": "Sarah",
- "last_name": "Caring",
- "name": "Sarah Caring",
- "role": "agent",
- "agent": true,
- "two_factor_authentication_enabled": true,
- "picture": {
}, - "can_members_access_group_tickets": null,
- "email_domains": [ ],
- "members_count": 0,
- "active_tickets_count": 0,
- "requested_tickets_count": 0,
- "teams": [ ]
}
]
}Create a user or customer group
Creates a user for the company. Also used to create customer groups, which are treated as users.
Authorizations:
Request Body schema: application/json
object |
Responses
Request samples
- Payload
{- "user": {
- "name": "Test Name",
- "role": 10,
- "team_ids": [ ],
- "type": "user"
}
}Response samples
- 201
{- "user": {
- "id": 1,
- "type": "user",
- "first_name": "Sarah",
- "last_name": "Caring",
- "name": "Sarah Caring",
- "role": "agent",
- "agent": true,
- "two_factor_authentication_enabled": true,
- "picture": {
}, - "can_members_access_group_tickets": null,
- "email_domains": [ ],
- "members_count": 0,
- "active_tickets_count": 0,
- "requested_tickets_count": 0,
- "teams": [ ]
}
}Show User or Customer Group
Retrieves the user specified by id.
Authorizations:
path Parameters
| id required | integer The users ID. |
query Parameters
| max_tickets | integer Default: 5 Specify the maximum number of recent tickets you want to retrieve that this user created. If false returns all tickets. |
Responses
Response samples
- 200
{- "user": {
- "id": 1,
- "type": "user",
- "first_name": "Sarah",
- "last_name": "Caring",
- "name": "Sarah Caring",
- "role": "agent",
- "agent": true,
- "two_factor_authentication_enabled": true,
- "picture": {
}, - "can_members_access_group_tickets": null,
- "email_domains": [ ],
- "members_count": 0,
- "active_tickets_count": 0,
- "requested_tickets_count": 0,
- "teams": [ ]
}
}Fetch Members of a customer group
Retrieves all members of a customer group specified by the customer groups ID.
Authorizations:
path Parameters
| id required | integer The ID of the customer group. |
Responses
Response samples
- 200
{- "users": [
- {
- "id": 1,
- "type": "user",
- "first_name": "Sarah",
- "last_name": "Caring",
- "name": "Sarah Caring",
- "role": "agent",
- "agent": true,
- "two_factor_authentication_enabled": true,
- "picture": {
}, - "can_members_access_group_tickets": null,
- "email_domains": [ ],
- "members_count": 0,
- "active_tickets_count": 0,
- "requested_tickets_count": 0,
- "teams": [ ]
}
]
}Add Member
Add a user to a customer group as a member.
Authorizations:
path Parameters
| id required | integer The ID of the customer group |
Request Body schema: application/json
object |
Responses
Request samples
- Payload
{- "member": {
- "id": 0
}
}Response samples
- 201
{- "user": {
- "id": 1,
- "type": "user",
- "first_name": "Sarah",
- "last_name": "Caring",
- "name": "Sarah Caring",
- "role": "agent",
- "agent": true,
- "two_factor_authentication_enabled": true,
- "picture": {
}, - "can_members_access_group_tickets": null,
- "email_domains": [ ],
- "members_count": 0,
- "active_tickets_count": 0,
- "requested_tickets_count": 0,
- "teams": [ ]
}
}Response samples
- 200
{- "forwarding_addresses": [
]
}Create Email
Creates an email for the company
Authorizations:
Request Body schema: application/jsonrequired
Payload to create a forwarding address
object |
Responses
Request samples
- Payload
{- "forwarding_address": {
- "name": "Company Inc",
- "filter_spam": true,
- "use_agent_name": true
}
}Response samples
- 201
{- "forwarding_address": {
- "id": 1,
- "name": "Company Inc"
}
}A filter is composed of two parts; a rule and a consequence.
- A rule dictates which tickets are matched
- A 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.
Create Consequence
Creates a new consequence
Authorizations:
Request Body schema: application/jsonrequired
Payload to create a consequence.
object |
Responses
Request samples
- Payload
{- "consequence": {
- "archive": false,
- "spam": false,
- "trash": false,
- "label": "desktop_uploader",
- "assign_user": "22102",
- "assign_team": ""
}
}Response samples
- 201
{- "consequence": {
- "id": "5_20130430051603"
}
}Fetch ticket replies
Retrieves all the replies of a ticket specified by it's ID
Authorizations:
path Parameters
| id required | integer The tickets ID |
Responses
Response samples
- 200
{- "replies": [
- {
- "id": 1,
- "created_at": "2001-02-15T04:05:06+07:00",
- "summary": "Reply Content",
- "cc": [ ],
- "bcc": [ ],
- "ticket": {
- "replies_count": 2,
- "comments_count": 0
}, - "replier": {
- "id": 1,
- "name": "Agent Argentus",
- "agent": true,
- "picture": {
}
}, - "content": {
- "body": "Reply Content",
- "html": null,
- "attachments": [ ]
}
}
]
}Create a reply
Post a reply to a ticket specified by it's ID. Admin users can reply on behalf of an agent.
Authorizations:
path Parameters
| id required | integer The tickets ID |
Request Body schema: application/jsonrequired
A reply to a ticket
object |
Responses
Request samples
- Payload
{- "reply": {
- "cc": [ ],
- "bcc": [ ],
- "content": {
- "html": "<p>Reply content</p>",
- "text": "Reply content",
- "attachment_ids": [ ]
}
}
}Response samples
- 201
{- "reply": {
- "id": 1,
- "created_at": "2001-02-15T04:05:06+07:00",
- "summary": "Reply Content",
- "cc": [ ],
- "bcc": [ ],
- "ticket": {
- "replies_count": 2,
- "comments_count": 0
}, - "replier": {
- "id": 1,
- "name": "Agent Argentus",
- "agent": true,
- "picture": {
}
}, - "content": {
- "body": "Reply Content",
- "html": null,
- "attachments": [ ]
}
}
}Show a reply
Retrieves the reply for the ticket specified by the ticket and reply IDs.
Authorizations:
path Parameters
| ticket_id required | integer The tickets ID |
| id required | integer The reply ID |
Responses
Response samples
- 200
{- "id": 1,
- "created_at": "2001-02-15T04:05:06+07:00",
- "summary": "Reply Content",
- "cc": [ ],
- "bcc": [ ],
- "ticket": {
- "replies_count": 2,
- "comments_count": 0
}, - "replier": {
- "id": 1,
- "name": "Agent Argentus",
- "agent": true,
- "picture": {
}
}, - "content": {
- "body": "Reply Content",
- "html": null,
- "attachments": [ ]
}
}Reports on average first response time, ticket counts and replies count.
Note: Reports are only available to admins.
Returns data points for average first response tim
Returns data points for average first response time.
Authorizations:
query Parameters
| user | integer ID of the agent to filter data points on. |
| team | integer ID of the team to filter data points on. |
| label | string Name of the label to filter data points on. |
Date (string) or DateTime (string) or Timestamp (string) |
Responses
Response samples
- 200
{- "data_points": [
- {
- "value": "42",
- "timestamp": "1360627200"
}
]
}Returns data points for tickets' count.
Returns data points for tickets' count.
Authorizations:
query Parameters
| user | integer ID of the agent to filter data points on. |
| team | integer ID of the team to filter data points on. |
| label | string Name of the label to filter data points on. |
Date (string) or DateTime (string) or Timestamp (string) |
Responses
Response samples
- 200
{- "data_points": [
- {
- "value": "42",
- "timestamp": "1360627200"
}
]
}Returns data points for replies' count.
Returns data points for replies' count.
Authorizations:
query Parameters
| user | integer ID of the agent to filter data points on. |
| team | integer ID of the team to filter data points on. |
| label | string Name of the label to filter data points on. |
Date (string) or DateTime (string) or Timestamp (string) |
Responses
Response samples
- 200
{- "data_points": [
- {
- "value": "42",
- "timestamp": "1360627200"
}
]
}Snippets allow you to create canned responses you can use when replying to your customers.
List, create, update and delete snippets.
Create Snippet
Creates a snippet for the company
Authorizations:
Request Body schema: application/jsonrequired
Snippet payload to create a snippet
object |
Responses
Request samples
- Payload
{- "snippet": {
- "name": "Facebook Link",
- "tags": "facebook, link",
- "content": {
- "text": "Facebook",
- "html": ""
}
}
}Response samples
- 201
{- "snippet": {
- "id": 4,
- "created_at": "2001-02-15T04:05:06+07:00",
- "name": "Facebook Link",
- "tags": "facebook, link",
- "content": {
- "text": "Facebook",
- "html": ""
}
}
}Update Snippet
Updates a Snippet specified by it's ID.
Authorizations:
path Parameters
| id required | integer The ID of the snippet to be updated. |
Request Body schema: application/jsonrequired
Snippet payload to create a snippet
object |
Responses
Request samples
- Payload
{- "snippet": {
- "name": "Facebook Link",
- "tags": "facebook, link",
- "content": {
- "text": "Facebook",
- "html": ""
}
}
}Response samples
- 200
{- "snippet": {
- "id": 4,
- "created_at": "2001-02-15T04:05:06+07:00",
- "name": "Facebook Link",
- "tags": "facebook, link",
- "content": {
- "text": "Facebook",
- "html": ""
}
}
}Assign a ticket to a team
Assigns a ticket to a team specified by the tickets ID and the team to be assigned (If the ticket is already assigned to a team and a user, reassigning the ticket to another team will remove the user assignee).
Authorizations:
path Parameters
| id required | integer The tickets ID |
Request Body schema: application/jsonrequired
A ticket assignation to a team
object |
Responses
Request samples
- Payload
{- "team_assignment": {
- "team_id": 1
}
}Response samples
- 201
{- "team_assignment": {
- "id": 2,
- "created_at": "2001-02-15T04:05:06+07:00",
- "ticket": {
- "id": 1
}
}, - "asignee": {
- "team": {
- "id": 2,
- "name": "Team 1",
- "picture": {
}
}
}
}Fetching Teams
Retrieves all the teams of the company
Authorizations:
query Parameters
| with_users | boolean If true, retrieves only teams with users in them. |
| user | string Value: "me" When me, retrives only the teams of the current user. All other values passed to this parameter is ignored |
Responses
Response samples
- 200
{- "teams": [
- {
- "id": 2,
- "name": "Team 1",
- "picture": {
}
}
]
}Actions you can do on tickets.
List, add, create, search, delete, archive, unarchive, assign, answer, mark as spam, trash, show replies and comment on tickets.
List tickets
Returns 15 tickets of the company in the order of their last activity.
Only tickets that are not archived are returned.
Authorizations:
query Parameters
| per_page | integer Default: 15 Specifies the number of tickets to retrieve. Must be less than 100. |
| page | integer Default: 1 Specifies the page of tickets to retrieve. |
| archived | string Default: false If true, retrieves only archived tickets. If false, it does not return any archived tickets. If any, includes archived tickets in the result. |
| spam | boolean Default: false If true, retrieved tickets contain tickets marked as spam. |
| trash | boolean Default: false If true, retrieved tickets contain tickets that are trashed. |
| replies | boolean If true, retrieved tickets contain only tickets with replies. If false, retrieved tickets contain only tickets without replies. |
| max_replies | integer Specifies the number of replies that a ticket must have. This cannot be used with replies = false. |
| assigned_user | string 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 | string 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. |
| label | string Set to label_name, retrieves only the tickets with the label label_name |
Date (string) or DateTime (string) or Timestamp (string) 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. | |
Date (string) or DateTime (string) or Timestamp (string) 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. | |
| sort_by | string Default: "last_activity" If last_activity, retrieves tickets sorted by last activity. If creation_time, retrieves tickets sorted by creation time. |
| requester_emails | string Can be used to filter tickets by requester email addresses. Accepts a string of comma separated email addresses. |
| total_only | boolean Default: false Can be used in conjunction with any other parameters to return only the total number of tickets |
Responses
Response samples
- 200
{- "total": 1,
- "current_page": 1,
- "per_page": 0,
- "total_pages": 0,
- "tickets": [
- {
- "id": 1,
- "subject": "Welcome to SupportBee",
- "replies_count": 0,
- "comments_count": 0,
- "last_activity_at": "2001-02-15T04:05:06+07:00",
- "created_at": "2001-02-15T04:05:06+07:00",
- "unanswered": true,
- "archived": false,
- "spam": false,
- "summary": "test -- Regards, Agent",
- "cc": [ ],
- "bcc": [ ],
- "labels": [ ],
- "requester": {
- "id": 21,
- "name": "Robert Requester",
- "role": "customer",
- "agent": false,
- "picture": [
- {
}
]
}, - "content": {
- "text": "test\\n\\n-- \\nRegards,\\nAgent",
- "html": "test<br>-- <br>Regards,<div>Agent</div>",
- "attachments": [
- {
- "id": 2,
- "created_at": "2001-02-15T04:05:06+07:00",
- "filename": "logo.jpg",
- "content_type": "image/jpeg; charset=UTF-8; name=logo.jpg",
- "url": {
}
}
]
}, - "current_user_asignee": {
- "id": 19,
- "name": "John Doe",
- "agent": true,
- "picture": [
- {
}
]
}, - "current_team_asignee": {
- "id": 1,
- "name": "Team 1",
- "agent": false,
- "picture": [
- {
}
]
}
}
]
}Create ticket
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.
Authorizations:
Request Body schema: application/jsonrequired
A support ticket
| subject | string Default: "No Subject" Specifies the subject of the ticket. |
| requester_name | string Specifies the name of the requester of the ticket. |
| requester_email | string Specifies the email of the requester of the ticket. |
| cc | Array of strings <email> (Email) [ items <email > ] Specifies the CC email addresses included in the ticket. If there are multiple emails, pass them comma separated. |
| bcc | Array of strings <email> (Email) [ items <email > ] 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 | boolean 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. |
object Specifies the content of the ticket. Either text or html must be present. Please look at the example above. | |
| forwarding_address_id | string 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. |
Responses
Request samples
- Payload
{- "subject": "Subject",
- "requester_name": "John Doe",
- "notify_requester": false,
- "content": {
- "text": "Creating a ticket",
- "html": "<p>Creating a ticket</p>",
- "attachment_ids": [
- 1240,
- 1241
]
}, - "forwarding_address_id": ""
}Response samples
- 201
{- "id": 1,
- "subject": "Welcome to SupportBee",
- "replies_count": 0,
- "comments_count": 0,
- "last_activity_at": "2001-02-15T04:05:06+07:00",
- "created_at": "2001-02-15T04:05:06+07:00",
- "unanswered": true,
- "archived": false,
- "spam": false,
- "summary": "test -- Regards, Agent",
- "cc": [ ],
- "bcc": [ ],
- "labels": [ ],
- "requester": {
- "id": 21,
- "name": "Robert Requester",
- "role": "customer",
- "agent": false,
- "picture": [
- {
}
]
}, - "content": {
- "text": "test\\n\\n-- \\nRegards,\\nAgent",
- "html": "test<br>-- <br>Regards,<div>Agent</div>",
- "attachments": [
- {
- "id": 2,
- "created_at": "2001-02-15T04:05:06+07:00",
- "filename": "logo.jpg",
- "content_type": "image/jpeg; charset=UTF-8; name=logo.jpg",
- "url": {
}
}
]
}, - "current_user_asignee": {
- "id": 19,
- "name": "John Doe",
- "agent": true,
- "picture": [
- {
}
]
}, - "current_team_asignee": {
- "id": 1,
- "name": "Team 1",
- "agent": false,
- "picture": [
- {
}
]
}
}Search tickets
Returns 15 tickets of the company in the order of their last activity matching the search query.
Authorizations:
query Parameters
| query required | string Specifies the query or keywords to searched. |
| per_page | integer Default: 15 Specifies the number of tickets to retrieve. Must be less than 100. |
| page | integer Default: 1 Specifies the page of tickets to retrieve. |
| spam | boolean Default: false If true, retrieved tickets contain tickets marked as spam. |
| trash | boolean Default: false If true, retrieved tickets contain tickets marked as trash. |
Responses
Response samples
- 200
{- "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": "2001-02-15T04:05:06+07:00",
- "created_at": "2001-02-15T04:05:06+07:00",
- "unanswered": true,
- "archived": false,
- "spam": false,
- "summary": "test -- Regards, Agent",
- "cc": [ ],
- "bcc": [ ],
- "labels": [ ],
- "requester": {
- "id": 21,
- "name": "Robert Requester",
- "role": "customer",
- "agent": false,
- "picture": [
- {
}
]
}, - "content": {
- "text": "test\\n\\n-- \\nRegards,\\nAgent",
- "html": "test<br>-- <br>Regards,<div>Agent</div>",
- "attachments": [
- {
- "id": 2,
- "created_at": "2001-02-15T04:05:06+07:00",
- "filename": "logo.jpg",
- "content_type": "image/jpeg; charset=UTF-8; name=logo.jpg",
- "url": {
}
}
]
}, - "current_user_asignee": {
- "id": 19,
- "name": "John Doe",
- "agent": true,
- "picture": [
- {
}
]
}, - "current_team_asignee": {
- "id": 1,
- "name": "Team 1",
- "agent": false,
- "picture": [
- {
}
]
}
}
]
}Retrieve a ticket
Retrieves a ticked recognized by it's ID
Authorizations:
path Parameters
| id required | integer The tickets ID |
Responses
Response samples
- 200
{- "ticket": {
- "id": 1,
- "subject": "Welcome to SupportBee",
- "replies_count": 0,
- "comments_count": 0,
- "last_activity_at": "2001-02-15T04:05:06+07:00",
- "created_at": "2001-02-15T04:05:06+07:00",
- "unanswered": true,
- "archived": false,
- "spam": false,
- "summary": "test -- Regards, Agent",
- "cc": [ ],
- "bcc": [ ],
- "labels": [ ],
- "requester": {
- "id": 21,
- "name": "Robert Requester",
- "role": "customer",
- "agent": false,
- "picture": [
- {
}
]
}, - "content": {
- "text": "test\\n\\n-- \\nRegards,\\nAgent",
- "html": "test<br>-- <br>Regards,<div>Agent</div>",
- "attachments": [
- {
- "id": 2,
- "created_at": "2001-02-15T04:05:06+07:00",
- "filename": "logo.jpg",
- "content_type": "image/jpeg; charset=UTF-8; name=logo.jpg",
- "url": {
}
}
]
}, - "current_user_asignee": {
- "id": 19,
- "name": "John Doe",
- "agent": true,
- "picture": [
- {
}
]
}, - "current_team_asignee": {
- "id": 1,
- "name": "Team 1",
- "agent": false,
- "picture": [
- {
}
]
}
}
}Assign a ticket to a user
Assigns a ticket to a user specified by the tickets ID and the user to be assigned (If the ticket is already assigned to a team, then the given user must be a member of that team).
Authorizations:
path Parameters
| id required | integer The tickets ID |
Request Body schema: application/jsonrequired
A ticket assignation to a user
object |
Responses
Request samples
- Payload
{- "user_assignment": {
- "user_id": 1
}
}Response samples
- 201
{- "user_assignment": {
- "id": 2,
- "created_at": "2001-02-15T04:05:06+07:00",
- "ticket": {
- "id": 1
}
}, - "asignee": {
- "user": {
- "id": 1,
- "name": "Agent1",
- "agent": true,
- "picture": {
}
}
}
}Assign a ticket to a team
Assigns a ticket to a team specified by the tickets ID and the team to be assigned (If the ticket is already assigned to a team and a user, reassigning the ticket to another team will remove the user assignee).
Authorizations:
path Parameters
| id required | integer The tickets ID |
Request Body schema: application/jsonrequired
A ticket assignation to a team
object |
Responses
Request samples
- Payload
{- "team_assignment": {
- "team_id": 1
}
}Response samples
- 201
{- "team_assignment": {
- "id": 2,
- "created_at": "2001-02-15T04:05:06+07:00",
- "ticket": {
- "id": 1
}
}, - "asignee": {
- "team": {
- "id": 2,
- "name": "Team 1",
- "picture": {
}
}
}
}Fetch ticket replies
Retrieves all the replies of a ticket specified by it's ID
Authorizations:
path Parameters
| id required | integer The tickets ID |
Responses
Response samples
- 200
{- "replies": [
- {
- "id": 1,
- "created_at": "2001-02-15T04:05:06+07:00",
- "summary": "Reply Content",
- "cc": [ ],
- "bcc": [ ],
- "ticket": {
- "replies_count": 2,
- "comments_count": 0
}, - "replier": {
- "id": 1,
- "name": "Agent Argentus",
- "agent": true,
- "picture": {
}
}, - "content": {
- "body": "Reply Content",
- "html": null,
- "attachments": [ ]
}
}
]
}Create a reply
Post a reply to a ticket specified by it's ID. Admin users can reply on behalf of an agent.
Authorizations:
path Parameters
| id required | integer The tickets ID |
Request Body schema: application/jsonrequired
A reply to a ticket
object |
Responses
Request samples
- Payload
{- "reply": {
- "cc": [ ],
- "bcc": [ ],
- "content": {
- "html": "<p>Reply content</p>",
- "text": "Reply content",
- "attachment_ids": [ ]
}
}
}Response samples
- 201
{- "reply": {
- "id": 1,
- "created_at": "2001-02-15T04:05:06+07:00",
- "summary": "Reply Content",
- "cc": [ ],
- "bcc": [ ],
- "ticket": {
- "replies_count": 2,
- "comments_count": 0
}, - "replier": {
- "id": 1,
- "name": "Agent Argentus",
- "agent": true,
- "picture": {
}
}, - "content": {
- "body": "Reply Content",
- "html": null,
- "attachments": [ ]
}
}
}Show a reply
Retrieves the reply for the ticket specified by the ticket and reply IDs.
Authorizations:
path Parameters
| ticket_id required | integer The tickets ID |
| id required | integer The reply ID |
Responses
Response samples
- 200
{- "id": 1,
- "created_at": "2001-02-15T04:05:06+07:00",
- "summary": "Reply Content",
- "cc": [ ],
- "bcc": [ ],
- "ticket": {
- "replies_count": 2,
- "comments_count": 0
}, - "replier": {
- "id": 1,
- "name": "Agent Argentus",
- "agent": true,
- "picture": {
}
}, - "content": {
- "body": "Reply Content",
- "html": null,
- "attachments": [ ]
}
}Fetch Comments
Retrieves all the comments on the ticket specified by the ticket ID.
Authorizations:
path Parameters
| id required | integer The tickets ID |
Responses
Response samples
- 200
{- "comments": [
- {
- "id": 1,
- "created_at": "2001-02-15T04:05:06+07:00",
- "ticket": {
- "replies_count": 0,
- "comments_count": 1
}, - "commenter": {
- "id": 1,
- "name": "Agent1",
- "agent": true,
- "picture": {
}
}, - "content": {
- "text": "test\\n\\n-- \\nRegards,\\nAgent",
- "html": "test<br>-- <br>Regards,<div>Agent</div>",
- "attachments": [
- {
- "id": 2,
- "created_at": "2001-02-15T04:05:06+07:00",
- "filename": "logo.jpg",
- "content_type": "image/jpeg; charset=UTF-8; name=logo.jpg",
- "url": {
}
}
]
}
}
]
}Create Comment
Creates a comment on a ticket specified by the ticket ID.
Authorizations:
path Parameters
| id required | integer The tickets ID |
Request Body schema: application/jsonrequired
A comment for a ticket
object |
Responses
Request samples
- Payload
{- "comment": {
- "content": {
- "text": "test\\n\\n-- \\nRegards,\\nAgent",
- "html": "test<br>-- <br>Regards,<div>Agent</div>",
- "attachments": [
- {
- "id": 2,
- "created_at": "2001-02-15T04:05:06+07:00",
- "filename": "logo.jpg",
- "content_type": "image/jpeg; charset=UTF-8; name=logo.jpg",
- "url": {
}
}
]
}
}
}Response samples
- 201
{- "comment": {
- "id": 1,
- "created_at": "2001-02-15T04:05:06+07:00",
- "ticket": {
- "replies_count": 0,
- "comments_count": 1
}, - "commenter": {
- "id": 1,
- "name": "Agent1",
- "agent": true,
- "picture": {
}
}, - "content": {
- "text": "test\\n\\n-- \\nRegards,\\nAgent",
- "html": "test<br>-- <br>Regards,<div>Agent</div>",
- "attachments": [
- {
- "id": 2,
- "created_at": "2001-02-15T04:05:06+07:00",
- "filename": "logo.jpg",
- "content_type": "image/jpeg; charset=UTF-8; name=logo.jpg",
- "url": {
}
}
]
}
}
}Assign a ticket to a user
Assigns a ticket to a user specified by the tickets ID and the user to be assigned (If the ticket is already assigned to a team, then the given user must be a member of that team).
Authorizations:
path Parameters
| id required | integer The tickets ID |
Request Body schema: application/jsonrequired
A ticket assignation to a user
object |
Responses
Request samples
- Payload
{- "user_assignment": {
- "user_id": 1
}
}Response samples
- 201
{- "user_assignment": {
- "id": 2,
- "created_at": "2001-02-15T04:05:06+07:00",
- "ticket": {
- "id": 1
}
}, - "asignee": {
- "user": {
- "id": 1,
- "name": "Agent1",
- "agent": true,
- "picture": {
}
}
}
}Fetching Users and Customer Groups
Retrieves all users of the company
Authorizations:
query Parameters
| with_invited | boolean Default: false If true, returns all the agents, including invited (unconfirmed) agents. |
| with_roles | string Default: "admin,agent,collaborator" Enum: "admin" "agent" "collaborator" "customer" |
| type | string Default: "user" Enum: "user" "customer_group" |
Responses
Response samples
- 200
{- "users": [
- {
- "id": 1,
- "type": "user",
- "first_name": "Sarah",
- "last_name": "Caring",
- "name": "Sarah Caring",
- "role": "agent",
- "agent": true,
- "two_factor_authentication_enabled": true,
- "picture": {
}, - "can_members_access_group_tickets": null,
- "email_domains": [ ],
- "members_count": 0,
- "active_tickets_count": 0,
- "requested_tickets_count": 0,
- "teams": [ ]
}
]
}Create a user or customer group
Creates a user for the company. Also used to create customer groups, which are treated as users.
Authorizations:
Request Body schema: application/json
object |
Responses
Request samples
- Payload
{- "user": {
- "name": "Test Name",
- "role": 10,
- "team_ids": [ ],
- "type": "user"
}
}Response samples
- 201
{- "user": {
- "id": 1,
- "type": "user",
- "first_name": "Sarah",
- "last_name": "Caring",
- "name": "Sarah Caring",
- "role": "agent",
- "agent": true,
- "two_factor_authentication_enabled": true,
- "picture": {
}, - "can_members_access_group_tickets": null,
- "email_domains": [ ],
- "members_count": 0,
- "active_tickets_count": 0,
- "requested_tickets_count": 0,
- "teams": [ ]
}
}Show User or Customer Group
Retrieves the user specified by id.
Authorizations:
path Parameters
| id required | integer The users ID. |
query Parameters
| max_tickets | integer Default: 5 Specify the maximum number of recent tickets you want to retrieve that this user created. If false returns all tickets. |
Responses
Response samples
- 200
{- "user": {
- "id": 1,
- "type": "user",
- "first_name": "Sarah",
- "last_name": "Caring",
- "name": "Sarah Caring",
- "role": "agent",
- "agent": true,
- "two_factor_authentication_enabled": true,
- "picture": {
}, - "can_members_access_group_tickets": null,
- "email_domains": [ ],
- "members_count": 0,
- "active_tickets_count": 0,
- "requested_tickets_count": 0,
- "teams": [ ]
}
}Update a User
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.
Authorizations:
path Parameters
| id required | integer The users ID. |
Request Body schema: application/json
This specifies the data in JSON required to update a user. All fields are optional. Any fields not provided will not be updated.
object |
Responses
Request samples
- Payload
{- "user": {
- "name": "Test Name",
- "role": 10,
- "team_ids": [ ],
- "type": "user"
}
}Response samples
- 200
{- "user": {
- "id": 1,
- "type": "user",
- "first_name": "Sarah",
- "last_name": "Caring",
- "name": "Sarah Caring",
- "role": "agent",
- "agent": true,
- "two_factor_authentication_enabled": true,
- "picture": {
}, - "can_members_access_group_tickets": null,
- "email_domains": [ ],
- "members_count": 0,
- "active_tickets_count": 0,
- "requested_tickets_count": 0,
- "teams": [ ]
}
}Fetch Members of a customer group
Retrieves all members of a customer group specified by the customer groups ID.
Authorizations:
path Parameters
| id required | integer The ID of the customer group. |
Responses
Response samples
- 200
{- "users": [
- {
- "id": 1,
- "type": "user",
- "first_name": "Sarah",
- "last_name": "Caring",
- "name": "Sarah Caring",
- "role": "agent",
- "agent": true,
- "two_factor_authentication_enabled": true,
- "picture": {
}, - "can_members_access_group_tickets": null,
- "email_domains": [ ],
- "members_count": 0,
- "active_tickets_count": 0,
- "requested_tickets_count": 0,
- "teams": [ ]
}
]
}Add Member
Add a user to a customer group as a member.
Authorizations:
path Parameters
| id required | integer The ID of the customer group |
Request Body schema: application/json
object |
Responses
Request samples
- Payload
{- "member": {
- "id": 0
}
}Response samples
- 201
{- "user": {
- "id": 1,
- "type": "user",
- "first_name": "Sarah",
- "last_name": "Caring",
- "name": "Sarah Caring",
- "role": "agent",
- "agent": true,
- "two_factor_authentication_enabled": true,
- "picture": {
}, - "can_members_access_group_tickets": null,
- "email_domains": [ ],
- "members_count": 0,
- "active_tickets_count": 0,
- "requested_tickets_count": 0,
- "teams": [ ]
}
}