Helpdesk API reference - Jitbit Helpdesk Docs

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:

Username and password are combined into a colon-separated string
```
username:password
```
The resulting string literal is then encoded using Base64
The authorization method and a space i.e. Basic is then put before the encoded string.
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.
For example, if the user has admin username and admin password then the header is formed as follows:
```
Authorization: Basic YWRtaW46YWRtaW4=
```

Example of a curl call:

curl -u admin:password -v http://localhost/helpdesk/api/Ticket?id=1234

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

Response codes

API methods respond with a status code:

200 (OK) - all good
404 (not found) - something is not found. For example, you're getting a user with a non-existing username. Or a ticket with a wrong ID.
400 (bad request) - your request has an error. For example, a required parameter is missing or malformed.
429 (too many requests) - rate-limit is exceeded.

When getting an error code ALWAYS LOOK AT THE RESPONSE BODY it will tell you what went wrong exactly.

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:

Name	Type	Description
mode	string	(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
categoryId	int[]	(optional) Filter by a category, you can pass an array like this: `?categoryId=1&categoryId=2`
sectionId	int	(optional) Filter by a section
statusId	int[]	(optional) Filter by status(es), you can pass an array like this: `?statusId=1&statusId=2`
fromUserId	int	(optional) Filter by a ticket creator
fromCompanyId	int	(optional) Filter by a company
handledByUserID	int	(optional) Filter by a ticket performer
tagName	string	(optional) Filter by ticket a tag
dateFrom	string	(optional) Filter by creation date (date format should be YYYY-MM-DD, for example 2016-11-24)
dateTo	string	(optional) Filter by creation date (date format should be YYYY-MM-DD, for example 2016-11-24)
updatedFrom	string	(optional) Filter by "last updated" date (date format should be YYYY-MM-DD, for example 2016-11-24)
updatedTo	string	(optional) Filter by "last updated" date (date format should be YYYY-MM-DD, for example 2016-11-24)
dueInDays	int	(optional) Filter by "due in X days"
includeCustomFields	bool	(optional) Add custom field values to the output
subscribedOnly	bool	(optional) Only return tickets you are subscribed to
count	int	(optional) How many tickets to return. Default: 10. Max: 300.
offset	int	(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": "2024-05-05T17:25:31.127Z",
		"Subject": "Test ticket",
		"Status": "In progress",
		"UpdatedByUser": false,
		"UpdatedByPerformer": false,
		"CategoryID": 21,
		"UserName": "admin",
		"Technician": null,
		"FirstName": "",
		"LastName": "",
		"DueDate": null,
		"TechFirstName": null,
		"TechLastName": null,
		"LastUpdated": "2024-05-06T10:24:13.873Z",
		"UpdatedForTechView": false,
		"UserID": 20,
		"CompanyID": null,
		"CompanyName": null,
		"AssignedToUserID": 1,
		"ResolvedDate": null,
		"SectionID": null,
		"Category": "test",
		"Origin": "WebApp",
		"Email": "admin@admin.lvm",
		"HasChildren": false,
		"LastUpdatedByUserID": 1,
		"LastUpdatedUsername": "",
		"StartDate": "2024-05-06T10:24:13.887Z"
    },
    //...more tickets
]

Ticket

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

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

Parameters:

Name	Type	Description
id	int	Ticket 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:

Name	Type	Description
categoryId	int	Category ID
body	string	Ticket body
subject	string	Ticket subject
priorityId	int	Ticket priority. Values: <li>-1 – Low</li><li>0 – Normal</li><li>1 – High</li><li>2 – Critical</li>
userId (optional)	int	User-ID to create a ticket "on-behalf" of this user (requires technician permissions)
tags (optional)	string	A string of tags separated by comma. Example: `tags=tag1,tag2,tag3`
origin (optional)	int	Where 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)	int	User-ID to assign the ticket to (optional, requires technician permissions)
customFields (optional)	string	A JSON-string that contains custom field values for the ticket. Format `{ "ID1" : "value", "ID2" : "value" }` where "ID" is the custom field's ID-number.
suppressConfirmation (optional)	bool	Skip sending user confirmation email (useful when creating a ticket on behalf)

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 "priorityId=0" -F "uploadFile=@file.txt"
    -u admin:password -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:

Name	Type	Description
id	int	Ticket ID
categoryId	int	(optional) Ticket category
priority	int	(optional) Ticket priority. Values: `-1` Low, `0` Normal, `1` High, `2` Critical
date	DateTime	(optional) Ticket creation date
userId	int	(optional) Ticket submitter's user ID
dueDate	DateTime	(optional) Due date
assignedUserId	int	(optional) Assigned technician's ID. Set to 0 (zero) to remove the currently assigned user.
timeSpentInSeconds	int	(optional) Time spent on the ticket
statusId	int	(optional) Ticket status ID. "Closed" id 3, "New" is 1, "In process" is 2. Check your custom status IDs in the admin area
tags	string	(optional) A comma-separated list of tags to apply to the ticket. Like `tags=tag1,tag2,tag3`. All existing tags will be removed
subject	string	(optional) Ticket subject
body	string	(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

Close

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

Closes a ticket. This is basically same as calling UpdateTicket with statusId=3. But offers an option to close tickets "silently", skipping email notificaiton.

Parameters:

Name	Type	Description
id	int	Ticket ID
suppressNotification	bool	(optional) Close "silently" without sending email notifications

Returns:

200 OK if there were no errors.

Example:

https://[helpdesk-url]/api/Close?id=321&suppressNotification=true

SetCustomField (POST)

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

Sets custom field value in a ticket.

Parameters:

Name	Type	Description
ticketId	int	Ticket ID
fieldId	int	Custom field ID
value	string	Value 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:

Name	Type	Description
ticketId	int	Ticket ID
cf12345 (12345 is the custom field id, see example)	string	Value 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?forCurrentUser=false

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

Parameters:

Name	Type	Description
forCurrentUser	bool	(optional) whether to return overall stats, or stats available to the current user

Returns:

{
	"TotalTickets": 208,
	"Closed": 22,
	"InProcess": 23,
	"NewTickets": 163,
	"Unanswered": 166,
	"Unassigned": 33,
	"Unclosed": 186,
	"HandledByMe": 153
}

{
	"NewTickets": 163,
	"Unanswered": 166,
	"Unassigned": 33,
	"Unclosed": 186,
	"HandledByMe": 153,
	"SubmittedByMe": 100,
	"InProcess": 23
}

Search

GET https://[helpdesk-url]/api/Search?query=TEXT&dateFrom=2020-12-12&fromUserId=123

Searches for tickets given a search phrase and various other criteria

Parameters:

Name	Type	Description
query	string	Text to search for
fromUserId	int	(optional) filter by ticket creator
categoryId	int[]	(optional) filter by category, you can pass an array like this: `?categoryId=1&categoryId=2`
statusId	int[]	(optional) filter by status
assignedToUserId	int	(optional) filter by assigned technician
dateFrom	datetime	(optional) ticket creation date
dateTo	datetime	(optional) ticket creation date

TicketCustomFields

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

View all ticket custom fields with their values

Parameters:

Name	Type	Description
id	int	Ticket ID
returnUnset	bool	(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:

Name	Type	Description
id	int	File 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:

Name	Type	Description
id	int	Ticket ID
multipart file	binary	File 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:password -v http://localhost/helpdesk/api/AttachFile

DeleteFile (GET)

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

Deletes a file from a ticket. Requires "helpdesk-administrator" permissions.

Parameters:

Name	Type	Description
id	int	File ID

Example curl call:

curl -u admin:password -v http://localhost/helpdesk/api/DeleteFile/1233

AddSubscriber (POST)

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

Adds a new subscriber to a ticket

Parameters:

Name	Type	Description
id	int	Ticket ID
userId	int	The new subscriber's user-ID

RemoveSubscriber (POST)

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

Removes a subscriber from a ticket

Parameters:

Name	Type	Description
id	int	Ticket ID
userId	int	The subscriber's user-ID

Subscribers (GET)

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

Returns list of subscribers from a ticket

Parameters:

Name	Type	Description
id	int	Ticket ID

TechsForCategory

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

Gets all possible assignees for a category

Parameters:

Name	Type	Description
id	int	Category 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:

Name	Type	Description
categoryId	int	Category 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:

Name	Type	Description
id	int	Primary ticket ID
id2	int	The merged ticket (the original will be deleted)

LinkTickets

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

Link two tickets together as "related".

Parameters:

Name	Type	Description
id	int	First ticket ID
id2	int	Second ticket ID

UnlinkTickets

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

Unlink two tickets.

Parameters:

Name	Type	Description
id	int	First ticket ID
id2	int	Second ticket ID

AddSubTicket

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

Make one ticket a subticket of another.

Parameters:

Name	Type	Description
parentId	int	Parent ticket ID
childId	int	Child ticket ID

RemoveSubTicket

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

Remove subticket.

Parameters:

Name	Type	Description
childId	int	Child ticket ID

LinkedTickets

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

Returns linked tickets for a given ticket.

Parameters:

Name	Type	Description
id	int	Ticket 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:

Name	Type	Description
id	int	Ticket 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:

Name	Type	Description
id	int	Ticket ID
returnFullTicket	bool	(optional) If true, returns the full ticket JSON details

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:

Name	Type	Description
id	int	Ticket 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:

Name	Type	Description
name	string	Tag name (could be new or existing)
ticketId	int	The 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:

Name	Type	Description
id	int	Ticket id
body	string	Comment body
forTechsOnly	bool	(optional) If this comment is for techs only. Default: false
isSystem	bool	(optional) If this is a "system" comment (shown in grey). Default: false
recipientIds	comma-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
fromUserId	int	(optional) the userId from which to post a comment from, required Administrator role

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

Comments

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

Gets comments of a specified ticket

Parameters:

Name	Type	Description
id	int	Ticket 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:

Name	Type	Description
email	string	user's email, should not be taken by another user
username	string	(optional) username, should not be taken by another user. If omitted, the app will use the `email` parameter
password	string	(optional) user's password (if not specified the helpdesk app will create a default strong password)
firstName	string	(optional) first name
lastName	string	(optional) surname
phone	string	(optional) phone
location	string	(optional) location
company	string	(optional) Set user's company. If a company doesn't exist, it will be created.
department	string	(optional) Set user's department. If department doesn't exist, it will be created.
sendWelcomeEmail	bool	(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:

Name	Type	Description
userId	int	edited user's ID
username	string	username, should not be taken by another user
email	string	user's email
firstName	string	first name
lastName	string	surname
notes	string	optional administrator's notes
phone	string	phone
location	string	location
department	string	user's department name
disabled	bool	enable/disable the user
company	string	user's company name
password	string	user's new password
enableEmailNotifications	bool	enable/disable email notifications for the user
greeting	string	The "greeting" that's added automatically when the user adds reply via web UI
signature	string	The "signature" that's added automatically when the user replies via web UI
outOfOffice	bool	are 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:

Name	Type	Description
userId	int	the user's ID

User (GET)

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

Gets information about a user by their ID.

Parameters:

Name	Type	Description
userId	int	the user's ID

SetCustomFieldForUser (POST)

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

Sets custom field value for a user.

Parameters:

Name	Type	Description
id	int	User ID
fieldId	int	Custom field ID
value	string	Value 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:

Name	Type	Description
email	string	email 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:

Name	Type	Description
fromUserId	int	the user ID to merge
toUserId	int	the 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:

Name	Type	Description
username	string	username

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:

Name	Type	Description
id	int	User 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:

Name	Type	Description
count	int	(optional) number of users to return. Default: 500
page	int	(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.
listMode	string	(optional) `all` (default) all users, `techs` techs including admins, `admins` admins only, `regular` only regular users, `disabled` - show deactivated users
departmentId	int	(optional) return users from a specific department
companyId	int	(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
    }
    //...
]

AddCategoryTechPermission

https://[helpdesk-url]/api/AddCategoryTechPermission?userId=123&categoryId=321

Make user a "technician" in a category. Available for admins only.

Parameters:

Name	Type	Description
userId	int	User ID
categoryId	int	Category's ID

RemoveCategoryTechPermission

https://[helpdesk-url]/api/RemoveCategoryTechPermission?userId=123&categoryId=321

Revoke "technician" permission form a user in a category. Available for admins only.

Parameters:

Name	Type	Description
userId	int	User ID
categoryId	int	Category's ID

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:

Name	Type	Description
name	string	company name
emailDomains	string	(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:

Name	Type	Description
id	int	company id
name	string	company name
notes	string	company notes
emailDomains	string (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:

Name	Type	Description
id	int	Company ID
fieldId	int	Custom field ID
value	string	Value 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:

Name	Type	Description
id	int	Company 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:

Name	Type	Description
categoryId	int	(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:

Name	Type	Description
id	int	Article 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:

Name	Type	Description
categoryId	int	Category ID
body	string	Article body
subject	string	Article subject
forTechsOnly	string	The 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:

Name	Type	Description
id	int	Rule 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:

Name	Type	Description
id	int	Rule ID

EnableRule

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

Enables a particular rule that was previously disabled.

Parameters:

Name	Type	Description
id	int	Rule ID

Custom fields

API Methods to work with custom fields

CustomFields (GET)

https://[helpdesk-url]/api/CustomFields?type=[1,2,3,4]

Returns a list of all custom fields in your system - ticket custom fields, user custom fields, assets custom fields etc.

Parameters:

Name	Type	Description
type	int	Custom field usage type: 1 - for Tickets, 2 - for Assets, 3 - for Users, 4 - for Companies

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:

Name	Type	Description
page	int (optional)	page number to return assets from. If you need assets from 51 to 100 - pass "2", etc.
assignedToUserId	int (optional)	filter by assigned user ID
assignedToCompanyId	int (optional)	filter by assigned company ID
assignedToDepartmentId	int (optional)	filter by assigned department ID
assignedToTicketId	int (optional)	filter by assigned to ticket ID
nameprefix	string (optional)	filter by asset names, that start with this prefix (3 symbols minimum)
includeDisabled	bool (optional)	show retired (disabled) assets

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:

Name	Type	Description
id	int	asset 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:

Name	Type	Description
modelName	required (string)	model name
manufacturer	required (string)	manufacturer name
type	required (string)	type
supplier	required (string)	supplier name
serialNumber	optional (string)	serial number
location	optional (string)	location
comments	optional (string)	additional comments
quantity	optional (int)	quantity (default: 1)
companyId	optional (int)	assign to a company

Returns:

{
    "id": 123
}

SetCustomFieldForAsset (POST)

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

Sets custom field value in an asset.

Parameters:

Name	Type	Description
id	int	Asset ID
fieldId	int	Custom field ID
value	string	Value 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:

Name	Type	Description
id	required (int)	asset ID
modelName	required (string)	model name
manufacturer	optional (string)	manufacturer name
type	optional (string)	type
supplier	optional (string)	supplier name
serialNumber	optional (string)	serial number
location	optional (string)	location
comments	optional (string)	additional comments
quantity	optional (int)	quantity (default: 1)
companyId	optional (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:

Name	Type	Description
assetId	required (int)	asset ID
userId	required (int)	user ID

UnAssignAssetToUser (POST)

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

Un-assign an asset from a user

Parameters:

Name	Type	Description
assetId	required (int)	asset ID
userId	required (int)	user ID

AddAssetToTicket (POST)

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

Add an asset to "assets involved" to a ticket

Name	Type	Description
assetId	required (int)	asset ID
ticketID	required (int)	ticket ID

RemoveAssetFromTicket (POST)

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

Removes a relates assets from a ticket

Name	Type	Description
assetId	required (int)	asset ID
ticketID	required (int)	ticket ID

EnableAsset (POST)

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

Enable an asset

Parameters:

Name	Type	Description
assetId	required (int)	asset ID

DisableAsset (POST)

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

Disable an asset

Parameters:

Name	Type	Description
assetId	required (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",