Sign in →

Get started with the Hellonext API

The Hellonext API allows you to access to almost all aspects of the platform via JSON. All read requests are authenticated only with an API key, whereas other requests require a JWT token to be present.

Generating your API Key and JWT Token

  1. Navigate to the “Advanced” settings page.

Dashboard > Organization Settings > Advanced

  1. Click on the “Generate” button in the API Key section. Copy the generated token.

Generate API Token

  1. This token will need to be sent in the header section of every read-only API request.
header["API-KEY"] = "mnBJtoViAeO2yb2PS7sF8Q";
  1. In case you use the API to make write/update/delete calls, you must also send an additional Authorization parameter. For this navigate to the “Single Sign-On” section and generate an SSO Key. Use this key to generate a unique JWT token for each user who accesses an API endpoint.

Generate SSO Key

header["Authorization"] = "3IIlJZNFukq3BRh76_aw4Q";
  1. Finally, all requests must have the following headers set to return a JSON response.
  • Must have a Content-Type header set to application/json
  • Must have a Accept header set to application/json

Organization

Get Information

This endpoint helps you extract organization information such as name, profile picture, submission form configuration and more.

HTTP Request

GET https://app.hellonext.co/api/v3/organizations/info

Headers

Parameter Default Description
API-KEY - Generate from organization settings on the admin dashboard.

success.json

{
  "success": true,
  "organization": {
    "subdomain": "feedback",
    "name": "Hellonext",
    "description": "",
    "home_page": "http://feedback.hellonext.co/",
    "avatar": null,
    "brand_colors": {
      "primary": "#4353FF",
      "primary_light": "#C8C8FF",
      "primary_dark": "#3947D9"
    }
  },
  "form": {
    "description": "Have something to say? Join the conversation.",
    "submit_button_text": "New Post"
  }
}

Boards

List All Boards

This endpoint retrieves all boards.

HTTP Request

GET https://app.hellonext.co/api/v3/buckets

Headers

Parameter Default Description
API-KEY - Generate from organization settings on the admin dashboard.

Query Parameters

Parameter Default Description
page 1 Used to paginate responses.
sort desc Set to asc to retrieve boards ordered by alphabetically ordered by ascending name.
privacy public Private boards are not returned by default. Set to private to retrieve private boards.
{
  "success": true,
  "buckets": [
    {
      "id": 1,
      "slug": "feedback",
      "name": "Feedback",
      "default": true,
      "private": false,
      "read_only": false
    },
    {
      "id": 2,
      "slug": "Bugs & Fixes",
      "name": "bugs",
      "default": false,
      "private": false,
      "read_only": false
    },
    {
      "id": 3,
      "slug": "Integrations Support",
      "name": "integrations-support",
      "default": false,
      "private": false,
      "read_only": false
    }
  ]
}

Get A Board

This endpoint retrieves a specific board.

HTTP Request

GET https://app.hellonext.co/api/v3/buckets/:id

Headers

Parameter Default Description
API-KEY - Generate from organization settings on the admin dashboard.
ALLOW-PRIVATE false Set to true if retrieving a private boards.

Query Parameters

Parameter Default Description
id - The ID of the board returned in the list boards endpoint.
{
  "success": true,
  "id": 1,
  "slug": "feedback",
  "name": "Feedback",
  "default": true,
  "private": false,
  "read_only": false,
  "form": {
    "description": null,
    "details": "Your Thoughts",
    "details_placeholder": "Remember, the more you tell, the more we know.",
    "heading": "New Submission",
    "title": "Title",
    "title_placeholder": "Title of your submission",
    "hello_sentence": null,
    "submission_template": null,
    "submit_button_text": "New Post"
  }
}

Create A Board

This endpoint allows only members and admins to create a board.

HTTP Request

POST https://app.hellonext.co/api/v3/buckets

Headers

Parameter Default Description
API-KEY - Generate from organization settings on the admin dashboard.
Authorization - Generate a unique JWT token specific to a user.

Body Parameters

Parameter Required Format Description
name true String Name of the board (also used to create the slug).
description false Text Explain what this board will be used to collect.
private false Boolean Only members and admins can access private boards.
default false Boolean Only one default board can exist. Setting this to true, will reset the previously default board.
read_only false Boolean Submissions are not allowed for this board.
form_heading false String Displayed on the form modal.
form_description false Text Rules for the submission.
form_title false String Help-text for the post title.
form_title_placeholder false String Placeholder for the post title.
form_details false String Help-text to explain what additional information you expect the user to submit.
form_details_placeholder false String Placeholder for the details section of the form.
submission_template false Text A guide for submitters when they submit a post. Will be displayed on the form details text box.
submit_button_text false String Text that is displayed on the submit button.
{
  "success": true,
  "id": 1,
  "slug": "feedback",
  "name": "Feedback",
  "default": true,
  "private": false,
  "read_only": false,
  "form": {
    "description": null,
    "details": "Your Thoughts",
    "details_placeholder": "Remember, the more you tell, the more we know.",
    "heading": "New Submission",
    "title": "Title",
    "title_placeholder": "Title of your submission",
    "hello_sentence": null,
    "submission_template": null,
    "submit_button_text": "New Post"
  }
}

Update A Board

This endpoint allows only members and admins to update a board.

HTTP Request

PUT https://app.hellonext.co/api/v3/buckets/:id

Headers

Parameter Default Description
API-KEY - Generate from organization settings on the admin dashboard.
ALLOW-PRIVATE false Set to true if updating a private board.
Authorization - Generate a unique JWT token specific to a user.

Body Parameters

Parameter Required Format Description
name true String Name of the board (also used to create the slug).
description false Text Explain what this board will be used to collect.
private false Boolean Only members and admins can access private boards.
default false Boolean Only one default board can exist. Setting this to true, will reset the previously default board.
read_only false Boolean Submissions are not allowed for this board.
form_heading false String Displayed on the form modal.
form_description false Text Rules for the submission.
form_title false String Help-text for the post title.
form_title_placeholder false String Placeholder for the post title.
form_details false String Help-text to explain what additional information you expect the user to submit.
form_details_placeholder false String Placeholder for the details section of the form.
submission_template false Text A guide for submitters when they submit a post. Will be displayed on the form details text box.
submit_button_text false String Text that is displayed on the submit button.
{
  "success": true,
  "id": 1,
  "slug": "feedback",
  "name": "Feedback",
  "default": true,
  "private": false,
  "read_only": false,
  "form": {
    "description": null,
    "details": "Your Thoughts",
    "details_placeholder": "Remember, the more you tell, the more we know.",
    "heading": "New Submission",
    "title": "Title",
    "title_placeholder": "Title of your submission",
    "hello_sentence": null,
    "submission_template": null,
    "submit_button_text": "New Post"
  }
}

Delete A Board

This endpoint allows only members and admins to delete a board.

HTTP Request

DELETE https://app.hellonext.co/api/v3/buckets/:id

Headers

Parameter Default Description
API-KEY - Generate from organization settings on the admin dashboard.
ALLOW-PRIVATE false Set to true if deleting a private board.
Authorization - Generate a unique JWT token specific to a user.
{
  "success": true
}

Posts

List All Posts

This endpoint retrieves all posts.

HTTP Request

GET https://app.hellonext.co/api/v3/feature_requests

Headers

Parameter Default Description
API-KEY - Generate from organization settings on the admin dashboard.
ALLOW-PRIVATE false Set to true if filtering out a private board’s posts.

Query Parameters

Parameter Default Description
page 1 Used to paginate responses.
bucket_id - Filter out a specific board’s posts by setting the board ID. Needs ALLOW-PRIVATE header to be set if it is a private board ID.
sort - Can be set to either, top, etc, latest_created_at, oldest_created_at, latest_updated_at or oldest_updated_at.
{
  "success": true,
  "feature_requests": [
    {
      "id": 4229,
      "slug": "john-smith",
      "title": "John Smith",
      "preview": "John Smith",
      "description": "This is a dummy description. \n\n",
      "description_html": "<p>This is a dummy description.</p>",
      "status": "In Progress",
      "url": "https://feedback.hellonext.co/b/api/p/john-smith",
      "submitter": "swaathi",
      "bucket": {
        "id": 14,
        "name": "API"
      },
      "votes_count": 0,
      "downvotes_count": 0,
      "comments_count": 0,
      "created_at": "2021-10-20T13:58:49.000Z",
      "updated_at": "2021-10-20T13:58:49.000Z"
    },
    {
      "id": 4229,
      "slug": "chrissy-smith",
      "title": "Chrissy Smith",
      "preview": "Chrissy Smith",
      "description": "This is a description for dummies. \n\n",
      "description_html": "<p>This is a description for dummies.</p>",
      "status": "Submitted",
      "url": "https://feedback.hellonext.co/b/api/p/chrissy-smith",
      "submitter": "swaathi",
      "bucket": {
        "id": 14,
        "name": "API"
      },
      "votes_count": 0,
      "downvotes_count": 0,
      "comments_count": 0,
      "created_at": "2021-10-20T13:58:49.000Z",
      "updated_at": "2021-10-20T13:58:49.000Z"
    }
  ]
}

Get A Post

This endpoint retrieves a specific post.

HTTP Request

GET https://app.hellonext.co/api/v3/feature_requests/:id

Headers

Parameter Default Description
API-KEY - Generate from organization settings on the admin dashboard.
ALLOW-PRIVATE false Set to true if retrieving a post in a private board.

Query Parameters

Parameter Default Description
id - The ID of the post returned in the list posts endpoint.
{
  "id": 4229,
  "slug": "chrissy-smith",
  "title": "Chrissy Smith",
  "preview": "Chrissy Smith",
  "description": "This is a description for dummies. \n\n",
  "description_html": "<p>This is a description for dummies.</p>",
  "status": "Submitted",
  "url": "https://feedback.hellonext.co/b/api/p/chrissy-smith",
  "submitter": "swaathi",
  "bucket": {
    "id": 14,
    "name": "API"
  },
  "votes_count": 0,
  "downvotes_count": 0,
  "comments_count": 0,
  "created_at": "2021-10-20T13:58:49.000Z",
  "updated_at": "2021-10-20T13:58:49.000Z"
}

Create A Post

This endpoint allows anyone to create a post.

HTTP Request

POST https://app.hellonext.co/api/v3/feature_requests

Headers

Parameter Default Description
API-KEY - Generate from organization settings on the admin dashboard.
ALLOW-PRIVATE false Set to true if submitting a post in a private board.
Authorization - Generate a unique JWT token specific to a user.

Body Parameters

Parameter Required Format Description
title true String Title of the post (also used to create the slug).
description false Text Details of the post (can be in HTML).
bucket_id true Integer Valid board ID. Needs ALLOW-PRIVATE header to be set if it is a private board ID.
{
  "id": 4230,
  "slug": "hello-world",
  "title": "Hello world",
  "preview": "",
  "description": null,
  "description_html": null,
  "status": "Submitted",
  "url": "https://feedback.hellonext.co/b/api/p/hello-world",
  "submitter": "Swaathi",
  "bucket": {
    "id": 14,
    "name": "API"
  },
  "votes_count": 0,
  "downvotes_count": 0,
  "comments_count": 0,
  "created_at": "2021-10-21T10:58:30.000Z",
  "updated_at": "2021-10-21T10:58:31.000Z"
}

[DEPRECATED] Submit

This endpoint allows anyone to submit a post.

This is a deprecated API endpoint and will be decommissioned soon. Do not use.

HTTP Request

POST https://app.hellonext.co/api/v3/feature_requests/submit

Headers

Parameter Default Description
API-KEY - Generate from organization settings on the admin dashboard.
ALLOW-PRIVATE false Set to true if submitting a post in a private board.

Body Parameters

Parameter Required Format Description
title true String Title of the post (also used to create the slug).
description false Text Details of the post (can be in HTML).
bucket_id true Integer Valid board ID. Needs ALLOW-PRIVATE header to be set if it is a private board ID.
email true String Email address of the submitter.
{
  "id": 4230,
  "slug": "hello-world",
  "title": "Hello world",
  "preview": "",
  "description": null,
  "description_html": null,
  "status": "Submitted",
  "url": "https://feedback.hellonext.co/b/api/p/hello-world",
  "submitter": "Swaathi",
  "bucket": {
    "id": 14,
    "name": "API"
  },
  "votes_count": 0,
  "downvotes_count": 0,
  "comments_count": 0,
  "created_at": "2021-10-21T10:58:30.000Z",
  "updated_at": "2021-10-21T10:58:31.000Z"
}

Update A Post

This endpoint allows anyone to update a post.

HTTP Request

PUT https://app.hellonext.co/api/v3/feature_requests/:id

Headers

Parameter Default Description
API-KEY - Generate from organization settings on the admin dashboard.
ALLOW-PRIVATE false Set to true if updating a post in a private board.
Authorization - Generate a unique JWT token specific to a user.

Body Parameters

Parameter Required Format Description
title true String Title of the post (also used to create the slug).
description false Text Details of the post (can be in HTML).
bucket_id true Integer Valid board ID. Needs ALLOW-PRIVATE header to be set if it is a private board ID.
{
  "id": 4230,
  "slug": "good-bye-world",
  "title": "Good bye world",
  "preview": "",
  "description": null,
  "description_html": null,
  "status": "Submitted",
  "url": "https://feedback.hellonext.co/b/api/p/good-bye-world",
  "submitter": "Swaathi",
  "bucket": {
    "id": 14,
    "name": "API"
  },
  "votes_count": 0,
  "downvotes_count": 0,
  "comments_count": 0,
  "created_at": "2021-10-21T10:58:30.000Z",
  "updated_at": "2021-10-21T10:58:31.000Z"
}

Delete A Post

This endpoint allows anyone to delete a post.

HTTP Request

DELETE https://app.hellonext.co/api/v3/feature_requests/:id

Headers

Parameter Default Description
API-KEY - Generate from organization settings on the admin dashboard.
ALLOW-PRIVATE false Set to true if deleting a post in a private board.
Authorization - Generate a unique JWT token specific to a user.
{
  "success": true
}

Changelogs

List All Changelogs

This endpoint retrieves all changelogs.

HTTP Request

GET https://app.hellonext.co/api/v3/changelogs

Headers

Parameter Default Description
API-KEY - Generate from organization settings on the admin dashboard.

Query Parameters

Parameter Default Description
page 1 Used to paginate responses.
status - Can be set to published or unpublished.
{
  "changelogs": [
    {
      "id": 1,
      "title": "API V1 is now live!",
      "preview": "Go use our new API now!",
      "description": "<p>Go use our new API now! Go on, you can do it!</p>",
      "url": "https://feeback.hellonext.co/changelogs/api-v1-is-now-live",
      "published": true,
      "published_on": "October 12th, 2021",
      "author": {
        "name": "Swaathi",
        "email": "swaathi@skcript.com"
      },
      "labels": [
        {
          "id": 3,
          "name": "New Feature",
          "color": "green"
        }
      ]
    }
  ]
}

Get A Changelog

This endpoint retrieves a specific changelog. It also shows all tagged posts.

HTTP Request

GET https://app.hellonext.co/api/v3/changelogs/:id

Headers

Parameter Default Description
API-KEY - Generate from organization settings on the admin dashboard.

Query Parameters

Parameter Default Description
id - The ID of the changelog returned in the list changelogs endpoint.
{
  "changelogs": [
    {
      "id": 1,
      "title": "API V1 is now live!",
      "preview": "Go use our new API now!",
      "description": "<p>Go use our new API now! Go on, you can do it!</p>",
      "url": "https://feeback.hellonext.co/changelogs/api-v1-is-now-live",
      "published": true,
      "published_on": "October 12th, 2021",
      "author": {
        "name": "Swaathi",
        "email": "swaathi@skcript.com"
      },
      "labels": [
        {
          "id": 3,
          "name": "New Feature",
          "color": "green"
        }
      ],
      "feature_requests": [
        {
          "id": 4229,
          "slug": "chrissy-smith",
          "title": "Chrissy Smith",
          "preview": "Chrissy Smith",
          "description": "This is a description for dummies. \n\n",
          "description_html": "<p>This is a description for dummies.</p>",
          "status": "Submitted",
          "url": "https://feedback.hellonext.co/b/api/p/chrissy-smith",
          "submitter": "swaathi",
          "bucket": {
            "id": 14,
            "name": "API"
          },
          "downvotes_count": 0,
          "comments_count": 0,
          "created_at": "2021-10-20T13:58:49.000Z",
          "updated_at": "2021-10-20T13:58:49.000Z"
        }
      ]
    }
  ]
}

Create A Changelog

This endpoint allows only members and admins to create a changelog.

HTTP Request

POST https://app.hellonext.co/api/v3/changelogs

Headers

Parameter Default Description
API-KEY - Generate from organization settings on the admin dashboard.
Authorization - Generate a unique JWT token specific to a user.

Body Parameters

Parameter Required Format Description
title true String Title of the changelog (also used to create the slug).
description false Text Details of the changelog (can be in HTML).
published false Boolean Set to true if you want the changelog to be published immediately.
scheduled_published_at false Date Any valid date format is accepted as long as it is in the future.
{
  "changelogs": [
    {
      "id": 1,
      "title": "Changelog labels is now live!",
      "preview": "Go label your changelogs now!",
      "description": "<p>Go label your changelogs now! Go on, you can do it!</p>",
      "url": "https://feeback.hellonext.co/changelogs/changelog-labels-is-now-live",
      "published": true,
      "published_on": "October 12th, 2021",
      "author": {
        "name": "Swaathi",
        "email": "swaathi@skcript.com"
      },
      "labels": [],
      "feature_requests": []
    }
  ]
}

Update A Changelog

This endpoint allows only members and admins to create a changelog.

HTTP Request

PUT https://app.hellonext.co/api/v3/changelogs/:id

Headers

Parameter Default Description
API-KEY - Generate from organization settings on the admin dashboard.
Authorization - Generate a unique JWT token specific to a user.

Body Parameters

Parameter Required Format Description
title true String Title of the changelog (also used to create the slug).
description false Text Details of the changelog (can be in HTML).
published false Boolean Set to true if you want the changelog to be published immediately.
scheduled_published_at false Date Any valid date format is accepted as long as it is in the future.
{
  "changelogs": [
    {
      "id": 1,
      "title": "Changelog labels is now live!",
      "preview": "Go label your changelogs now!",
      "description": "<p>Go label your changelogs now! Go on, you can do it!</p>",
      "url": "https://feeback.hellonext.co/changelogs/changelog-labels-is-now-live",
      "published": true,
      "published_on": "October 12th, 2021",
      "author": {
        "name": "Swaathi",
        "email": "swaathi@skcript.com"
      },
      "labels": [],
      "feature_requests": []
    }
  ]
}

Delete A Changelog

This endpoint allows anyone to delete a changelog.

HTTP Request

DELETE https://app.hellonext.co/api/v3/changelogs/:id

Headers

Parameter Default Description
API-KEY - Generate from organization settings on the admin dashboard.
Authorization - Generate a unique JWT token specific to a user.
{
  "success": true
}

Kanban

This section documents the API for the customizable roadmap section of Hellonext.

List All Columns

This endpoint retrieves all kanban columns, in order.

HTTP Request

GET https://app.hellonext.co/api/v3/kanban/columns

Headers

Parameter Default Description
API-KEY - Generate from organization settings on the admin dashboard.
{
  "success": true,
  "columns": [
    {
      "id": 1,
      "name": "Ideas",
      "position": 1
    },
    {
      "id": 2,
      "name": "Building",
      "position": 2
    },
    {
      "id": 3,
      "name": "Live",
      "position": 3
    }
  ]
}

List All Entries

This endpoint retrieves all kanban entries, of a specific column.

HTTP Request

GET https://app.hellonext.co/api/v3/kanban/:column_id/entries

Headers

Parameter Default Description
API-KEY - Generate from organization settings on the admin dashboard.

Query Parameters

Parameter Default Description
column_id - Required to fetch entries of a column.
page 1 Used to paginate responses.
{
  "success": true,
  "column": {
    "id": 1,
    "name": "stay",
    "position": 1
  },
  "entries": [
    {
      "id": 1,
      "title": "Customizable Roadmap",
      "tagline": "Like a Kanban, but not.",
      "description": "<p>You can add whatever you want in here! And tag posts!</p>",
      "position": 1,
      "header_image": {
        "url": "https://..."
      },
      "feature_requests": [
        {
          "id": 4229,
          "slug": "chrissy-smith",
          "title": "Chrissy Smith",
          "preview": "Chrissy Smith",
          "description": "This is a description for dummies. \n\n",
          "description_html": "<p>This is a description for dummies.</p>",
          "status": "Submitted",
          "url": "https://feedback.hellonext.co/b/api/p/chrissy-smith",
          "submitter": "swaathi",
          "bucket": {
            "id": 14,
            "name": "API"
          },
          "downvotes_count": 0,
          "comments_count": 0,
          "created_at": "2021-10-20T13:58:49.000Z",
          "updated_at": "2021-10-20T13:58:49.000Z"
        }
      ]
    }
  ]
}

Webhooks

Hellonext provides webhooks which allow us to send information to your custom endpoint when certain events are triggered. This allows you to integrate your systems with our platform.

Webhook events are currently supported for the following modules,

  1. Posts
  2. Changelogs

For example, you can configure an endpoint to receive information when a new post is submitted.

How does it work?

A webhook is simply a HTTP POST request to an endpoint (URL) that you set. Hellonext automatically triggers the webhook when a relevant event occurs in your organization.

How to setup a webhook?

  1. Navigate to the “Dashboard” and then click on “Webhooks” in the sidebar.
  2. Click on the “Add Webhook” button.
  3. Fill in the URL and description. Then select the events you want to be notified for. Your URL is a simple HTTP endpoint. It must satisfy the following conditions:
    • It must have a valid SSL certificate (https).
    • It must be accessible on the public internet.
    • It should return a 200 status code when the request is successful._
  4. Click on the “Save” button.

The Retry Policy

When a webhook is triggered, the request is sent to the endpoint specified in your configuration. If the request fails, the request is retried up to 3 times. If the request fails after 3 times, the webhook is marked as failed.

You can also check the logs of each webhook in the “Webhooks” section of your organization “Dashboard”.

Example Payload For A Post Submission

The webhook HTTP payload will include information both in its request body.

{
  "type": "postCompleted",
  "data": {
    "id": 80874,
    "title": "Facebook Conversion",
    "object": "post",
    "description": "This is a test",
    "description_html": "<p>This is a test</p>\n",
    "status": {
      "label": "Completed",
      "value": "completed"
    },
    "assignee": {},
    "approval_status": "approved",
    "hidden": false,
    "pinned": false,
    "downvotes_count": 0,
    "upvotes_count": 1,
    "etc_date": null,
    "parent_id": null,
    "comments_count": 0,
    "created_at": 1648026486,
    "updated_at": 1651686939,
    "submitter": {
      "name": "Hellonext Support",
      "email": "support@hellonext.co"
    },
    "before": {
      "status": {
        "label": "Planned",
        "value": "planned"
      },
      "completed_at": null
    },
    "after": {
      "status": {
        "label": "Completed",
        "value": "completed"
      },
      "completed_at": "2022-05-04 17:55:39 UTC"
    }
  },
  "created": 1651686939
}  

Errors

The Hellonext API uses the following error codes:

4xx

Error Code Meaning
400 Bad Request – Your request is not properly structured
401 Unauthorized – Your API key or JWT token is wrong
403 Forbidden – The resource requested is hidden for members/admins only
404 Not Found – The specified resource could not be found
418 I’m a teapot
429 Too Many Requests – You’re requesting too many resources! Slow down!

5xx

Error Code Meaning
500 Internal Server Error – We have a problem with our server. Try again later.
503 Service Unavailable – We’re offline for maintanance. Please try again later.

If at any point of time you face errors using our API, please raise a ticket on our feedback platform.