Advanced topics

Helpdesk API

Jitbit help desk ticketing system includes a REST API for "inbound" integration and API hooks for "outbound" integration.

General info

Base address

The API address is:

https://[HELPDESK]/api

Where [HELPDESK] is the helpdesk application address. Hosted or self-installed, doesn’t matter.

Don’t forget to add "/helpdesk" to the URL if your Helpdesk is hosted under a sub-directory.

Example of the correct URL for SaaS clients:

https://company.jitbit.com/helpdesk/api

Basic authentication

Every API action checks the user's permissions before executing the action (showing tickets, posting comments etc), so you must authenticate as a helpdesk user by sending basic authorization headers with every call.

Again: all the methods use basic authentication and you need to pass the Authorization header with every API call.

Most of http-client software (like curl etc.) support basic authentication out of the box without any additional coding. But just in case - here's how you construct the Authorization header programmatically:

  1. Username and password are combined into a colon-separated string
    username:password
    
  2. The resulting string literal is then encoded using Base64
  3. The authorization method and a space i.e. Basic is then put before the encoded string.
  4. NOTE: even if you use Windows authentication with your on-premise helpdesk installation you still have to use Basic auth headers! Simply pass your Windows username and password. Also don’t forget to include the user’s domain into the username like this DOMAIN\Username.
  5. For example, if the user has admin username and admin password then the header is formed as follows:
    Authorization: Basic YWRtaW46YWRtaW4=
    

NOTE: If you are using Windows\AD authentication specify the fully qualified domain name as your username, like DOMAIN\username.

Keep in mind that passing wrong username and/or password to the app 3 times in a row blocks your IP address for 5 minutes.

Token authentication

In addition to Basic Authentication described above, we support token authentication.

Authorization: Bearer <User-Token>

You can get your <User-Token> by visiting /User/Token/ page in the helpdesk app. You can also visit /User/Token?json=true to get the token in the JSON format.

Note: when a user changes their password - the authentication token expires and stops working. If you'd like to invalidate all tokens at once and force them all to expire - change the app's "shared secret" setting in the admin area.

Passing parameters

All incoming method-parameters should be passed via query-strings like this

http://helpdesk-url/api/SetCustomField?ticketId=123&fieldId=321&value=blahblah

or via the POST data.

Use Query-string or POST vars, not JSON

When sending parameters to the API, pass them as either query-string, or via POST fields. Do not use JSON. Some of our most used API methods support incoming JSON (because people are lazy and don't read the docs) but the recommended way is to avoid it.

GZipped response

Make sure you add Accept-Encoding: gzip header to save bandwidth and get the response faster

General methods

Authorization (POST)

POST https://[helpdesk-url]/api/Authorization

Use this method to simply test if you pass correct basic authentication headers. The method returns a helpdesk "user" object (as a JSON string) that represents the current user.

Returns:

{
    "UserID": 1,
    "Username": "admin",
    "Email": "admin@testmail",
    "FirstName": "",
    "LastName": "",
    "Notes": "",
    "Location": "",
    "Phone": "",
    "Department": null,
    "CompanyName": null,
    "IPAddress": "::1",
    "HostName": "::1",
    "Lang": "",
    "UserAgent": "Mozilla/5.0 (Windows NT 6.2; WOW64) AppleWebKit/537.31 (KHTML, like Gecko) Chrome/26.0.1410.3 Safari/537.31",
    "AvatarURL": null,
    "Signature": "test sign",
    "Greeting": "Hi",
    "CompanyId": null,
    "IsAdmin": true,
    "Disabled": false,
    "SendEmail": true,
    "IsTech": false,
    "LastSeen": "2020-02-28T04:48:00Z",
    "IsManager": false
}

Ticket methods

API methods that work with helpdesk tickets

Tickets

GET https://[helpdesk-url]/api/Tickets

Gets a list of tickets the current user has permissions to see. Returns a JSON array.

Parameters:

NameTypeDescription
modestring(optional) Allows you to choose, which tickets to show all (default) shows all tickets, including closed, unanswered shows new or updated by customer or for tech tickets, unclosed all active tickets, handledbyme shows tickets assigned to the user
categoryidint(optional) Filter by a category
sectionIdint(optional) Filter by a section
statusIdint[](optional) Filter by status(es), you can pass an array like this: ?statusId=1&statusId=2
fromUserIdint(optional) Filter by a ticket creator
fromCompanyIdint(optional) Filter by a company
handledByUserIDint(optional) Filter by a ticket performer
tagNamestring(optional) Filter by ticket a tag
dateFromstring(optional) Filter by creation date (date format should be YYYY-MM-DD, for example 2016-11-24)
dateTostring(optional) Filter by creation date (date format should be YYYY-MM-DD, for example 2016-11-24)
updatedFromstring(optional) Filter by "last updated" date (date format should be YYYY-MM-DD, for example 2016-11-24)
updatedTostring(optional) Filter by "last updated" date (date format should be YYYY-MM-DD, for example 2016-11-24)
dueInDaysint(optional) Filter by "due in X days"
includeCustomFieldsbool(optional) Add custom field values to the output
countint(optional) How many tickets to return. Default: 10. Max: 300.
offsetint(optional) Use this to create paging. For example "offset=20&count=20" will return the next 20 tickets after the first 20. Default: 0.

Returns

[
    {
        "IssueID": 382,
        "Priority": 0,
        "StatusID": 1,
        "IssueDate": "2013–01–11T15:29:49.57",
        "Subject": "test",
        "Status": "New",
        "UpdatedByUser": false,
        "UpdatedByPerformer": false,
        "CategoryID": 21,
        "UserName": "admin",
        "Technician": null,
        "FirstName": "",
        "LastName": "",
        "DueDate": null,
        "TechFirstName": null,
        "TechLastName": null,
        "LastUpdated": "2013–01–11T15:29:49.57",
        "UpdatedForTechView": false,
        "UserID": 1,
        "CompanyID": null,
        "CompanyName": null,
        "SectionID": null,
        "AssignedToUserID": null,
        "Category": "Hardware"
    }
    //...more tickets
]

Ticket

GET https://[helpdesk-url]/api/ticket?id=123

Gets details of a ticket. The method returns a ticket JSON object

Parameters:

NameTypeDescription
idintTicket id

Returns:

{
    "Attachments": [
        {
            "FileName": "icon.png",
            "FileData": null,
            "FileID": 1740828,
            "CommentID": 12722431,
            "CommentDate": "2020-02-28T04:48:00Z",
            "FileHash": null,
            "FileSize": 0,
            "IssueID": 2431395,
            "UserID": 43499,
            "GoogleDriveUrl": null, //cloud URL (google, dropbox, onedrive etc)
            "ForTechsOnly": false,
            "Url": "https://support.jitbit.com/helpdesk/File/Get?id=1740828"
        }
    ],
    "Tags": [
        {
            "TagID": 14502,
            "Name": "tag1",
            "TagCount": 0
        }
    ],
    "Status": "In progress",
    "OnBehalfUserName": null,
    "SubmitterUserInfo": {
        "UserID": 43499,
        //more user info properties
    },
    "CategoryName": "General issues",
    "AssigneeUserInfo": {
        "UserID": 43499,
        //more user info properties
    },
    "TicketID": 2431395,
    "UserID": 43499,
    "AssignedToUserID": 43499,
    "IssueDate": "2020-02-28T04:48:00Z",
    "Subject": "test",
    "Body": "test ticket",
    "Priority": 0,
    "StatusID": 2,
    "CategoryID": 7277,
    "DueDate": null,
    "ResolvedDate": null,
    "StartDate": "2020-02-28T04:48:00Z",
    "TimeSpentInSeconds": 143,
    "UpdatedByUser": false,
    "UpdatedByPerformer": true,
    "UpdatedForTechView": false,
    "IsCurrentUserTechInThisCategory": false,
    "IsCurrentCategoryForTechsOnly": false,
    "SubmittedByCurrentUser": true,
    "IsInKb": false,
    "Stats": null
}

Ticket (POST)

https://[helpdesk-url]/api/ticket

Creates a new ticket

Parameters:

NameTypeDescription
categoryIdintCategory ID
bodystringTicket body
subjectstringTicket subject
priorityIdintTicket priority. Values: <li>-1 – Low</li><li>0 – Normal</li><li>1 – High</li><li>2 – Critical</li>
userId (optional)intUser-ID to create a ticket "on-behalf" of this user (requires technician permissions)
tags (optional)stringA string of tags separated by comma. Example: tags=tag1,tag2,tag3
origin (optional)intWhere the ticket came from, i.e. sets the "via" field for the ticket. Can be one of: 0 (WebApp), 1 (Email), 2 (Widget), 3 (API), 4 (Scheduler), 5 (MobileApp), 6 (Phone), 7 (LiveChat), 8 (InPerson)
assignedToUserId (optional)intUser-ID to assign the ticket to (optional, requires technician permissions)
customFields (optional)stringA JSON-string that contains custom field values for the ticket. Format { "ID1" : "value", "ID2" : "value" } where "ID" is the custom field's ID-number.

This method supports file attachments. To attach a file you need to send a POST request with "Content-Type: multipart/form-data;" with each parameter, including the file, as a separate "part". Search how to do "form data post requests" in your programming language. Example curl call:

curl -F "categoryId=1" -F "body=test" -F "subject=test" -F "priorityId=0" -F "uploadFile=@file.txt"
    -u admin:admin -v http://localhost/helpdesk/api/ticket

Returns

The created ticket ID

UpdateTicket (POST)

https://[helpdesk-url]/api/UpdateTicket

Change ticket parameters, one or many.

The method allows editing your own tickets only (unless you're helpdesk administrator or "technician")

Parameters:

NameTypeDescription
idintTicket ID
categoryIdint(optional) Ticket category
priorityint(optional) Ticket priority. Values: -1 Low, 0 Normal, 1 High, 2 Critical
dateDateTime(optional) Ticket creation date
userIdint(optional) Ticket submitter's user ID
dueDateDateTime(optional) Due date
assignedUserIdint(optional) Assigned technician's ID. Set to 0 (zero) to remove the currently assigned user.
timeSpentInSecondsint(optional) Time spent on the ticket
statusIdint(optional) Ticket status ID. "Closed" id 3, "New" is 1, "In process" is 2. Check your custom status IDs in the admin area
tagsstring(optional) A comma-separated list of tags to apply to the ticket. Like tags=tag1,tag2,tag3. All existing tags will be removed
subjectstring(optional) Ticket subject
bodystring(optional) Ticket body

Returns:

200 OK if there were no errors. Returns an error message otherwise.

Example:

https://[helpdesk-url]/api/UpdateTicket?id=321&dueDate=2018-12-01

SetCustomField (POST)

https://[helpdesk-url]/api/SetCustomField

Sets custom field value in a ticket.

Parameters:

NameTypeDescription
ticketIdintTicket ID
fieldIdintCustom field ID
valuestringValue as a string. For checkboxes pass true or false. For dropdowns pass the option ID. For dates pass date as a string in any format.

Returns:

200 OK if there were no errors. Returns an error message otherwise.

SetCustomFields (POST)

https://[helpdesk-url]/api/SetCustomFields

Sets multiple custom field values in a ticket with one request.

Parameters:

NameTypeDescription
ticketIdintTicket ID
cf12345 (12345 is the custom field id, see example)stringValue as a string. For checkboxes pass true or false. For dropdowns pass the option ID. For dates pass date as a string in any format.

Example request parameters:

ticketId=10556
cf1624=123
cf1625=asd
cf1626=zxc

Returns:

200 OK if there were no errors. Returns an error message otherwise.

Stats

GET https://[helpdesk-url]/api/Stats

Gets overall statistics for the ticketing system - number of open tickets, closed, new, unassigned etc.

Parameters:

None

Returns:

{
    "TotalTickets": 177,
    "Closed": 4,
    "InProcess": 32,
    "NewTickets": 141,
    "Unanswered": 159,
    "Unassigned": 5,
    "Unclosed": 173
}

TicketCustomFields

https://[helpdesk-url]/api/TicketCustomFields?id=123

View all ticket custom fields with their values

Parameters:

NameTypeDescription
idintTicket ID
returnUnsetbool(optional) Return custom fields with unset values (default: false)

Returns:

[
    {
        "FieldName": "Helpdesk URL",
        "FieldID": 2903,
        "Type": 1,
        "UsageType": 0,
        "Value": null,
        "ValueWithOption": null,
        "Mandatory": false
    }
]

Custom field types

Text = 1,
Date = 2,
SelectionCombo = 3,
Checkbox = 4,
MultilineText = 5

Attachment

https://[helpdesk-url]/api/attachment?id=123

Allows you to download an individual file attachment

Parameters:

NameTypeDescription
idintFile attachment ID

Returns:

The requested file attachment as a file. Look at the "Content-Type" header for the file type. You can find the file name in the "Content-disposition" header.

AttachFile (POST)

https://[helpdesk-url]/api/AttachFile

Attaches a file to a ticket

Parameters:

NameTypeDescription
idintTicket ID
multipart filebinaryFile data to upload

To attach a file simply send a POST request with "Content-Type: multipart/form-data;" with each parameter, including the file, as a separate "part". Search how to do "form data post requests" in your programming language. Example curl call:

curl -F "id=1" -F "uploadFile=@myfile.txt" -u admin:admin -v http://localhost/helpdesk/api/AttachFile

AddSubscriber (POST)

https://[helpdesk-url]/api/AddSubscriber

Adds a new subscriber to a ticket

Parameters:

NameTypeDescription
idintTicket ID
userIdintThe new subscriber's user-ID

RemoveSubscriber (POST)

https://[helpdesk-url]/api/RemoveSubscriber

Removes a subscriber from a ticket

Parameters:

NameTypeDescription
idintTicket ID
userIdintThe subscriber's user-ID

Subscribers (GET)

https://[helpdesk-url]/api/Subscribers?id=123

Returns list of subscribers from a ticket

Parameters:

NameTypeDescription
idintTicket ID

Categories

https://[helpdesk-url]/api/categories

Gets all categories the user has permissions to see.

Returns:

 [
    {
        "CategoryID": 7277,
        "Name": "General issues",
        "SectionID": null,
        "Section": null,
        "NameWithSection": "General issues",
        "ForTechsOnly": false,
        "FromAddress": null
    }
]

TechsForCategory

https://[helpdesk-url]/api/TechsForCategory?id=123

Gets all possible assignees for a category

Parameters:

NameTypeDescription
idintCategory ID

Returns:

[
    {
        "UserID": 43499,
        "Username": "Max",
        "FirstName": "Max",
        "LastName": "",
        "TicketsAssigned": 16,
        "FullNameAndLogin": "Max",
        "FullName": "Max"
    }
]

CustomFieldsForCategory

https://[helpdesk-url]/api/CustomFieldsForCategory?categoryId=123

Gets all possible custom field available in this ticket category (along with their "option" for drop-down custom fields)

Parameters:

NameTypeDescription
categoryIdintCategory ID

Returns:

[
    {
        "FieldName": "NAME",
        "FieldID": 123123123,
        "Type": 4,
        "UsageType": 1,
        "ForTechsOnly": false,
        "Mandatory": false,
        "OrderByNumber": 2,
        "ShowInGrid": true,
        "SelectionComboOptions": null
    }
]

MergeTickets

https://[helpdesk-url]/api/MergeTickets

Merge two tickets together. This action is irreversible.

Parameters:

NameTypeDescription
idintPrimary ticket ID
id2intThe merged ticket (the original will be deleted)
https://[helpdesk-url]/api/LinkTickets

Link two tickets together as "related".

Parameters:

NameTypeDescription
idintFirst ticket ID
id2intSecond ticket ID
https://[helpdesk-url]/api/UnlinkTickets

Unlink two tickets.

Parameters:

NameTypeDescription
idintFirst ticket ID
id2intSecond ticket ID

AddSubTicket

https://[helpdesk-url]/api/AddSubTicket

Make one ticket a subticket of another.

Parameters:

NameTypeDescription
parentIdintParent ticket ID
childIdintChild ticket ID

RemoveSubTicket

https://[helpdesk-url]/api/RemoveSubTicket

Remove subticket.

Parameters:

NameTypeDescription
childIdintChild ticket ID

LinkedTickets

https://[helpdesk-url]/api/LinkedTickets?id=123

Returns linked tickets for a given ticket.

Parameters:

NameTypeDescription
idintTicket id

Returns:

[
   {
      "TicketID":123123,
      "Subject":"test",
      "StatusID":2,
      "UpdatedByUser":false,
      "UpdatedByPerformer":true,
      "CompanyID":null,
      "UserID":1,
      "Username":"admin",
      "FirstName":"John",
      "LastName":"Doe",
      "IssueDate":"2020-02-28T04:48:00Z"
   }
]

SubTickets

https://[helpdesk-url]/api/SubTickets?id=123

Returns sub tickets for a given ticket (first level deep)

Parameters:

NameTypeDescription
idintTicket id

Returns:

[
   {
      "IssueID":55280,
      "Priority":0,
      "StatusID":1,
      "IssueDate":"2020-05-12T11:59:50.91Z",
      "Subject":"Some text",
      "Status":"New",
      "UpdatedByUser":false,
      "UpdatedByPerformer":false,
      "CategoryID":2051,
      "UserName":"admin",
      "Technician":null,
      "FirstName":"John",
      "LastName":"Doe",
      "DueDate":null,
      "TechFirstName":null,
      "TechLastName":null,
      "LastUpdated":"2020-06-12T11:33:29.157Z",
      "UpdatedForTechView":false,
      "UserID":1,
      "CompanyID":null,
      "CompanyName":null,
      "AssignedToUserID":null,
      "ResolvedDate":null,
      "SectionID":null,
      "Category":"test copy",
      "Origin":0,
      "Email":"admin@admin.com",
      "HasChildren":false,
      "StatusColor":null,
      "LastUpdatedByUserID":null,
      "LastUpdatedUsername":null
   }
]

ParentTicket

https://[helpdesk-url]/api/ParentTicket?id=123

Returns the parent ticket ID (or zero if not parent ticket found)

Parameters:

NameTypeDescription
idintTicket ID

Returns:

ticket ID as response text (no JSON)

TicketIntegrationData

https://[helpdesk-url]/api/TicketIntegrationData?id=123

Returns all ticket integration data - Jira, Github, etc.

Parameters:

NameTypeDescription
idintTicket id

Returns:

{
	"BitbucketIssueUrl": null,
	"JiraIssueUrl": "https://jira/browse/JB-1",
	"GitHubIssueUrl": null,
	"AsanaTaskUrl": null,
	"TrelloCardUrl": null,
	"VSOWorkItemUrl": null,
	"HarvestProjectUrl": null,
	"GitLabIssueUrl": "https://gitlab.com/empire/deathstar/-/issues/1",
	"BasecampTodoUrl": null
}

TagTicket (POST)

https://[helpdesk-url]/api/TagTicket

Adds a tag to a ticket

Parameters:

NameTypeDescription
namestringTag name (could be new or existing)
ticketIdintThe ticket ID to tag

Comments

API methods that work with ticket comments (AKA replies)

Comment (POST)

https://[helpdesk-url]/api/comment

Posts a comment to a ticket

Parameters:

NameTypeDescription
idintTicket id
bodystringComment body
forTechsOnlybool(optional) If this comment is for techs only. Default: false
isSystembool(optional) If this is a "system" comment (shown in grey). Default: false
recipientIdscomma-separated integers(optional) A list of subscriber user IDs to send the comment notification to. By default it is sent to all subscribers. Default: null
fromUserIdint(optional) the userId from which to post a comment from, required Administrator role

This method supports file attachments. To attach a file you need to send a POST request with "Content-Type: multipart/form-data;" with each parameter, including the file, as a separate "part". Search how to do "form data post requests" in your programming language. Example curl call:

curl -F "id=1" -F "body=test" -F "uploadFile=@file.txt" -u admin:admin -v http://localhost/helpdesk/api/comment

Comments

https://[helpdesk-url]/api/comments?id=123

Gets comments of a specified ticket

Parameters:

NameTypeDescription
idintTicket id

Returns:

 [
    {
        "CommentID": 1828,
        "IssueID": 471,
        "UserID": 1,
        "UserName": "admin",
        "Email": "admin@testmail",
        "FirstName": "",
        "LastName": "",
        "IsSystem": false,
        "CommentDate": "2020-02-28T04:48:00Z",
        "ForTechsOnly": false,
        "Body": "Hi\r\n\r\n",
        "TicketSubject": null,
        "Recipients": ""
    }
 ]

CommentTemplates

https://[helpdesk-url]/api/CommentTemplates

Gets all available "canned responses" from your Helpdesk

Returns:

[{
    "TemplateId": 1420,
    "Body": "You need to set Helpdesk's application pool to run under .NET 4.0 instead of 2.0 in IIS.",
    "Name": "4.0 instead of 2.0"
},
{
    "TemplateId": 362,
    "Body": "Could you please tell me, what app are you talking about exactly?",
    "Name": "Which app??"
}]

Users

Working with helpdesk users - creating, deleting, updating etc.

CreateUser (POST)

https://[helpdesk-url]/api/CreateUser

Creates a new user. Requires "helpdesk-administrator" permissions.

Parameters:

NameTypeDescription
usernamestringusername, should not be taken by another user
passwordstringuser's password
emailstringuser's email
firstNamestring(optional) first name
lastNamestring(optional) surname
phonestring(optional) phone
locationstring(optional) location
companystring(optional) Set user's company. If a company doesn't exist, it will be created.
departmentstring(optional) Set user's department. If department doesn't exist, it will be created.
sendWelcomeEmailbool(optional) Send a "welcome" to the user

Returns:

userId

UpdateUser (POST)

https://[helpdesk-url]/api/UpdateUser?userId=123&username=joe&disabled=false

Updates a user. Requires "helpdesk-administrator" permissions. All parameters except userId are optional

Parameters:

NameTypeDescription
userIdintedited user's ID
usernamestringusername, should not be taken by another user
emailstringuser's email
firstNamestringfirst name
lastNamestringsurname
notesstringoptional administrator's notes
phonestringphone
locationstringlocation
departmentstringuser's department name
disabledboolenable/disable the user
companystringuser's company name
passwordstringuser's new password
enableEmailNotificationsboolenable/disable email notifications for the user
greetingstringThe "greeting" that's added automatically when the user adds reply via web UI
signaturestringThe "signature" that's added automatically when the user replies via web UI
outOfOfficeboolare they "out of office"

DeleteUser (POST)

https://[helpdesk-url]/api/DeleteUser?userId=123

Deletes a user. Requires "helpdesk-administrator" permissions. WARNING: there's no undo.

Parameters:

NameTypeDescription
userIdintthe user's ID

User (GET)

https://[helpdesk-url]/api/User?userId=123

Gets information about a user by their ID.

Parameters:

NameTypeDescription
userIdintthe user's ID

SetCustomFieldForUser (POST)

https://[helpdesk-url]/api/SetCustomFieldForUser

Sets custom field value for a user.

Parameters:

NameTypeDescription
idintUser ID
fieldIdintCustom field ID
valuestringValue as a string. For checkboxes pass true or false. For dropdowns pass the option ID. For dates pass date as a string in any format.

Returns:

200 OK if there were no errors. Returns an error message otherwise.

UserByEmail

https://[helpdesk-url]/api/UserByEmail?email=admin@testmail.com

Gets all information about a user. Requires "helpdesk-administrator" or "technician" permissions.

Parameters:

NameTypeDescription
emailstringemail address

Returns:

{
    "UserID": 43499,
    "Username": "Max",
    "Password": null,
    "Email": "max@test",
    "FirstName": "Max",
    "LastName": "",
    "Notes": "test",
    "Location": "",
    "Phone": "+16463977708",
    "Department": null,
    "CompanyName": "Jitbit Software",
    "IPAddress": "213.229.75.25",
    "HostName": "213.229.75.25",
    "Lang": "en-US",
    "UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.118 Safari/537.36",
    "AvatarURL": null,
    "Signature": "Cheers,\r\nMax",
    "Greeting": "Hi #FirstName#",
    "CompanyId": 451,
    "CompanyNotes": null,
    "IsAdmin": true,
    "Disabled": false,
    "SendEmail": false,
    "IsTech": false,
    "LastSeen": "2020-02-28T04:48:00Z",
    "IsManager": false,
    "PushToken": null,
    "FullNameAndLogin": "Max",
    "FullName": "Max"
}

MergeUsers (POST)

https://[helpdesk-url]/api/MergeUsers?fromUserId=123&toUserId=321

Merges two users together. Requires "helpdesk-administrator" permissions. WARNING: there's no undo.

Parameters:

NameTypeDescription
fromUserIdintthe user ID to merge
toUserIdintthe users ID to merge TO

UserByUsername

https://[helpdesk-url]/api/UserByUsername?username=admin

Gets all information about a user. Requires "administrator" or "technician" permissions.

Parameters:

NameTypeDescription
usernamestringusername

Returns:

{
    "UserID": 43499,
    "Username": "Max",
    "Password": null,
    "Email": "max@test",
    "FirstName": "Max",
    "LastName": "",
    "Notes": "test",
    "Location": "",
    "Phone": "+16463977708",
    "Department": null,
    "CompanyName": "Jitbit Software",
    "IPAddress": "213.229.75.25",
    "HostName": "213.229.75.25",
    "Lang": "en-US",
    "UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.118 Safari/537.36",
    "AvatarURL": null,
    "Signature": "Cheers,\r\nMax",
    "Greeting": "Hi #FirstName#",
    "CompanyId": 451,
    "CompanyNotes": null,
    "IsAdmin": true,
    "Disabled": false,
    "SendEmail": false,
    "IsTech": false,
    "LastSeen": "2020-02-28T04:48:00Z",
    "IsManager": false,
    "PushToken": null,
    "FullNameAndLogin": "Max",
    "FullName": "Max"
}

UserCustomFields

https://[helpdesk-url]/api/UserCustomFields?id=123

View all user custom fields. Available for technicians only.

Parameters:

NameTypeDescription
idintUser ID

Returns:

[
    {
        "FieldName": "User status",
        "FieldID": 1234,
        "Type": 1,
        "Value": "Paying Customer"
    }
]

Users

https://[helpdesk-url]/api/Users

Gets a list of all users in the helpdesk app. Requires "helpdesk-administrator" permissions.

Parameters:

NameTypeDescription
countint(optional) number of users to return. Default: 500
pageint(optional) used to get the next set of users after the first one. So ?count=50 returns the first 50 users and ?count=50&page=2 returns the following 50 users.
listModestring(optional) all (default) all users, techs techs including admins, admins admins only, regular only regular users, disabled - show deactivated users
departmentIdint(optional) return users from a specific department
companyIdint(optional) return users from a specific company

Returns:

[
    {
        "UserID": 321,
        "FirstName": "",
        "LastName": "",
        "Notes": null,
        "Location": "",
        "Phone": "",
        "CompanyName": null,
        "CompanyId": null,
        "DepartmentID": null,
        "LastSeen": null,
        "Username": "123@123.com",
        "Email": "123@123.com",
        "IsAdmin": false,
        "Disabled": false
    }
    //...
]

Companies

https://[helpdesk-url]/api/Companies

Gets a list of all companies. Requires "helpdesk-administrator" permissions.

Returns:

[
    {
        "CompanyID": 1,
        "Name": "test company",
        "EmailDomain": null,
        "Notes": null
    }
    //...
]

Company (POST)

https://[helpdesk-url]/api/Company

Creates a new company. Requires "helpdesk-administrator" permissions.

Parameters:

NameTypeDescription
namestringcompany name
emailDomainsstring(optional) one or more company email domains. Separate multiple values with semicolon like this "empire.com;deathstar.com;vader.com"

Returns:

Created company id or an id of an existing company if the supplied name is taken

UpdateCompany (POST)

https://[helpdesk-url]/api/UpdateCompany

Updates company details. Requires "helpdesk-administrator" permissions.

Parameters:

NameTypeDescription
idintcompany id
namestringcompany name
notesstringcompany notes
emailDomainsstring (optional)email domain list separated by a semicolon (ex. "abc.com;123.com;qwe.com")

Departments

https://[helpdesk-url]/api/Departments

Gets a list of all departments. Requires "helpdesk-administrator" permissions.

Returns:

[
    {
        "DepartmentID": 1,
        "Name": "test name"
    }
    //...
]

Returns:

200 OK if there were no errors. Returns an error message otherwise.

SetCustomFieldForCompany (POST)

https://[helpdesk-url]/api/SetCustomFieldForCompany

Sets custom field value for a company.

Parameters:

NameTypeDescription
idintCompany ID
fieldIdintCustom field ID
valuestringValue as a string. For checkboxes pass true or false. For dropdowns pass the option ID. For dates pass date as a string in any format.

Returns:

200 OK if there were no errors. Returns an error message otherwise.

CompanyCustomFields

https://[helpdesk-url]/api/CompanyCustomFields?id=123

View all company custom fields. Available for technicians only.

Parameters:

NameTypeDescription
idintCompany ID

Returns:

[
    {
        "FieldName": "Company city",
        "FieldID": 1234,
        "Type": 1,
        "Value": "Los Angeles"
    }
]

Knowledge base

API methods to manipulate Knowledge base articles

Articles

https://[helpdesk-url]/api/Articles

Returns a list of your Knowledge base articles with titles, full URLs and other useful information, excluding the actual article content.

Parameters:

NameTypeDescription
categoryIdint(optional) Return articles from a particular category

Returns:

{
    "Articles": [
        {
            "Attachments": [],
            "ArticleId": 6,
            "Subject": "Sample KB article",
            "Body": null,
            "ForTechsOnly": false,
            "CategoryID": 5,
            "CategoryName": null,
            "CategoryNotes": null,
            "TagString": null,
            "UrlId": "6-sample-kb-article",
            "DateCreated": "2016-10-09T05:04:40.89",
            "LastUpdated": null,
            "Url": "http://localhost:3000//KB/View/6-sample-kb-article",
            "Tags": null
        }
        //....
    ],
    "Categories": [
        {
            "CategoryID": 5,
            "Name": "Payment issues",
            "SectionID": 1,
            "Section": "Sales",
            "TicketCount": 1,
            "NameWithSection": "Sales \\ Payment issues",
            "ForTechsOnly": false,
            "ForSpecificUsers": false,
            "FromAddress": null,
            "KBOnly": false
        }
        //...
    ],
    "Tags": []
}

Article

https://[helpdesk-url]/api/Article/{id}

Returns a particular Knowledge Base article along with its content.

Parameters:

NameTypeDescription
idintArticle ID

Returns:

{
    "Attachments": [],
    "ArticleId": 7,
    "Subject": "Another sample KB article",
    "Body": "This is a sample Knowledge Base article, just to give you a clue what it looks like.\r\n\r\n[b]Subtitle[/b]\r\n\r\nHere you can explain the knowledge base article in detail. If applicable, explain how the problem can be worked around.",
    "ForTechsOnly": false,
    "CategoryID": 6,
    "CategoryName": "Pre-sales questions",
    "CategoryNotes": null,
    "TagString": null,
    "UrlId": null,
    "DateCreated": "2016-10-09T05:04:40.893",
    "LastUpdated": "2016-10-09T05:04:40.893",
    "Url": "http://localhost:3000//KB/View/7",
    "Tags": []
}

Article (POST)

https://[helpdesk-url]/api/article

Creates a new Knowledge-base article

Parameters:

NameTypeDescription
categoryIdintCategory ID
bodystringArticle body
subjectstringArticle subject
forTechsOnlystringThe article is for "technicians only"
curl -F "categoryId=1" -F "body=test" -F "subject=test" -u admin:admin -v http://localhost/helpdesk/api/article

Returns

The created Article ID

Automation rules

API methods to manipulate helpdesk automation

Rule

https://[helpdesk-url]/api/Rule/{id}

Returns a particular rule as XML.

Parameters:

NameTypeDescription
idintRule ID

Returns:

<?xml version="1.0" encoding="utf-16"?>
<AutomationRule xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
...
  <Conditions>
...
  </Conditions>
  <Actions>
...
  </Actions>
</AutomationRule>

DisableRule

https://[helpdesk-url]/api/DisableRule/{id}

Disables a particular rule to prevent it from triggering.

Parameters:

NameTypeDescription
idintRule ID

EnableRule

https://[helpdesk-url]/api/EnableRule/{id}

Enables a particular rule that was previously disabled.

Parameters:

NameTypeDescription
idintRule ID

Assets

API Methods to work with assets

Assets (GET)

https://[helpdesk-url]/api/Assets

Returns a list of all assets in your system (50 per page), optionally filtered by assest name.

Parameters:

NameTypeDescription
pageint (optional)page number to return assets from. If you need assets from 51 to 100 - pass "2", etc.
assignedToUserIdint (optional)filter by assigned user ID
assignedToCompanyIdint (optional)filter by assigned company ID
assignedToDepartmentIdint (optional)filter by assigned department ID
assignedToTicketIdint (optional)filter by assigned to ticket ID
nameprefixstring (optional)filter by asset names, that start with this prefix (3 symbols minimum)

Returns:

[
    ...
    {
        "Tickets": null,
        "AssignedUsers": [],
        "Fields": [],
        "Attachments": null,
        "ItemID": 91,
        "Manufacturer": "Apple",
        "Supplier": "none",
        "ModelName": "Macbook",
        "TypeID": 0,
        "Type": "Laptop",
        "ManufacturerID": 0,
        "SupplierID": 0,
        "SerialNumber": null,
        "Location": null,
        "Comments": null,
        "Quantity": 0,
        "TicketCount": 0,
        "Company": null,
        "CompanyID": null
    }
    ...
]

Asset (GET)

https://[helpdesk-url]/api/Asset?id={id}

Get a single asset by ID.

Parameters:

NameTypeDescription
idintasset ID

Returns:

{
    "Tickets": null,
    "AssignedUsers": [],
    "Fields": [],
    "Attachments": null,
    "ItemID": 91,
    "Manufacturer": "Apple",
    "Supplier": "none",
    "ModelName": "Macbook",
    "TypeID": 0,
    "Type": "Laptop",
    "ManufacturerID": 0,
    "SupplierID": 0,
    "SerialNumber": null,
    "Location": null,
    "Comments": null,
    "Quantity": 0,
    "TicketCount": 0,
    "Company": null,
    "CompanyID": null
}

Asset (POST)

https://[helpdesk-url]/api/Asset

Create an asset

Parameters:

NameTypeDescription
modelNamerequired (string)model name
manufacturerrequired (string)manufacturer name
typerequired (string)type
supplierrequired (string)supplier name
serialNumberoptional (string)serial number
locationoptional (string)location
commentsoptional (string)additional comments
quantityoptional (int)quantity (default: 1)
companyIdoptional (int)assign to a company

Returns:

{
    "id": 123
}

SetCustomFieldForAsset (POST)

https://[helpdesk-url]/api/SetCustomFieldForAsset

Sets custom field value in an asset.

Parameters:

NameTypeDescription
idintAsset ID
fieldIdintCustom field ID
valuestringValue as a string. For checkboxes pass true or false. For dropdowns pass the option ID. For dates pass date as a string in any format.

Returns:

200 OK if there were no errors. Returns an error message otherwise.

UpdateAsset (POST)

https://[helpdesk-url]/api/UpdateAsset

Update an existing asset

Parameters:

NameTypeDescription
idrequired (int)asset ID
modelNamerequired (string)model name
manufactureroptional (string)manufacturer name
typeoptional (string)type
supplieroptional (string)supplier name
serialNumberoptional (string)serial number
locationoptional (string)location
commentsoptional (string)additional comments
quantityoptional (int)quantity (default: 1)
companyIdoptional (int)assign to a company

Returns:

{
    "Tickets": null,
    "AssignedUsers": [],
    "Fields": [],
    "Attachments": null,
    "ItemID": 91,
    "Manufacturer": "Apple",
    "Supplier": "none",
    "ModelName": "Macbook",
    "TypeID": 0,
    "Type": "Laptop",
    "ManufacturerID": 0,
    "SupplierID": 0,
    "SerialNumber": null,
    "Location": null,
    "Comments": null,
    "Quantity": 0,
    "TicketCount": 0,
    "Company": null,
    "CompanyID": null
}

AssignAssetToUser (POST)

https://[helpdesk-url]/api/AssignAssetToUser

Assign an asset to a user

Parameters:

NameTypeDescription
assetIdrequired (int)asset ID
userIdrequired (int)user ID

UnAssignAssetToUser (POST)

https://[helpdesk-url]/api/UnAssignAssetToUser

Un-assign an asset from a user

Parameters:

NameTypeDescription
assetIdrequired (int)asset ID
userIdrequired (int)user ID

AddAssetToTicket (POST)

https://[helpdesk-url]/api/AddAssetToTicket

Add an asset to "assets involved" to a ticket

EnableAsset (POST)

https://[helpdesk-url]/api/EnableAsset

Enable an asset

Parameters:

NameTypeDescription
assetIdrequired (int)asset ID

DisableAsset (POST)

https://[helpdesk-url]/api/DisableAsset

Disable an asset

Parameters:

NameTypeDescription
assetIdrequired (int)asset ID

Authentication API

You can also utilize the Authentication API that is included in both the hosted and self-hosted version. Please find more details here

Rate Limiting

Many of the resource-intensive methods in the Help Desk API have rate-limits and throttle abusive clients. Most of the calls are limited to 90 times per minute, while Search and UserByEmail are limited to 60 times per minute. If a client sends more requests, the server either responds with 429 status code or sometimes just serves artificially slow responses. Wait a couple of minutes and try again.

If you're using the self-hosted version you can disable rate limiting by adding this to the "appsettings.json" configuration file:

"DisableRateLimit" : "true",
Previous
Self-hosted installation