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:
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.
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
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
-
Example URL: https://ideascale.com/a/rest/v1/members (This will send verification email to members)
-
Example URL: https://ideascale.com/a/rest/v1/members/create/silent (This will only create members and will not sent verification email)
-
Method: POST
-
POST data: Member JSON Structure
-
Expected Response: JSON Member Info structure for new member
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
-
Example URL: https://ideas.ideascale.com/a/rest/v1/ideas/20884/vote
-
Method: POST
-
POST data: Vote on Idea JSON structure
-
Expected Response: JSON Idea Info structure for the updated 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:
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}
-
Example URL: https://ideascale.com/a/rest/v1/email/group/75
-
Method: Post
-
Endpoint: /email/group/{id}
-
App Scope Required: Admin
-
Response content type: JSON
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}