Helpdesk API

Helpdesk API

Jitbit web-based help desk ticketing system includes a “RESTful” web-service that can be called from external apps (inbound integration) and API hooks that can call external apps (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 hosted clients must add “/helpdesk” to the base URL.

Example of the correct URL:

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

Basic authentication

Every API action checks the user’s permissions to perform the action (see tickets, post comments) etc. You must authenticate as a helpdesk user by sending basic authorization headers with every call, more on that later.

All the methods use basic authentication. You need to pass the Authorization header with every API call.

Most of http-client software (like the “curl” tool etc.”) supports basic authentication without any additional coding. But just in case: here’s how you construct the Authorization header:

  1. Username and password are combined into a 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 local helpdesk install you still have to use Basic auth headers! And pas your Windows usernames and passwords. And 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:

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

Authorization: Basic YWRtaW46YWRtaW4=

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.

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.

General methods

Authorization (POST)

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

Use this method to simply test if you pass correct authorization headers. The method returns a helpdesk “user” JSON object (as a string) that represents the current user. Please find the available properties on the right.

Returns:

{
    "UserID": 1,
    "Username": "admin",
    "Email": "[email protected]",
    "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": "/Date(1360748934770)/",
    "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 (otional) 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 (otional) Filter by a category
    sectionId int (otional) Filter by a section
    statusId int (otional) Filter by a status
    fromUserid int (otional) Filter by a ticket creator
    fromCompanyId int (otional) Filter by a company
    handledByUserID int (otional) Filter by a ticket performer
    tagName string (otional) Filter by ticket a tag
    dateFrom string (otional) Filter by creation date (date format should be YYYY-MM-DD, for example 2016-11-24)
    dateTo string (otional) Filter by creation date (date format should be YYYY-MM-DD, for example 2016-11-24)
    updatedFrom string (otional) Filter by “last updated” date (date format should be YYYY-MM-DD, for example 2016-11-24)
    updatedTo string (otional) Filter by “last updated” date (date format should be YYYY-MM-DD, for example 2016-11-24)
    count int (otional) How many tickets to return. Default: 10. Max: 100.
    offset int (otional) Use this to create paging. For example “offset=20&count=20” will return the next 20 tickets after the first 20. Defalut: 0.

    Returns

    [
        {
            "IssueID": 382,
            "Priority": 0,
            "StatusID": 1,
            "IssueDate": "20130111T15: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": "20130111T15: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

    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": "/Date(1428513969800)/",
                "FileHash": null,
                "FileSize": 0,
                "IssueID": 2431395,
                "UserID": 43499,
                "GoogleDriveUrl": null,
                "DropboxUrl": null,
                "ForTechsOnly": false,
                "Url": "https://support.jitbit.com/helpdesk//helpdesk/GetAttachment.ashx?FileID=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": "/Date(1428513709633)/",
        "Subject": "test",
        "Body": "test ticket",
        "Priority": 0,
        "StatusID": 2,
        "CategoryID": 7277,
        "DueDate": null,
        "ResolvedDate": null,
        "StartDate": "/Date(1428513969817)/",
        "TimeSpentInSeconds": 143,
        "UpdatedByUser": false,
        "UpdatedByPerformer": true,
        "UpdatedForTechView": false,
        "IsCurrentUserTechInThisCategory": false,
        "IsCurrentCategoryForTechsOnly": false,
        "SubmittedByCurrentUser": true,
        "IsInKb": false,
        "Stats": null
    }

    Ticket (POST)

    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:
  • -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

    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 "[email protected]" -u admin:admin -v http://localhost/helpdesk/api/ticket

    Returns

    The created ticket ID

    UpdateTicket (POST)

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

    Change ticket parameters, one or many.

    Parameters:

    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
    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

    Returns:

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

    Example:

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

    SetCustomField (POST)

    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.

    TicketCustomFields

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

    View all ticket custom fields with their values

    Parameters:

    Name Type Description
    id int Ticket ID

    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

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

    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.

    Categories

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

    Gets all categories the user has permissions to see.

    Parameters:

    None

    Returns:

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

    TechsForCategory

    GET 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"
        }
    ]

    Comments

    API methods that work with ticket comments (AKA replies)

    Comment (POST)

    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 If this comment is for techs only. Default: false

    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 "[email protected]" -u admin:admin -v http://localhost/helpdesk/api/comment

    Comments

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

    Gets comments of a specified ticket

    Parameters:

    Name Type Description
    id int Ticket id

    Returns:

     [
        {
            "CommentID": 1828,
            "IssueID": 471,
            "UserID": 1,
            "UserName": "admin",
            "Email": "[email protected]",
            "FirstName": "",
            "LastName": "",
            "IsSystem": false,
            "CommentDate": "/Date(1360750914287)/",
            "ForTechsOnly": false,
            "Body": "Hi\r\n\r\n",
            "TicketSubject": null,
            "Recipients": "",
            "Attachments": []
        }
     ]

    CommentTemplates

    GET 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)

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

    Creates a new user

    Parameters:

    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

    Returns: userId

    UpdateUser (POST)

    POST https://[helpdesk-url]/api/UpdateUser Updates a user

    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

    UserByEmail

    GET https://[helpdesk-url]/api/[email protected]

    Gets all information about a user

    Parameters:

    Name|Type|Description email|string|email address

    Returns:

    {
        "UserID": 43499,
        "Username": "Max",
        "Password": null,
        "Email": "maxt3[email protected]",
        "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,
        "CRMID": 2200,
        "CompanyNotes": null,
        "IsAdmin": true,
        "Disabled": false,
        "SendEmail": false,
        "IsTech": false,
        "LastSeen": "/Date(1428513697957)/",
        "IsManager": false,
        "PushToken": null,
        "FullNameAndLogin": "Max",
        "FullName": "Max"
    }

    Users

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

    Gets a list of all users in the helpdesk app

    Parameters:

    Name Type Description
    count int number of users to return. Default: 500
    page int 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
  • “all” (default) - all users
  • “techs” - techs including admins
  • “admins” - admins only
  • “regular” - only regular users
  • Returns:

    [
        {
            "UserID": 321,
            "FirstName": "",
            "LastName": "",
            "Notes": null,
            "Location": "",
            "Phone": "",
            "CompanyName": null,
            "IPAddress": null,
            "HostName": null,
            "Lang": null,
            "UserAgent": null,
            "AvatarURL": null,
            "Signature": null,
            "Greeting": null,
            "CompanyId": null,
            "DepartmentID": null,
            "CompanyNotes": null,
            "SendEmail": true,
            "IsTech": false,
            "LastSeen": null,
            "RecentTickets": null,
            "IsManager": false,
            "PushToken": null,
            "PushPlatform": null,
            "TwoFactorAuthEnabled": false,
            "TimezoneID": null,
            "FullNameAndLogin": "123@123.com",
            "FullName": "123@123.com",
            "Username": "123@123.com",
            "Password": null,
            "Email": "123@123.com",
            "IsAdmin": false,
            "Disabled": false
        }
        //...
    ]

    Companies

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

    Gets a list of all companies

    Returns:

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

    Company (POST)

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

    Creates a new company

    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 was taken

    Knowledge base

    API methods to manipulate Knowledge base articles

    Articles

    GET 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

    GET https://[helpdesk-url]/api/Article/%id%

    Returns a particular Knowledge Base article along with its content.

    Parameters:

    Name Type Description
    id required 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": []
    }

    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: https://www.jitbit.com/hosted-helpdesk/hosted-help-desk-authentication-api/

    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 makes more requests, the server responds with 429 status code. Wait a couple of minutes and try again.