Helpjuice API v3
Documentation on using the Helpjuice.com API V3 (JSON API)
Written by Emir Vatric
Updated at March 24th, 2023
Table of Contents
OverviewBase URLAuthenticationHTTP MethodsSchemaSingle ResourcesCollectionsPaginationErrorsSearchSearch the Knowledge BaseUsersCreate a New userUpdate a userRetrieve a userRetrieve all usersDelete a userDeactivate a userActivate a userGroupsCreate a new groupUpdate a groupRetrieve a groupRetrieve group usersRetrieve all groupsDelete a groupCategoriesCreate a new categoryUpdate a categoryRetrieve a categoryRetrieve all categoriesDelete a categoryArticlesCreate an articleUpdate an articleRetrieve an articleRetrieve all articlesDelete an articleActivitiesRetrieve an activityRetrieve all activitiesSettingsRetrieve account settingsUpdate account settingsOverview
Version 3 of the Helpjuice API is structured around REST, HTTP, and JSON. API endpoint URLs are organized around resources, such as users or articles. It uses HTTP methods for indicating the action to take on a resource, and HTTP status codes for expressing error statuses. Resources are represented in JSON following a conventional schema.
Base URL
The API is accessed using a base URL that is specific to your account. In the examples provided in this documentation, we use the URL youraccountname.helpjuice.com as a stand-in for your real account API URL. In addition, URL paths should begin with api/v3 to specify version 3 of the API. Generally, the URL will be in the form:
https://<your-account>.helpjuice.com/api/v3/<resource>.
Authentication
All requests to the API are authenticated by providing your API key. The API key should be provided as an HTTP header named Authorization or as api_key query parameter. (How do I get my API key).
Remember to keep your API key secret. Do not share it and take care not to expose it publicly in client-side code.
| Param | Value |
|---|---|
| api_key | ffb722a62e8********************** |
Your API key can be found in your account on the Settings/API Credentials page for instructions please visit How do I get my API key. Each account has its own unique API key.
Require token for API? option in your API Credentials settings page needs to be enabled.
User Identification
By default, all API V3 requests are performed as if the account's owner themselves were logged in. However, if you would like to "impersonate" a custom user to restrict content and features the user can use, you can do so by using HTTP Basic Auth. Just provide the user's email as the username and a blank password and Helpjuice will perform the request as if that user were logged in.
This is useful for implementations where you would like to consume the API and provide Helpjuice functionality in a custom way to your users. You can do so by implementing a custom service of your own, behind your own user authentication wall, and proxy requests from your frontend, through your service (which would add the current user's email and your API key) and finally to Helpjuice servers. This way, you keep your private key hidden and have more freedom on how to authenticate users.
HTTP Methods
The v3 API uses standard HTTP methods for indicating the action to take on a resource.
| Method | Action |
|---|---|
| GET | Retrieve a resource |
| POST | Create a new resource |
| PUT | Update a resource |
| DELETE | Remove a resource |
Schema
All API requests and response bodies adhere to a common JSON format representing individual items and collections of items.
Single Resources
Individual resources are represented by top level member named after the resource in the singular form. Below is a representation of a single contact. This could be used in the body of a PUT request and it’s what would be returned in the body of a GET request.
{
"user": {
"email": "jsmith@example.com",
"name": "John Smith",
"first_name": "John",
"last_name": "Smith",
"role_id": "superadmin",
"created_at": "2020-07-08T13:50:20.949Z",
"updated_at": "2020-07-08T13:50:20.949Z"
}
}Collections
Collections of resources are represented by a top level member named after the resource in the plural form. Below is a representation of a collection of contacts.
{
"users": [
{
"email": "jsmith@example.com",
"name": "John Smith",
"first_name": "John",
"last_name": "Smith",
"role_id": "superadmin",
"created_at": "2020-07-08T13:50:20.949Z",
"updated_at": "2020-07-08T13:50:20.949Z"
},
{
"email": "jdoe@example.com",
"name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"role_id": "admin",
"created_at": "2020-07-08T13:50:20.949Z",
"updated_at": "2020-07-08T13:50:20.949Z"
}
]
}Pagination
Endpoints that return collections of resources must limit the number of records returned in a given response. A typical endpoint will return 25 records by default, the query parameter limit can be used to alter the number of records returned.
{
"meta": {
"current": 1,
"limit": 15,
"total_pages": 4,
"total_count": 50
}
}| Parameter | Description |
|---|---|
| Limit | The number of results to display in each page ( default = 25, max = 1000 ). |
| Page | Current page with data. |
Errors
The API uses HTTP status codes to indicate an error has occurred while processing a request. There are four main error status codes used by the API:
| Code | Description |
|---|---|
| 403 | In case the API key is not provided. |
| 404 | In case the requested data does not exist. |
| 422 | The request could not be processed, usually due to a missing or invalid parameter. |
In the case of 422 errors, the response will also include an error object with an explanation of fields that are missing or invalid. Here is an example:
HTTP/1.1 422 Unprocessable Entity { "errors": [ { "email": "is not valid." } ] }Search
Search the Knowledge Base
URL
GET https://<your-account>.helpjuice.com/api/v3/search
FILTERS
| query |
type: String, the query to search by |
| category_id |
type: Integer, searches for articles under this particular category |
RESPONSE raw
{
"searches": [
{
"id": 1,
"name": "Helpjuice Article",
"slug": "111-helpjuice-article",
"tag_names": [],
"answer_sample": "Short answer in few words",
"long_answer_sample": "Longer answer but not a full article",
"categories": {
"current": {
"id": 23,
"name": "Using Helpjuice",
"url": "Url to your category"
}
},
"last_published_date": "July 30th, 2020",
"last_published_user_name": "John Doe",
"is_published": true,
"is_internal": false,
"url": "Url to your article"
}
]
}
Users
Create a New user
URL
POST https://<your-account>.helpjuice.com/api/v3/users
BODY raw
{
"user": {
"first_name": "John",
"last_name": "Doe",
"email": "jhon@doe.com",
"role_id": "admin",
"group_ids": [
1,
2
]
}
}
| Field | Type | Description |
|---|---|---|
| first_name* | String | First name of the user. |
| last_name | String | Last name of the user. |
| email* | String | Unique email of the user. |
| role_id* | String | Role of the user(superadmin, admin, collaborator, draft_writer, viewer) |
| group_ids | Array | Ids of the groups where the user should be joined. |
Update a user
URL
PUT https://<your-account>.helpjuice.com/api/v3/users/:id
BODY raw
{
"user": {
"first_name": "John"
}
}
| Field | Type | Description |
|---|---|---|
| first_name | String | First name of the user. |
| last_name | String | Last name of the user. |
| String | Unique email of the user. | |
| role_id | String | Role of the user(superadmin, admin, collaborator, draft_writer, viewer) |
| group_ids | Array | Ids of the groups where the user should be joined. |
Retrieve a user
URL
GET https://<your-account>.helpjuice.com/api/v3/users/:id
BODY raw
{
"user": {
"first_name": "John",
"last_name": "Doe",
"email": "john@doe.com",
"role_id": "admin"
}
}
Retrieve all users
URL
GET https://<your-account>.helpjuice.com/api/v3/users
BODY raw
{
"users": [
{
"email": "jsmith@example.com",
"firstName": "John",
"lastName": "Smith"
},
{
"email": "alice@example.com",
"firstName": "Alice",
"lastName": "Jones"
}
]
}
Delete a user
URL
DELETE https://<your-account>.helpjuice.com/api/v3/users/:id
Deactivate a user
URL
PUT https://<your-account>.helpjuice.com/api/v3/users/:id/deactivate
BODY raw
{
"user": {
"first_name": "John",
"last_name": "Doe",
"email": "john@doe.com",
"role_id": "admin"
}
}
Activate a user
URL
PUT https://<your-account>.helpjuice.com/api/v3/users/:id/activate
BODY raw
{
"user": {
"first_name": "John",
"last_name": "Doe",
"email": "john@doe.com",
"role_id": "admin"
}
}
Groups
Create a new group
URL
POST https://<your-account>.helpjuice.com/api/v3/groups
BODY raw
{
"group": {
"name": "New Group",
"smart_load": true,
"user_ids": [
1,
2
],
"auto_groups": "@gmail.com, @email.com"
}
}
| Field | Type | Description |
|---|---|---|
| name* | String | Name of the group. |
| smart_load | Boolean | Enable smart loading users in this group. |
| user_ids | Array | Join users to this group. |
| auto_groups | String | A comma-separated string of email extension that will be auto-loaded to this group. smart_load has to be enabled. |
Update a group
URL
PUT https://<your-account>.helpjuice.com/api/v3/groups/:id
BODY raw
{
"group": {
"smart_load": true,
"auto_groups": "@email.com"
}
}
| Field | Type | Description |
|---|---|---|
| name | String | Name of the group. |
| smart_load | Boolean | Enable smart loading users in this group. |
| user_ids | Array | Join users to this group. |
| auto_groups | String | A comma-separated string of email extension that will be auto-loaded to this group. smart_load has to be enabled. |
Retrieve a group
URL
GET https://<your-account>.helpjuice.com/api/v3/groups/:id
BODY raw
{
"group": {
"id": 1,
"name": "new group",
"smart_load": true,
"created_at": "2020-07-29T09:37:03.529Z",
"auto_groups": [
{
"expression": "@gmail.com"
},
{
"expression": "@email.com"
}
],
"users": [
{
"id": 1,
"name": "John Doe",
"role_id": "superadmin"
},
{
"id": 2,
"name": "John Best",
"role_id": "admin"
}
]
}
}
Retrieve group users
URL
GET https://<your-account>.helpjuice.com/api/v3/groups/:id/users?page=1&limit=25
page and limit parameters are optional and will default to the first page and a limit of 25 users
BODY raw
{
"meta": {
"current": 1,
"limit": 25,
"total_page": 185,
"total_count": 4605,
},
"users": [
{
"id": 1,
"name": "John Doe",
"role_id": "superadmin",
},
{
"id": 2,
"name": "John Best",
"role_id": "admin",
}, ...
]
}
Delete
Retrieve all groups
URL
GET https://<your-account>.helpjuice.com/api/v3/groups
BODY raw
{
"groups":[
{
"id":2,
"name":"second group",
"smart_load":false,
"created_at":"2020-07-29T09:37:03.529Z",
"auto_groups":[
],
"users":[
{
"id":1,
"name":"Jhon Doe",
"role_id":"superadmin"
},
{
"id":2,
"name":"Jhon Best",
"role_id":"admin"
}
]
},
{
"id":3,
"name":"new group",
"smart_load":false,
"created_at":"2020-07-29T09:37:03.529Z",
"auto_groups":[
{
"expression":"@gamil.com"
}
],
"users":[
{
"id":1,
"name":"Jhon Doe",
"role_id":"superadmin"
},
{
"id":2,
"name":"Jhon Best",
"role_id":"admin"
}
]
}
]
}
Delete a group
URL
DELETE https://<your-account>.helpjuice.com/api/v3/groups/:id
BODY raw
{
"group": {
"delete_users": false
}
}
| Field | Type | Description |
|---|---|---|
| delete_users | Boolean | Delete users that are inside this group. |
Categories
Create a new category
URL
POST https://<your-account>.helpjuice.com/api/v3/categories
BODY raw
{
"category": {
"parent_id": 1,
"accessibility": 1,
"description": "My Helpjuice category",
"name": "Category",
"codename": "category",
"archived": false,
"user_ids": [
1,
2
],
"group_ids": [
1
]
}
}
| Field | Type | Description |
|---|---|---|
| parent_id | Integer | The ID of the parent category. |
| accessibility | Integer | (public: 1, internal: 0, private: 2) limited the access to articles inside. |
| description | String | Description of the category. |
| name* | String | Name of the category. |
| codename | String | The slug for the category. |
| archived | Boolean | Whether the category is archived or not. |
| user_ids | Array | If accessibility is set to private, these users will have access to it. |
| group_ids | Array | If accessibility is set to private, these group members will have access to it. |
Update a category
URL
PUT https://<your-account>.helpjuice.com/api/v3/categories/:id
BODY raw
{
"category": {
"name": "New Category"
}
}
| Field | Type | Description |
|---|---|---|
| parent_id | Integer | The ID of the parent category. |
| accessibility | Integer | (public: 1, internal: 0, private: 2) limited the access to articles inside. |
| description | String | Description of the category. |
| name | String | Name of the category. |
| codename | String | The slug for the category. |
| archived | Boolean | Whether the category is archived or not. |
| user_ids | Array | If accessibility is set to private, these users will have access to it. |
| group_ids | Array | If accessibility is set to private, these group members will have access to it. |
Retrieve a category
URL
GET https://<your-account>.helpjuice.com/api/v3/categories/:id
BODY raw
{
"category": {
"id": 1,
"name": "Category name",
"codename": "111-category",
"accessibility": 0,
"description": "Description",
"published_questions": [
{
"id": 22,
"name": "Published article",
"url": "Url to your article"
}
],
"draft_questions": [
{
"id": 23,
"name": "Draft article",
"url": "Url to your article"
}
],
"url": "Url to your category"
}
}
Retrieve all categories
URL
GET https://<your-account>.helpjuice.com/api/v3/categories
FILTERS
| segments |
type: Hash. When using segmentation fields |
| language_code |
type: String. For example, en_US. Allows you to filter categories by language |
BODY raw
{
"categories": [
{
"id": 5,
"name": "Category",
"codename": "22-category",
"accessibility": 0,
"description": "Description",
"published_questions": [
{
"id": 22,
"name": "Published article",
"url": "Url to your article"
}
],
"draft_questions": [
{
"id": 23,
"name": "Draft article",
"url": "Url to your article"
}
],
"url": "Url to your category"
},
{
"id": 55,
"name": "Category",
"codename": "55-category",
"accessibility": 0,
"description": "Description",
"published_questions": [
{
"id": 22,
"name": "Published article",
"url": "Url to your article"
}
],
"draft_questions": [
{
"id": 23,
"name": "Draft article",
"url": "Url to your article"
}
],
"url": "Url to your category"
}
]
}
Delete a category
URL
DELETE https://<your-account>.helpjuice.com/api/v3/categories/:id
Articles
Create an article
To create a new article we only need to send parent category ID and we will create a new draft article for you.
URL
POST https://<your-account>.helpjuice.com/api/v3/articles
BODY raw
{
"article":{
"name":"new article",
"description":"This is a new article",
"codename":"new-article",
"visibility_id":0,
"body":"<p>this is the article body</p>",
"published":true,
"category_ids":[
1,
2
],
"user_ids":[
1,
2,
6
],
"group_ids":[
1
],
"contributor_user_ids":[
1,
2
]
}
}
| Field | Type | Description |
|---|---|---|
| name* | String | Name of the article. |
| description | String | Description of the article. |
| codename | String | slug or URL for the article. |
| visibility_id | Integer | (public: 1, internal: 0, private: 2) limited access to the article. |
| body | String | Body of the article. |
| published | Boolean | Whether the article is published or not. |
| category_ids | Array | Categories that the article will appear in. |
| user_ids | Array | If accessibility is set to private, these users will have access to it. |
| group_ids | Array | If accessibility is set to private, these group members will have access to it. |
| contributor_user_ids | Array | Article contributors |
Update an article
URL
PUT https://<your-account>.helpjuice.com/api/v3/articles/:id
BODY raw
{
"article": {
"name": "new article",
"codename": "new-article"
}
}
| Field | Type | Description |
|---|---|---|
| name | String | Name of the article. |
| description | String | Description of the article. |
| codename | String | slug or URL for the article. |
| visibility_id | Integer | (public: 1, internal: 0, private: 2) limited access to the article. |
| body | String | Body of the article. |
| published | Boolean | Whether the article is published or not. |
| category_ids | Array | Categories that the article will appear in. |
| user_ids | Array | If accessibility is set to private, these users will have access to it. |
| group_ids | Array | If accessibility is set to private, these group members will have access to it. |
| contributor_user_ids | Array | Article contributors |
Upvote an article
Use this endpoint to upvote/like an article
URL
PUT https://<your-account>.helpjuice.com/api/v3/articles/:id/upvote
Downvote an article
Use this endpoint to downvote/dislike an article
URL
PUT https://<your-account>.helpjuice.com/api/v3/articles/:id/downvote
Retrieve an article
URL
GET https://<your-account>.helpjuice.com/api/v3/articles/:id
PARAMS
- processed: Provide "true" if you want to see the final processed article body (which expands internal blocks, for example). This is useful in combination with HTTP Basic Auth when you want to render the article for a particular user.
- kb_language: Applicable to articles that have translations. When you provide this parameter, Helpjuice will try to find the translated version of the requested article. If it exists, that version will be returned. Otherwise, the default one will be returned
- Let's say you have an article with ID 100 in English (en_US) and it's also translated to Spanish (es_ES). If you request "/api/v3/articles/100?kb_language=es_ES", then the Spanish version will be returned. Now if you request "/api/v3/articles/100?kb_language=pt_PT", the English version will be returned as you don't have a translation for this article in that language
BODY raw
{
"article": {
"id": 1,
"name": "New Article",
"views": 112,
"accessibility": 0,
"description": "my new article",
"codename": "new-article",
"created_at": "2020-07-29T09:37:03.529Z",
"updated_at": "2020-07-29T09:37:03.529Z",
"published": false,
"answer": [
{
"body": "<p>New Article</p>",
"body_txt": "New Article",
"format": "html",
"updated_at": "2020-07-29T09:37:03.529Z"
}
],
"url": "Url to your article"
}
}
Retrieve all articles
URL
GET https://<your-account>.helpjuice.com/api/v3/articles
FILTERS
| created_since | type: Date, eg. 20-09-2021 |
| category_id |
type: Integer, filters articles under this particular category |
| filter[accessibility] | type: Integer, accepts ( 1 - Public, 0 - Internal, 2 - Private ) |
| filter[is_published] | type: Bool, accepts: ( True, False) |
| filter[language] | type: String, accepts: language shortcode eg. en_us |
BODY raw
{
"articles": [
{
"id": 1,
"name": "New Article",
"views": 112,
"accessibility": 0,
"description": "my new article",
"codename": "new-article",
"created_at": "2020-07-29T09:37:03.529Z",
"updated_at": "2020-07-29T09:37:03.529Z",
"published": false,
"answer": [
{
"body": "<p>New Article</p>",
"body_txt": "New Article",
"format": "html",
"updated_at": "2020-07-29T09:37:03.529Z"
}
],
"url": "Url to your article"
},
{
"id": 2,
"name": "Second Article",
"views": 12,
"accessibility": 0,
"description": "my second article",
"codename": "second-article",
"created_at": "2020-07-29T09:37:03.529Z",
"updated_at": "2020-07-29T09:37:03.529Z",
"published": true,
"answer": [
{
"body": "<p>My Second Article</p>",
"body_txt": "My Second Article",
"format": "html",
"updated_at": "2020-07-29T09:37:03.529Z"
}
],
"url": "Url to your article"
}
]
}
Delete an article
URL
DELETE https://<your-account>.helpjuice.com/api/v3/articles/:id
Activities
Retrieve an activity
URL
GET https://<your-account>.helpjuice.com/api/v3/activities/:id
RESPONSE raw
{
"activity": {
"id": 1,
"trackable_id": 22,
"trackable_type": "Question",
"owner_id": 1,
"action": "create",
"created_at": "2020-07-29T09:37:03.529Z"
}
}
Retrieve all activities
URL
GET https://<your-account>.helpjuice.com/api/v3/activities
FILTERS
| reverse_chronologically |
type: Boolean, returns activities ordered by more recent first. |
| chronologically |
type: Boolean, returns activities ordered by oldest first. |
| filter[owner_id] |
type: Integer, filters by activities done by the user with this id. |
RESPONSE raw
{
"activities": [
{
"id": 1,
"trackable_id": 22,
"trackable_type": "Question",
"owner_id": 1,
"action": "create",
"created_at": "2020-07-29T09:37:03.529Z"
},
{
"id": 2,
"trackable_id": 22,
"trackable_type": "Question",
"owner_id": 1,
"action": "create",
"created_at": "2020-07-29T09:37:03.529Z"
}
]
}
Settings
Retrieve account settings
URL
GET https://<your-account>.helpjuice.com/api/v3/settings/account
RESPONSE raw
{
"account": {
"name": "Your Account",
"subdomain": "your_account",
"internal_kb": false,
"expire_password_after_days": null,
"contact_us_email": "support.youraccount.com",
"contact_us_subject": "[Support] {{ question.name }}",
"contact_us_single_sender": false,
"only_internal_article_requests": false,
"created_at": "2020-07-29T09:37:03.529Z"
}
}
Update account settings
URL
GET https://<your-account>.helpjuice.com/api/v3/settings
RESPONSE raw
{
"settings": {
"name": "Your Account",
"subdomain": "your_account",
"internal_kb": false,
"expire_password_after_days": null,
"contact_us_email": "support.youraccount.com",
"contact_us_subject": "[Support] {{ question.name }}",
"contact_us_single_sender": false,
"only_internal_article_requests": false,
"created_at": "2020-07-29T09:37:03.529Z"
}
}
| Field | Type | Description |
|---|---|---|
| name | String | Name of your account. |
| top_questions_count | Integer | The number of articles that will be shown in your kb. |
| internal_kb | Boolean | Use your kb internally only. |
| expire_password_after_days | Integer | Password expiration for new users, number of days. |
| contact_us_email | String | Support Email address. |
| contact_us_subject | String | Contact us emails, subject line. |
| contact_us_single_sender | Boolean | Send all contact us emails asset in contact_us_email field. |
| only_internal_article_requests | Boolean | Only signed-in users can send Article requests. |