Objective:
Objective of this document is to ensure a 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 includes 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 considers the customer environment as a whole.
 
About the API
The IdeaScale API provides methods for obtaining data from this site for using 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.
 
 Using the API
 How to request an api token:
 
 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 token). 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 Profile>>Communities>>Api Tokens

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 http request header. The request header field name must be “api_token.
 
Authentication
Non-SSO communities
Authentication is based on API token. The token generated above must be in every REST call. The token should be present in an HTTP header named “api_token”.
 
Non-SSO communities with member Token:
Sometimes it may be required that a 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 example in many programming languages. In brief, it contains a AES encrypted JSON string which contains at-least the email address of the target member. To learn more about Multipass Token please refer to https://support.ideascale.com/overview-articles/single-sign-on-multipass-saml-yammer
 
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 HTTP header named “api_token”. The request must also provide the SSO credentials of the user for whom the request is being made. The HTTP 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. Example of how to create multipass SSO token can be found at
https://support.ideascale.com/overview-articles/single-sign-on-multipass-saml-yammer

General REST API Information
The IdeaScale REST API is a RESTful API. It is based on the HTTP 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
 
 Please 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 you could refer to: https://a.ideascale.com/api-docs/index.html
 
List of few Sample API Endpoints:

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: https://ideascale.com/a/rest/v1/members/email/john@ideascale.com
Method: GET


 Create New Members


 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" : "john.doe@domain.com"}
 
 
 Vote on Idea:


 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:
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 

 
 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/

Header:
All API call should provide these header values.

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

Did this answer your question?