Developing with Ideanote
Thanks for your interest in developing with Ideanote!
Ideanote is built modular and flexible from the ground up to support a wide range of innovation use-cases. Our easy-to-integrate REST API allows you to create custom innovation workflows for your business - from collecting ideas to managing teams and syncing data.
Introduction
The Ideanote API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. The API is stateless – all requests are validated against an API token.
The API is versioned to ensure backwards compatibility: the current version is v1.
The current base URL of the API is https://api.ideanote.io/v1/.
Note that the URL query parameter field is required for all endpoints.
Use-Cases
The Ideanote API offers a powerful set of tools to integrate idea management capabilities into your business processes and existing infrastructure.
Some common ways of using our API span from integrating Ideanote deep into an application you are developing yourself, to more light use-case of sending of ideas to Ideanote or syncing data between Ideanote and another application.
Take a look at the following examples:
- Idea Submission: Automatically capture ideas from internal communication tools and virtual meetings via the Ideanote API, submitting them directly to Ideanote for evaluation.
- Project Management Integration: Seamlessly transition approved ideas into actionable projects with Ideanote's API, creating tasks or projects in project management tools like Jira.
- In-App Feedback: Direct customer feedback from your applications into Ideanote using the API for structured, customer-driven innovation.
- Business Intelligence: Extract idea submission data for BI analysis, creating detailed reports on innovation ROI, top ideas, and employee contributions with the Ideanote API.
- Employee Recognition: Connect Ideanote with HR systems to automatically reward employees for their contribution to successful ideas, enhancing engagement.
- Data Privacy Compliance: Maintain compliance by using the API to manage user data, including searching, updating, or deleting deactivated users from your central registry.
By leveraging the Ideanote API in these ways, you can create a more integrated, efficient, and engaging innovation ecosystem for your business.
REST API Basics
Ideanote’s API is a REST-based interface, which means that applications make requests to the API by accessing specific URLs using HTTPS. Each request is a single, self-contained operation.
The base URL for all API calls is https://api.ideanote.io/v1/, with specific paths appended to this base URL for accessing different resources. For instance, to list Ideas Collections, the URL extends to include /v1/idea_collections.
Authentication is essential for using the Ideanote API, requiring an access token to be included in the HTTP header as Authorization: Bearer YOUR_TOKEN. This ensures secure access to your workspace data scoped to the user who created the access token. Additionally, all API calls must include an Accept: application/json header, indicating that the data exchange format is JSON, which is the only format supported by the API.
The API is organized around resources, which are identified in the URL and manipulated through HTTP verbs like GET, POST, PUT, and DELETE. These verbs indicate the action you wish to perform, such as querying, adding, updating, or deleting.
Parameters play a significant role in the API's functionality, with query parameters specifying details for GET requests and body data for PUT and POST requests. This allows for nuanced interactions with the API, such as paging through results or updating specific resource data.
Error handling in the Ideanote API utilizes standard HTTP status codes to indicate the success or failure of requests. Common codes include 200 for success, 400 for bad requests, 429 for exceeding usage limits, and 500 for internal server errors.
Ideanote Data Structure
Ideanote's architecture is designed to reflect the hierarchical and collaborative nature of innovation within businesses. This structure supports an organized approach to managing ideas, from inception to execution, within a digital workspace tailored for efficiency.
Below, we delve into the primary components of Ideanote's data structure to help developers navigate and leverage the platform effectively.
Workspaces: A Workspace is the top layer in Ideanote, they organize everything related to innovation in one centralized home for ideas for the business.
Sections: Sections break down the Workspace into more manageable visual areas, such as different departments or topics. This makes it easier to keep innovation organized for the business.
Idea Collections: Idea Collections are where ideas on particular topics are gathered. They include Phases that an idea must pass through, helping to structure the development process from start to finish.
Phases and Ideas: Phases are the steps an idea goes through within a Collection, from conception to completion. Ideas are the fundamental elements here, contributed by users and evolved through comments, likes, and their progression through these Phases. Each idea is based on a custom Form with Idea Fields as defined by the business, sometimes with different Forms for each Idea Collections, depending on context.
Users, Teams, and Ranks: Inside a Workspace, users are the contributors and can be grouped into Teams for collaboration. Users have Ranks such as Workspace Owner, Admin, Member and Guest that can give more or less access to settings, creating Idea Collections and managing content .
Access and Permissions: Access to Idea Collections is managed by sharing settings, not ranks. This means a user's ability to see, add to, or interact with Idea Collections depends on whether it's shared with them or their Team, ensuring the right people can focus on the relevant tasks.
Developers can find more details on user ranks and permissions at Ideanote's help center.
Access to the API
To get started with the Ideanote API, you will need to generate your API Access Token under Settings > Account > API Token in the Ideanote App.
You’ll need to have at least an Admin rank to get access and every user has access to entities and data via the API that they have access to as a user in the Ideanote App.
You can have multiple API Tokens to use across different applications, each can be individually revoked.
Our APIs are free to use for customers on a paid subscription.
Example API Calls
This tutorial will show you how to make your first API call to the Ideanote API and retrieve a list of ideas from an Idea Collection.
Step 1: Generate an Ideanote API Access Token
Here is a step-by-stop tutorial for Authorization
You will need to pass this 43 character long token in an Authorization header of type Bearer Token in all the HTTPS requests you will make to the Ideanote API to access the content defined in your account. Here is an example of an authorization header:
Authorization: Bearer ea5b9e4********************Step 2: List Idea Collections via the API
Call the Idea Collections endpoint to list all Idea Collections your user has access to.
curl -X GET "https://api.ideanote.io/v1/idea_collections" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>"The above command returns JSON structured like this:
[
{
"id": "020166b4-8846-4896-b2ac-9074fd3a1b2c",
"title": "Example Idea Collection",
"question": "How might we improve the coffee?",
"details": null,
"stats": {
"ideas": {
"total": 3
}
},
"cover": {
"url": {
"thumbnail": "https://uploads.staging.ideanote.dev/staging/v1/f985c93c-bcbd-e67f-31e5-d54f965a5fe1/download_original"
}
}
}
]Step 3: Select an Idea Collection and List Ideas
Call the endpoint to list ideas in a specific Idea Collection. The below example has filled out the id in the format here and contains URL parameters to return metadata and idea fields including field titles, kinds and values.
curl -X GET "https://api.ideanote.io/v1/idea_collections/020166b4-8846-4896-b2ac-9074fd3a1b2c/ideas?fields=id,friendlyId,keywords,status.title,phase.name,fields.{kind,title,value},owner.{firstName}" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>"Step 4: Processing the JSON Response
The HTTPS response will be a list of ideas formatted as JSON.
Each idea field has an idea field title and value. If you are looking for specific content, for example the description of an idea you can look for the :id with that title and then process the value of that idea field. Idea Fields are listed by their ID to keep the API consistent even if an idea field is renamed in the Ideanote App.
You can identify idea field IDs ahead of time in the Ideanote App under Forms > Fields > Copy ID.
[
{
"id": "38494f31-4edc-414c-8320-e1aa8988e7aa",
"friendlyId": 2,
"keywords": ["bad", "idea", "bad", "idea"],
"status": {
"title": "On Track"
},
"phase": {
"name": "Comment"
},
"fields": [
{
"kind": "LONG_TEXT",
"title": "Description",
"value": "This is a bad idea"
},
{
"kind": "SHORT_TEXT",
"title": "Title",
"value": "Bad Idea"
}
],
"owner": {
"firstName": "Test"
}
},
{
"id": "da011987-cfa9-49fa-b331-bb4ca0b2fa1b",
"friendlyId": 1,
"keywords": ["great", "idea", "great", "idea"],
"status": {
"title": "On Track"
},
"phase": {
"name": "Comment"
},
"fields": [
{
"kind": "SHORT_TEXT",
"title": "Title",
"value": "Great Idea"
},
{
"kind": "LONG_TEXT",
"title": "Description",
"value": "This is a great idea"
}
],
"owner": {
"firstName": "Test"
}
}
]