US English (US)
FR French
DE German
SA Arabic
BS Bosnian

Contact Us

If you still have questions or prefer to get help directly from an agent, please submit a request.
We’ll get back to you as soon as possible.

Please fill out the contact form below and we will reply as soon as possible.

  • Book a Demo
  • Product Updates
  • Contact Us
English (US)
US English (US)
FR French
DE German
SA Arabic
BS Bosnian
  • Home
  • API V3

Helpjuice API v3

Documentation on using the Helpjuice.com API V3 (JSON API)

Written by Emir Vatric

Updated at March 24th, 2023

Contact Us

If you still have questions or prefer to get help directly from an agent, please submit a request.
We’ll get back to you as soon as possible.

Please fill out the contact form below and we will reply as soon as possible.

  • Getting Started
    Users Accessibility New to Helpjuice? Start Here Content Management Multiple Languages/Translations & Localization Multilingual Knowledge Bases Analytics Video Tutorials
  • Customization
    Customization Guides
  • API V2
  • API V3
  • Article Editor
  • Swifty (In-App Widget)
  • Billing / Subscription
  • Authentication
+ More

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 settings

Overview

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

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


Delete

Downvote an article

Use this endpoint to downvote/dislike an article

URL

PUT https://<your-account>.helpjuice.com/api/v3/articles/:id/downvote
Delete

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.
 
helpjuice api v3

Was this article helpful?

Yes
No
Give feedback about this article

Related Articles

Copyright © 2023 - Helpjuice

Helpjuice, Inc. is a registered US Corporation, EIN # 45-2275731

Download W9
  • Help
  • Features
  • Pricing
  • About
  • Careers
  • Customers
  • Blog
  • Case Studies
  • Resources
  • Knowledge Base Examples
  • Privacy Policy
  • Terms of Service

Why is the knowledge base important?

With a knowledge base, you can allow your customers to self-help themselves, thus reducing your customer support by up to 60%. Furthermore, you can also have your team get instant answers to the questions they need without having to email themselves all using knowledge base software.

What is the purpose of a knowledge base?

The purpose of knowledge base software is to allow you to host your knowledge base/corporate wiki in one centralized 'hub'. Both your customers, and employees can now access information within seconds!

Made with from Miami, Bosnia, Morocco & Brasil

+1 (833) 387 3877 success@helpjuice.com
Expand