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
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
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
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
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
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
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
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 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
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.
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
Remove a webhook.
URL
https://api.hunchbuzz.com/v1/[CommunityId]/webhooks/[WebhookId]
Method
DELETE
Parameters
None
Returns
200 Ok
Errors
400 Bad request
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