IdeaScale REST API

API Overview

Objective:
The objective of this document is to ensure proper documentation of the APIs for a community. This document can be used to further automate and integrate your community with any internal/home-grown software solutions.

The architecture and design considerations of IdeaScale software include maximum integration with custom applications so that customers can best use the software according to their organization preferences.


The API library will be enriched over time with more endpoints.

Scope:
This document discusses the use of APIs in an IdeaScale community. This document serves as an instruction for any future integration needs. This document includes the environment requirement of the systems or applications connecting to IdeaScale API set. However, the document does not consider the customer environment as a whole.
 
About the API
The IdeaScale API provides methods for obtaining data from this site for use in mashups and other consumable formats. Anyone can use the API -- all it takes is a 10-second signup process to obtain a key -- so we can keep track of how many people are using the API and a way to get in touch with you if there are changes to the API itself.

Quick Links: 

  1. Getting Started

  2. Authentication

  3. URL

  4. Example API Endpoints

  5. Create New Members

  6. Vote on Idea

  7. Email Members

  8. List of success/error code that will be displayed

  9. Assumptions

Get Started: 


How to request an API token:

Please note that the ability to access API tokens is controlled by the community admin. If this feature is disabled, community members will not be able to generate API tokens. Admins can find this setting in their Community Settings under Integration >> Developer API >> API Access for Members.


Screenshot 2023-08-29 at 7.15.40 AM

To access the API you need to create an API Token. The API Token can be created from your IdeaScale profile. API access is per-member basis (i.e., every member can have one or more API tokens). The API token will make use of IdeaScale’s user roles (ie. normal members--or end-users--will only get be able to use the calls permitted to them and Admin members will get admin level permission. You can request an API from:

Personal Settings >> Communities >> API Tokens

Screenshot 2023-05-02 at 5.14.45 PM

Screenshot 2023-05-02 at 5.16.57 PM


Once the API token is generated, it can be used to access the IdeaScale API. Every API request must be used with the appropriate members’ API token.
An IdeaScale API token must be provided when making API calls in https request header. The request header field name must be “api_token.

Authentication


Non-SSO communities

Authentication is based on API tokens. The token generated above must be in every REST call. The token should be present in an HTTPS header named api_token.

 

Non-SSO communities with member Token:
Sometimes it may be required that an API call is made on behalf of a community member. IdeaScale supports this by means of Multipass token. If a header named “member_token” contains a valid encrypted Multipass token, then the “member_token” is used to identify the actor member. The Multipass token named “member_token” is generated using Multipass token generation code which is available in https://github.com/ideascale/multipass and has examples in many programming languages. In brief, it contains an AES encrypted JSON string that contains at least the email address of the target member. To learn more about Multipass Token please refer to https://help.ideascale.com/knowledge/single-sign-on-sso
 
The multipass token generation code would need “Site Key” and “API Key”. These keys can be found from Community Settings >> Integration >> Developer 

 

SSO Communities
API requests for single sign-on communities must contain an API token from an admin user of the community in an HTTPS header named “api_token”. The request must also provide the SSO credentials of the user for whom the request is being made. The HTTPS header name is “sso_token” which is the multipass token used for SSO authentication. For this, to work the Multipass Key should be created for the community. This can be set from Community Settings> Single Signon. An example of how to create a multipass SSO token can be found at https://help.ideascale.com/knowledge/single-sign-on-sso

General REST API Information
The IdeaScale REST API is a RESTful API. It is based on the HTTPS protocol and supports JSON format data transfers.

URL

 The IdeaScale REST API URL has three components:
 1) Community URL - The URL of the community.
 2) API Version - Identifies the version of the IdeaScale REST API being used.
 3) Method URL - specific call being made.
 For example, an API call to get the set of campaigns for the community apitest.ideascale.com, using version 1.0 of the API would be:
 https://apitest.ideascale.com/a/rest/v1/campaigns

Tip: Replace 'apitest.ideascale.com' with your specific community URL

Note: The API will not accept certain types of content submitted as ideas, comments, titles or tags. For example, if the following types of content are POSTed to the API, the API will return an 'INVALID_CONTENT' error:
 a. html tags
 b. Excessively long text (if the idea length limit is enforced by your moderator)
 c. Curse words (if the moderator has enabled curse word filtering)

 
For the detailed list of API endpoints refer to: https://a.ideascaleapp.com/api-docs/index.html
 

Example API Endpoints:

Note: These are example URL's, please replace the portion of the URL using 'ideascale.com' with your specific community URL

Action:  Create New Member
Method URL: /members
EG: https://ideascale.com/a/rest/v1/members
Method: POST

Action:  Create Campaign
Method URL: /campaign
EG: https://ideascale.com/a/rest/v1/campaign
Method: POST

Action: Create New Idea
Method URL: /idea
EG: https://ideascale.com/a/rest/v1/idea
Method: POST

Action: Delete Ideas
Method URL /idea/{ideaId}/delete
EG: https://ideascale.com/a/rest/v1/idea/3421/delete
Method: DELETE

Action: Delete all Ideas, Comments and Vote
Method URL /community/delete/ideas
EG: https://ideascale.com/a/rest/v1/community/delete/ideas
Method: DELETE

Action: Delete all members and ideas including votes and comments from community
Method URL /community/delete/ideasAndMembers
EG: https://ideascale.com/a/rest/v1/community/delete/ideasAndMembers
Method: DELETE

Action:  Get all Campaigns
Method URL: /campaigns
EG: https://ideascale.com/a/rest/v1/campaigns
Method: GET

Action:  Get Member Information
Method URL: /members/{memberId}
EG: https://ideascale.com/a/rest/v1/members/29781
Method: GET

Action:  Get Member Information By Name
Method URL: /members/name/{name}
EG: https://ideascale.com/a/rest/v1/members/name/John
Method: GET

Action:  Get Member Information By Email
Method URL: /members/email/{email}
EG: [email protected]
Method: GET

 Create New Members:

Note: These are examples, please replace the portion of the URL using 'ideascale.com' with your specific community URL


Member JSON Structure

 Used by: /members

Field Name  Type       Required     Description
name            String     Required     Name of Member
email            String Required         Email address of member

 Sample:
 {"name" : "John Doe", "email" : "[email protected] "}

 Vote on Idea:

Note: This is an example, please replace the portion of the URL using 'ideascale.com' with your specific community URL


Vote Up on Idea JSON Structure

Used by: /ideas/{ideaId}/vote/up

Field Name    Type          Required      Description
MyVote           Number    Optional       1 for agree

 Sample:
 { "myVote":1 }

Email Members:

Note: This is an example, please replace the portion of the URL using 'ideascale.com' with your specific community URL

Used by: /email/group/{id}

Note: Only Admin will be able to sent email to a group


Query Parameter
"Id": Group Id. Group can be "moderators", "admins" or a "group"

Request Body Parameters:
"subject" : String (required)
"body" : String (required)

Sample:

{
"subject" : "Are you ready for the survey",
"body" : "Hey, You will receive another email shortly"
}


Here is a list of success/error code that will be displayed:

Key                                                Message                                                 HTTP Code UNEXPECTED                              Unexpected Error                                             500
INVALID_HEADER                       Invalid HTTP Header for API Request             400 NO_AUTHENTICATION
_HEADER                                     No Header containing authentication data    400 NO_API_TOKEN No API             Token provided                                                 400
NO_CAMPAIGN                           No Campaign provided                                    400  INVALID_API_TOKEN                 Invalid API Token                                              400
INVALID_OAUTH_TOKEN           Invalid OAuth Token                                         400
INVALID_SSO_TOKEN                Invalid SSO Token                                             400
INVALID_MEMBER_TOKEN        Invalid Member Token                                      400 MULTIPASS_SSO_NOT
_ENABLED                                   Multipass SSO not enabled                              400 MULTIPASS_KEYS_NOT
_CONFIGURED                            Multipass Keys not configured                          400 SSO_MEMBER_NOT_FOUND
SSO                                               Member not found                                             404
PERMISSION_DENIED                 Permission Denied                                            403
RESTRICTED_TO_ADMIN           Resource is restricted to ADMIN                      403 NO_SECURE_CHANNEL            Secure channel required                                   403
NO_SSO_TOKEN                        No SSO token provided by SSO community    403 LICENSE_NOT_ALLOWED        Resource not accessible to current license       403 COMMUNITY_NOT_FOUND    Community not found                                           404
MEMBER_NOT_FOUND           Member not found                                                404
MEMBER_NAME_NOT
_FOUND                                    Member name not provided                                 404 PERSON_NOT_FOUND           Person not found 404
CAMPAIGN_NOT_FOUND      Campaign not found 404
IDEA_NOT_FOUND                 Idea not found 404
STATUS_NOT_FOUND           custom status not found 404
MISSING_REMOTE                  Authentication missing expected Remote
_IDENTITY_DATA                    identity Data                                                            400  INVALID_CREDENTIALS        Authentication data contains invalid credentials 403 INVALID_STATUS_CHANGE  Invalid Status Change                                             400
INVALID_CONTENT                Invalid Content                                                        400
COMMENT_NOT_FOUND     Comment not found                                                404
OWNERSHIP_DISABLED        Idea ownership is not enabled                              400 MULTIPLE_OWNERSHIP
_DISABLED                              Mulitple ownership is not enabled                        400
INVALID_EMAIL                       Invalid Email                                                            400
UNSUPPORTED_FILE
_EXTENSION                          Unsupported file extension                                     400 FILE_STORAGE_LIMIT           You have exceeded the storage limit                     400
FILE_EXIST                             A file with the same name already exists               400 EMAIL_ALREADY
_REGISTERED                        Email already registered                                          400
INVALID_EMAIL_OR              Invalid email or already registered,
_ALREADY_REGISTERED      try a different email.                                                 400
IDENTITY_NOT_FOUND       Identity not found                                                     404
PRIVATE_COMMUNITY         Private community
_NOT_ALLOWED                   is not allowed for research                                      403
ACTOR_IS_LOCKED              Actor is locked                                                          403
HTML_TAGS_NOT
_ALLOWED                             Html tags not allowed                                              400
TEXT_CONTAINS_
FORBIDDEN_CHARACTERS Text Contains forbidden characters                        400
ABUSIVE_WORD_FOUND    Abusive/Inflammatory/Curse words found             400 PERSON_LOCKED                 Person is locked                                                       403
REVIEWSCALE_NOT_
FOUND                                   Reviewscale not found                                             404
STAGE_NOT_FOUND           Stage not found                                                         404
FUNNEL_NOT_FOUND        Funnel not found                                                       404
BADGE_NOT_FOUND          Badge not found                                                       404
CAMPAIGN_CHANGE_
NOT_ALLOWED                    Campaign change not allowed                                403 REQUIRED_FIELD_
MISSING                                 Required data not found                                          400 INVALID_ORDER_BY_KEY   Invalid order by key                                                  400
CAMPAIGN_GROUP_
NOT_FOUND                        Campaign Group not found                                      400
INVALID_INPUT                    Invalid input value                                                     400
ASSESSMENT_NOT_
FOUND                                  Assessment Not Found                                            400
GROUP_NOT_FOUND        Group not found                                                        400 

 

Here is the list of order keys:

date-up
date-down
id-up
id-down
name-up
name-down
point-up
point-down 
 

Known API Issues:

  • Error Info JSON is not being returned

  • top ideas are sometimes not ordered correctly

  • specifying version as “v1.0” returns 404


Assumptions:

This API documentation will have the below two items as mandatory environmental considerations.

Host:
https://ideascale.com/a/rest/v1/

Your Community URL in place of 'ideascale.com'


Header:
All API call should provide these header values.

Parameter name: api_token
Value: {Value provided by ideascale}

 

Last Updated: October 26, 2023