End of Life
Mods for HESK has reached end of life. While your installation will still have the API available, we recommend uninstalling Mods for HESK and switch to HESK 3.
Authentication
Most endpoints require authentication in the form of an X-Auth-Token to help cut down on spam. A token can be generated for a user via the API Settings page in the admin area in your helpdesk. The X-Auth-Token should be passed as a request header.
A future Mods for HESK release will allow:
- the generation of "generic" tokens to be used by an application and will not be required to be associated with a specific helpdesk user.
- the generation of a user-specific token via an API endpoint
Which Endpoints Require Authentication?
Next to the API endpoint title, if there is a key (🔑) next to the URI, then authentication is required.
Dates
Regardless of how dates are formatted in HESK, the REST API will always return dates and times in ISO-8601 format. For example: 2017-03-12 13:59:43, where the time will be in the HESK installation's time zone along with the HESK installation's time offset.
Errors
If an unexpected error occurs on the server, a generic 500 response code will be returned along with the following JSON:
{
"type": "ERROR",
"title": "Exception Occurred",
"message": "Fought an uncaught exception. Check the logs for more information. Log ID: ####"
}
Should another error occur when trying to log (such as a database error), the following JSON will be returned instead:
{
"type": "ERROR",
"title": "Exception Occurred",
"message": "Fought an uncaught exception. Additionally, the error could not be logged! :'("
}
You can check the relevant log by going to the "View Message Log" page in your helpdesk
Passing Custom Fields
If an API endpoint supports saving / updating custom fields, The following API convention is used:
"customFields": {
"#": "customFieldValue"
}
# is the custom field number (1-50). customFieldValue is the string value of the custom field. See the table below for any specific formats that may be required
| Custom Field Type | String Representation |
|---|---|
| text | The value |
| textarea | The value |
| The value | |
| hidden | The value |
| select | The value |
| checkbox | The value |
| radio | The value |
| date | ISO-8601 representation of the date (i.e. January 1, 2017 should be sent as 2017-01-01) |
| readonly | The value |
URL Rewriting
The Mods for HESK API supports URL rewriting. This feature can be enabled via the API settings page.
If you enable URL rewriting, follow the instructions on the popover. Also, the /index.php in the base URL on this site can be omitted if URL rewriting is enabled.