Overview

Trudesk API general information

API Version 2 has already begun being implemented. Only security/bug fixes will be applied to version 1

Authentication

Trudesk uses an API key to authenticate requests. The default administrator user has an api key generated during account creation.

Your API key can be found in your profile or by sending a login request.

Send the API key in the accesstoken header to authenticate each request.

Login

Login through the login api endpoint to return your accesstoken


post
/api/v1/login

Usage

curl -l "http://{url}/api/v1/login"

Request

{
"username": your_username,
"password": your_password
}

Response

{
"success": true,
"accesstoken": your_access_token,
"user": {USER_OBJECT}
}

Models

Ticket

Property Type Comment
_id ObjectID MongoDB Object ID
uid Number Readable Ticket ID
owner User Ref User Object - Owner of Ticket
group Group Group linked to this Ticket
assignee User User currently assigned to this Ticket
date Date Ticket Creation Date
updated Date Ticket Updated Date
deleted Bool Has the ticket be marked deleted?
type TicketType Ref TicketType Object
status Number Ticket Status (0-New, 1-Open, 2-Pending, 3-Closed)
priority Priority Ref Ticket Priority Object
tags Array[Tag] Ref Tag Objects linked to Ticket
subject String The subject of the ticket
issue String Issue text
closedDate Date Date the ticket was closed.
comments Array[Comment] Ref Comment Object
notes Array[Note] Ref Note Object
attachments Array[Attachment] Ref Attachment Object
history Array[History] Ref History Object
subscribers Array[User] List of subscribed Users


Ticket Type

Property Type Comment
_id ObjectID MongoDB Object ID
name String Name of ticket type
priorities Array[Priority] Array of linked Priorities


Ticket Comment

Property Type Comment
owner ObjectID Ref User owner of the comment
date Date DateTime the comment was created
comment String Message content
deleted Bool Is the comment deleted?


Ticket Note

Property Type Comment
owner ObjectID Ref User owner of the note
date Date DateTime the note was created
note String Note content
deleted Bool Is the note deleted?


Priority

Property Type Comment
_id ObjectID MongoDB Object ID
name String Display Name of priority
overdueIn Number Minutes until priority is marked overdue
htmlColor String Hex color value to display the priority


User

Property Type Comment
_id ObjectID MongoDB Object ID
username String User’s Username
password String Bcrypt Encrypted Password
fullname String User’s Full Name
email String User’s Email Address
role Role Ref Permission Role Object
lastOnline Date DateTime user was last online
title String User’s Title
image String Filename of user’s profile pic
resetPassHash String Hash string for user’s password reset
resetPassExpire Date DateTime the password hash will expire
tOTPKey String Layer2 Auth Key for onetime password
tOTPPeriod String Time the key is validated
resetL2AuthHash String Hash for resetting the L2 Auth
resetL2AuthExpire Date DateTime resetL2AuthHas will expire
hasL2Auth Bool Does the user have L2Auth enabled?
accessToken String API Key assigned to user
deleted Bool Is the account marked deleted?


Group

Property Type Comment
_id ObjectID MongoDB Object ID
name String Name of group
members Array[[User(#User)]] Group Members
sendMailTo Array[[User(#User)]] Users to send notifications to
public Bool Is this group a public created group?


Role

Property Type Comment
_id ObjectID MongoDB Object ID
name String Role Name
normalized String Role name normalized
grants Array[String] Permission grants for the role
hierarchy Bool Does the role have hierarchy enabled?


Notice

Property Type Comment
_id ObjectID MongoDB Object ID
name String Internal name for the notice
date Date Date the notice was created
color String Hex color of the notice background
fontColor String Hex color of the notice font
message String Message the notice will display
active Bool If the notice is currently active
activeDate Date The DateTime the notice was activated
alertWindow Bool Show UI blocking alert window?


Notification

Property Type Comment
_id ObjectID MongoDB Object ID
owner User Ref user the notification belongs to
title String Title content
message String Message content
type Number Type of notification
data Object Supporting notificiation object
unread Bool Has the notification been read?


Setting

Property Type Comment
_id ObjectID MongoDB Object ID
name String Name of the setting
value Mixed Value of the setting


Users

Get

Returns a list of accounts via query string


get
/api/v1/users

Usage

curl -H "accesstoken: {accesstoken}" \
-l "http://{url}/api/v1/users?limit={limit}&page={page}&search={term}"

Response

{
"success": true,
"count": 1,
"users": [
{
"_id": "59154d0b728c2904421f0ab6",
"username": "chris.brame",
"fullname": "Chris Brame",
"email": "email@gmail.com",
"role": "support",
"title": "Support Director",
"deleted": false,
"preferences": {
"openChatWindows": [],
"autoRefreshTicketGrid": true,
"tourCompleted": false
},
"groups": [
"Group Name"
]
}
]
}

Get Single

Get the account via given username


get
/api/v1/users/{username}

Usage

curl -H "accesstoken: {accesstoken}" -l http://{url}/api/v1/users/:username

Response

{
"success": true,
"groups": [
"57c4789c8bfd267c0383acd1",
"5912a110b61e5b6c042594c8"
],
"user": {
"_id": "57c4789c8bfd267c0383acd2",
"username": "chris.brame",
"fullname": "Chris Brame",
"email": "email@gmail.com",
"role": "admin",
"title": "Administrator",
"image": "aProfile_chris.brame.jpg",
"lastOnline": "2017-10-27T19:38:33.315Z",
"deleted": false,
"preferences": {
"openChatWindows": [],
"autoRefreshTicketGrid": true,
"tourCompleted": false
}
}
}

Create

Create an account with the given post data


Post
/api/v1/users/create

Usage

curl -X POST \
-H "Content-Type: applications/json" \
-H "accessToken: {accesstoken}" \
-d "{Request Data}" \
-l http://{url}/api/v1/users/create

Request Data

{
"aUsername": "user.name",
"aPass": "password",
"aPassConfirm": "password",
"aFullname": "fullname",
"aEmail": "email@email.com",
"aRole": "{RoleId}",
"aTitle": "User Title",
"aGrps": "[{GroupId}]"
}

Response

{
"success": true,
"error": null,
"account": {
"_id": "59154d0b728c2904421f0ab6",
"username": "chris.brame",
"fullname": "Chris Brame",
"email": "email@email.com",
"role": "support",
"title": "Support Director",
"deleted": false,
"preferences": {
"openChatWindows": [],
"autoRefreshTicketGrid": true,
"tourCompleted": false
},
"iOSDeviceTokens": [],
"groups": []
}
}

Update

Updates the given user via username


put
/api/v1/users/{username}

Usage

curl -X PUT \
-H "Content-Type: applications/json" \
-H "accessToken: {accesstoken}" \
-d "{Request Data}" \
-l http://{url}/api/v1/users/{username}

Request Data

{
"aUsername": "{{username}}",
"aFullname": "{{fullname}}",
"aTitle": "{{title}}",
"aPass": "{{password}}",
"aPassconfirm": "{{password_confirm}}",
"aEmail": "{{email}}",
"aRole": "{{role.id}}",
"aGrps": []
}

Response

{
"success": true
}

Enable

Enables the given user via username


get
/api/v1/users/{username}/enable

Response

{ "success": true }

Disable

Disable the given user via username


delete
/api/v1/users/{username}

Response

{ "success": true }

Groups

Create

Creates a group


post
/api/v1/groups/create

Usage

curl -X POST \
-H "Content-Type: applications/json" \
-H "accessToken: {accesstoken}" \
-d {RequestData} \
-l http://{url}/api/v1/users/{username}

Request Data

{
"name": "Group Name",
"members": [members],
"sendMailTo": [sendMailTo]
}

Response

{ 
"success": true,
"error": null,
"group": {

}
}

Get

Returns all groups


get
/api/v1/groups/all
curl -H "accesstoken: {accesstoken}" -l http://{url}/api/v1/groups/all

Response

{
"success": true,
"groups": [{
"_id": "{_id}",
"name": "Group Name",
"sendMailTo": [],
"members": []
}]
}

Get Single

Returns a single group via _id


get
/api/v1/groups/{id}
curl -H "accesstoken: {accesstoken}" -l http://{url}/api/v1/group/{id}

Response

{
"success": true,
"group": {
"_id": "{_id}",
"name": "Group Name",
"sendMailTo": [],
"members": []
}
}

Delete

Deletes the given group via _id


delete
/api/v1/groups/{id}
curl -X DELETE \
-H "accesstoken: {accesstoken}" \
-l http://{url}/api/v1/group/{id}

Response

{
"success": true,
"error": null
}

Update

Updates the given group


put
/api/v1/groups/{id}
curl -X PUT \
-H "Content-Type: application/json" \
-H "accesstoken: {accesstoken}" \
-d "{RequestData}" \
-l http://{url}/api/v1/groups/:id

Request Data

{
"name": "Group Name",
"members": [members],
"sendMailTo": [sendMailTo]
}

Response

{
"success": true,
"error": null,
"group": {
"_id": "{_id}",
"name": "Group Name",
"sendMailTo": [],
"members": []
}
}

Messages

Get Messages

Returns messages for the current logged in user (user of accesstoken)

This API is schedule to change in an upcoming update


get
/api/v1/messages
curl -H "accesstoken: {accesstoken}" -l http://{url}/api/v1/messages

Response

{
"success": true,
"conversations": [{
"cid": "591d3aee68dc1eec4955491b",
"p": [
{
"_id": "590972322df64538101af2d9",
"username": "User.1415",
"fullname": "User 1415",
"email": "user.1415@fakeemail.com"
},
{
"_id": "57c4789c8bfd267c0383acd2",
"username": "chris.brame",
"fullname": "Chris Brame",
"email": "chris.brame@fakeemail.com",
"title": "Administrator",
"image": "aProfile_chris.brame.jpg",
"lastOnline": "2017-11-02T00:36:30.574Z"
}
],
"messages": [
{
"_id": "59882765ca493f8c12a354f9",
"createdAt": "2017-08-07T08:40:05.399Z",
"owner": {
"_id": "57c4789c8bfd267c0383acd2",
"username": "chris.brame",
"fullname": "Chris Brame",
"email": "chris.brame@fakeemail.com",
"image": "aProfile_chris.brame.jpg",
"lastOnline": "2017-11-02T00:36:30.574Z"
},
"body": "Hey"
},
]
}]
}

Notices

Create

Creates a notice


post
/api/v1/notices/create
curl -X PUT \
-H "Content-Type: application/json" \
-H "accesstoken: {accesstoken}" \
-d "{RequestData}" \
-l http://{url}/api/v1/notice/create

Request Data

{
"name": "Group Name",
"members": [members],
"sendMailTo": [sendMailTo]
}

Response

{
"success": true,
"error": null,
"group": {
"_id": "{_id}",
"name": "Group Name",
"sendMailTo": [],
"members": []
}
}

Delete

Deletes Notice


delete
/api/v1/notices/{noticeId}
curl -X DELETE \
-H "Content-Type: application/json" \
-H "accesstoken: {accesstoken}" \
-l http://{url}/api/v1/notice/{noticeId}

Response

{
"success": true,
"error": null
}

Update

Updates Notice


put
/api/v1/notices/{noticeId}
curl -X PUT \
-H "Content-Type: application/json" \
-H "accesstoken: {accesstoken}" \
-d {RequestData} \
-l http://{url}/api/v1/notice/{noticeId}

Request Data

{
"name": "Notice Name",
"messages": "Notice Message",
"color": "#CCCCC",
"fontColor": "#000000",
"alterWindow": true
}

Response

{
"success": true,
"error": null
}

Clear

Clears the currently active notice


get
/api/v1/notices/clearactive
curl -H "Content-Type: application/json" \
-H "accesstoken: {accesstoken}" \
-l http://{url}/api/v1/notice/clearactive

Response

{
"success": true,
"error": null
}

Reports

Generate

Reports API is currently being redesigned

Settings

Update

Updates setting


put
/api/v1/setting/{setting}
curl -X PUT \
-H "Content-Type: application/json" \
-H "accesstoken: {accesstoken}" \
-d {RequestData} \
-l http://{url}/api/v1/setting/{setting}

Request Data

{
"name": "setting:name",
"value": {setting value}
}

Response

{
"success": true,
"error": null
}

Tickets

Create

Creates a ticket


post
/api/v1/tickets/create
curl -X POST \
-H "Content-Type: application/json" \
-H "accesstoken: {accesstoken}" \
-d {RequestData} \
-l http://{url}/api/v1/tickets/create

Request Data

{
"subject": "Subject",
"issue": "Issue Exmaple",
"owner": {OwnerId},
"group": {GroupId},
"type": {TypeId},
// Note: Priority must be priority id associated with the selected type id
"priority": {PriorityId}
}

Response

{
"success": true,
"error": null,
"ticket": {
"date": "2017-05-01T06:28:48.815Z",
"deleted": false,
"status": 1,
"uid": 15025,
"_id": "5906d5a0fe0710942be61c55"
"tags": [
{
"_id": "57f887385881a1602ffc7063",
"name": "34234"
}
],
"comments": [
{
"owner": {
"_id": "57f59e306067d1d40764bdb1",
"username": "demo.user",
"fullname": "Demo User",
"email": "demo@demo.com",
"role": "admin",
"title": "",
"image": "aProfile_demo.user.png"
},
"date": "2017-05-01T06:29:29.402Z",
"comment": "<p>Got it</p>\n",
"_id": "5906d5c9fe0710942be61c5c",
"deleted": false
}
],
"notes": [],
"attachments": [],
"history": [
{
"action": "ticket:created",
"description": "Ticket was created.",
"owner": {
"_id": "57f59e306067d1d40764bdb1",
"username": "demo.user",
"fullname": "Demo User",
"email": "demo@demo.com",
"role": "admin",
"title": "",
"image": "aProfile_demo.user.png"
},
"_id": "5906d5a0fe0710942be61c56",
"date": "2017-05-01T06:28:48.818Z"
}
],
"subscribers": [
{
"_id": "57f59e306067d1d40764bdb1",
"username": "demo.user",
"fullname": "Demo User",
"email": "demo@demo.com",
"role": "admin",
"title": "",
"image": "aProfile_demo.user.png"
}
],
"updated": "2017-08-09T06:29:23.184Z",
"assignee": {},
"closedDate": null,
"priority": {PriorityID},
"group": {
"_id": "57c4789c8bfd267c0383acd1",
"name": "Administrators",
"public": false,
"sendMailTo": [
"57c4789c8bfd267c0383acd2"
],
"members": [
"5896bccc67b4a730278e8fd6"
]
},
"issue": "<p>Testing ticket creatation from phone</p>\n",
"subject": "Test from phone",
"type": {
"_id": "57c4789c8bfd267c0383acd0",
"name": "Task"
},
"owner": {
"_id": "57f59e306067d1d40764bdb1",
"username": "demo.user",
"fullname": "Demo User",
"email": "demo@demo.com",
"role": "admin",
"title": "",
"image": "aProfile_demo.user.png"
}
}
}

Get

Get Single

Returns a single ticket via UID


get
/api/v1/tickets/{uid}
curl -H "Content-Type: application/json" \
-H "accesstoken: {accesstoken}" \
-l http://{url}/api/v1/tickets/{uid}

Response

{
"success": true,
"error": null,
"ticket": {
"date": "2017-05-01T06:28:48.815Z",
"deleted": false,
"status": 1,
"uid": 15025,
"_id": "5906d5a0fe0710942be61c55"
"tags": [
{
"_id": "57f887385881a1602ffc7063",
"name": "34234"
}
],
"comments": [
{
"owner": {
"_id": "57f59e306067d1d40764bdb1",
"username": "demo.user",
"fullname": "Demo User",
"email": "demo@demo.com",
"role": "admin",
"title": "",
"image": "aProfile_demo.user.png"
},
"date": "2017-05-01T06:29:29.402Z",
"comment": "<p>Got it</p>\n",
"_id": "5906d5c9fe0710942be61c5c",
"deleted": false
}
],
"notes": [],
"attachments": [],
"history": [
{
"action": "ticket:created",
"description": "Ticket was created.",
"owner": {
"_id": "57f59e306067d1d40764bdb1",
"username": "demo.user",
"fullname": "Demo User",
"email": "demo@demo.com",
"role": "admin",
"title": "",
"image": "aProfile_demo.user.png"
},
"_id": "5906d5a0fe0710942be61c56",
"date": "2017-05-01T06:28:48.818Z"
}
],
"subscribers": [
{
"_id": "57f59e306067d1d40764bdb1",
"username": "demo.user",
"fullname": "Demo User",
"email": "demo@demo.com",
"role": "admin",
"title": "",
"image": "aProfile_demo.user.png"
}
],
"updated": "2017-08-09T06:29:23.184Z",
"assignee": {},
"closedDate": null,
"priority": {PriorityID},
"group": {
"_id": "57c4789c8bfd267c0383acd1",
"name": "Administrators",
"public": false,
"sendMailTo": [
"57c4789c8bfd267c0383acd2"
],
"members": [
"5896bccc67b4a730278e8fd6"
]
},
"issue": "<p>Testing ticket creatation from phone</p>\n",
"subject": "Test from phone",
"type": {
"_id": "57c4789c8bfd267c0383acd0",
"name": "Task"
},
"owner": {
"_id": "57f59e306067d1d40764bdb1",
"username": "demo.user",
"fullname": "Demo User",
"email": "demo@demo.com",
"role": "admin",
"title": "",
"image": "aProfile_demo.user.png"
}
}
}

Returns tickets based on search string


get
/api/v1/tickets/search/?search={searchString}
curl -H "Content-Type: application/json" \
-H "accesstoken: {accesstoken}" \
-l http://{url}/api/v1/tickets/search/?search={searchString}

Response

{
"success": true,
"error": null,
"count": 0,
"tickets": []
}

Update

Updates ticket via ObjectId


put
/api/v1/tickets/{id}

curl -H "Content-Type: application/json" 
-H "accesstoken: {accesstoken}"
-X PUT
-d {RequestData}
-l http://{url}/api/v1/tickets/{id}

Request Data

{
"status": 0-3,
"group": GroupId,
"issue": "New Issue Text",
"subject": "New Subject Text"
}

Response

{
"success": true,
"error": null,
"ticket": {
"date": "2018-02-11T17:39:21.790Z",
"deleted": false,
"status": 0,
"tags": [...],
"comments": [...],
"notes": [],
"attachments": [...],
"history": [...],
"subscribers": [...],
"_id": "5a807fc98a7f3c15cc86a68d",
"subject": "Test Ticket",
"issue": "{New Issue Text}",
"group": {
"members": [...],
"sendMailTo": [...],
"public": false,
"_id": "57c4789c8bfd267c0383acd1",
"name": "Administrators"
},
"type": {
"_id": "57c4789c8bfd267c0383acd0",
"name": "Task"
},
"priority": {PriorityID},
"owner": {
"_id": "57c4789c8bfd267c0383acd2",
"username": "chris.brame",
"fullname": "Chris Brame",
"email": "polonel@gmail.com",
"role": "admin",
"title": "Administrator",
"image": "aProfile_chris.brame.jpg"
},
"uid": 197671
}
}

Delete

Delete ticket via ObjectId


delete
/api/v1/tickets/{id}

curl -H "accesstoken: {accesstoken}" 
-X DELETE
-l http://{url}/api/v1/tickets/{id}

Response

{
"success": true,
"error": null
}

Comments

Add

Adds a comment to a ticket


post
/api/v1/tickets/addcomment

curl -H "accesstoken: {accesstoken}"
-X POST
-d {RequestData}
-l http://{url}/api/v1/tickets/addcomment

Request Data

{
"ticketId": {TicketId},
"owner": {OwnerId},
"comment": "Comment to post"
}