Hunchbuzz API V1

Request and response formats

In general, the HunchBuzz API uses HTTP GET and HTTP POST requests with JSON arguments and JSON responses. Request authentication is via OAuth 2.0 using the Authorization request header.

If the user loses access or doesn't have access to a resource, the API will return a 401 Unauthorized error.

Date format

All dates in the API use UTC and are strings in the ISO 8601 "combined date and time representation" format:

2020-05-15T15:50:38Z

Authentication

Hunchbuzz supports OAuth 2.0 for authorizing API requests. Authorized requests to the API should use an Authorization header with the value Bearer [TOKEN], where [TOKEN] is an access token obtained through the OAuth flow.

Authorize endpoint

URL

https://login.hunchbuzz.com/oauth/authorize

Method

GET

Parameters

client_id

Your HunchBuzz application id

redirect_uri

Your HunchBuzz application redirect URL

state

Arbitrary data that will be passed back to your redirect URI. This parameter should be used to protect against cross-site request forgery (CSRF).

Returns

Rediects to: redirect_uri/?code=ABCDEFG&state=[STATE]

Token endpoint

URL

https://login.hunchbuzz.com/oauth/token

Method

GET

Parameters

client_id

Your HunchBuzz application id

client_secret

Your HunchBuzz application secret

grant_type

bearer

code

The code you recieved on the redirect back to your application

redirect_uri

Your HunchBuzz application redirect URL

Returns

A JSON-encoded dictionary including an access token (access_token), the length of time it's valid (expires_in), token type (token_type), a user ID (uid). The token type will always be "bearer".

Example response


User profile

Get the profile of the authenticated user.

URL

https://api.hunchbuzz.com/v1/profile

Method

GET

Parameters

None

Returns

A JSON-encoded object with the users details.

id

The HunchBuzz user ID.

emailAddress

The HunchBuzz user email address.

name

The HunchBuzz user name.

avatar

A URL to their profile image - will rediect to external domain.

Example response


Communities

A user can belong to one or more communities - this endpoint will return a JSON-array of community details.

URL

https://api.hunchbuzz.com/v1/communities

Method

GET

Parameters

None

Returns

A JSON-encoded array of community objects.

id

The HunchBuzz community ID.

title

The HunchBuzz community title.

logo

The HunchBuzz community logo.

url

Link to the HunchBuzz community.

created

The date the community was created.

Example response


Challenges

A challenge (or question) is presented to the user for them to respond. By default, this endpoint will return all challenges the current user has access to.

URL

https://api.hunchbuzz.com/v1/[CommunityId]/challenges

Method

GET

Parameters

public_only

(Optional) Only return challenges all users have access to.
true/false

Returns

A JSON-encoded array of challenge objects.

id

The challenge ID.

title

The challenge title.

description

The challenge description, can currently contain HTML. Long field.

createdBy

Profile model of the user who created the challenge.

created

The date the challenge was created.

closeDate

If populated, the date the challenge is marked as closed. No new data can be added after this date. Date is UTC.

votes

The number of votes on ideas in this challenge.

ideas

The number of active ideas in this challenge.

comments

The number of comments on active ideas in this challenge.

isOpen

Is the challenge active.

Example response


Ideas

Returns a JSON array of ideas that belong to the challenge.

URL

https://api.hunchbuzz.com/v1/[CommunityId]/ideas/[ChallengeId]

Method

GET

Parameters

None

Returns

A JSON-encoded array of community objects.

id

The idea ID.

challengeId

The challenge ID the idea belongs to.

title

The idea title.

content

The idea itself. Can contain Markdown.

content

The date the idea was created.

tags

If populated, a comma seperated list of tags.

excerpt

A short version of the idea content. Plain text.

image

The chosen image for this idea.

createdBy

Profile model of the user who created the challenge.

ideaStage

The current Idea stage.

Example response


Idea stages

Returns a JSON array of ideas that belong to the challenge.

URL

https://api.hunchbuzz.com/v1/[CommunityId]/ideas/[ChallengeId]

Method

GET

Parameters

None

Returns

A JSON-encoded array of community objects.

id

The idea stage ID.

order

The position of the idea stage in the flow.

name

The name of the idea stage.

name

The description of the idea stage.

color

The display color of the idea stage.

finalStage

The final stage indicator.

0 - declined/not happening

1 - in progress/not in final stage

2 - approved/implemented

Example response


Webhooks

HunchBuzz will push data to a remote webhook on selected evens. If a webhook fails more than 5 times it will be disabled. It can be re-enabled using the reset endpoint.

All hits to your endpoint will be POST requests with JSON bodies.

List webhooks

List the webhooks for your application.

URL

https://api.hunchbuzz.com/v1/[CommunityId]/webhooks

Method

GET

Parameters

None

Returns

A JSON-encoded array of webhook objects.

id

Webhook id.

webhookUrl

The remote webhook URL.

status

The status of the webhook.

1 - active

2 - disabled

failedRequests

How many failed requests have been made since the last successful request.

Example response


Create a webook

List the webhooks for your application.

URL

https://api.hunchbuzz.com/v1/[CommunityId]/webhooks

Method

POST

Parameters

webhookUrl

The URL Hunchbuzz will POST data to.

Returns

A JSON-encoded webhook object.

id

Webhook id.

webhookUrl

The remote webhook URL.

status

The status of the webhook.

1 - active

2 - disabled

failedRequests

How many failed requests have been made since the last successful request.

Example response


Errors

400 Bad request

Empty or invalid webhookUrl field.

Reset a webook

If a webhook has become disabled due to excessive failed requests, you can reset it.

URL

https://api.hunchbuzz.com/v1/[CommunityId]/webhooks/reset/[WebhookId]

Method

POST

Parameters

None

Returns

200 Ok

Errors

400 Bad request

Delete a webhook

Remove a webhook.

URL

https://api.hunchbuzz.com/v1/[CommunityId]/webhooks/[WebhookId]

Method

DELETE

Parameters

None

Returns

200 Ok

Errors

400 Bad request

Webhook events

All webhooks will be sent to your URL via a POST request and a JSON encoded body as they happen inside the Hunchbuzz event system.

If a request fails, we'll requeue it for 5 minutes, up to 5 times. If we still can't send the data through, we'll disable the webhook and you will need to reset the connection using the mechanism above.

All webhooks will have topic and action properties on them, and a model property containing the item that triggered the webhook. The id field is the webhook id.

Topics

Actions

Platform

  • Edit

Challenge

  • Create

  • Edit

  • Delete

Idea

  • Create

  • Edit

  • Delete

  • Move

IdeaStage

  • Create

  • Edit

  • Delete

Sample

Idea create