Helpdesk API

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

Base address

The API address is:

https://helpdesk-url/api Where [helpdesk-url] 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. All SaaS clients must add "/helpdesk" to the base URL.

Example of the correct URL for SaaS clients:

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

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.) supports basic authentication out of the box without any additional coding. But just in case - here's how you construct the Authorization header:

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=

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.

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. Do not try to use JSON.

Cookies support

We highly recommend using a client that accepts cookies (sent by the server with the response). We cache a lot of secondary non-sensitive data in the "session" so using cookies can and will speed up the API response and ease the load on the server.

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. Please find the available properties on the right.

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.

Name	Type	Description
mode	string	(optional) Allows you to choose, what tickets to show: "all"(default) – 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
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
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. Defalut: 0.

Name	Type	Description
categoryId	int	Category ID
body	string	Ticket body
subject	string	Ticket subject
priorityId	int	Ticket priority. Values: -1 – Low 0 – Normal 1 – High 2 – Critical
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`

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

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.

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.

Name	Type	Description
id	int	Ticket ID
returnUnset	bool	Return custom fields with unset values (default: false)

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

Name	Type	Description
username	string	username, should not be taken by another user
password	string	user's password
email	string	user's email
firstName	string	first name
lastName	string	surname
phone	string	phone
location	string	location
company	string	Set user's company. If the company doesn't exist, it will be created.
department	string	Set user's department. If department doesn't exist, it will be created.
sendWelcomeEmail	bool	Send a "welcome" to the user

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"

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.

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

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)

Name	Type	Description
id	required	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)

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"

Name	Type	Description
id	int	company id
name	string	company name
notes	string	company notes

Name	Type	Description
page	optional	page number to return assets from. If you need assets from 51 to 101 - pass "2", etc.
assignedToUserId	optional	filter by assigned user ID
assignedToCompanyId	optional	filter by assigned company ID
assignedToDepartmentId	optional	filter by assigned company ID