or Create a profile

Home → Knowledge Base → Developers →

IdeaScale REST API

IdeaScale REST API

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.

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

List of API Calls

Action Method URL Method
Get Campaigns /campaigns GET
Get Top Ideas /ideas/top GET
Get Recent Ideas /ideas/recent GET
Get All Campaign Ideas /campaigns/{campaignId}/ideas GET
Get Recent Campaign Ideas /campaigns/{campaignId}/ideas/recent GET
Get Top Campaign Ideas /campaigns/{campaignId}/ideas/top GET
Create New Idea /idea POST
Vote on An Idea /ideas/{ideaId}/vote POST
Add a comment to an Idea /idea/{ideaId}/comment POST
Get Member Information /members/{memberId} GET
Get Member Information By Email /members/email/{email} GET
Get Member Ideas /members/{memberId}/ideas GET

Using the API

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.

apirequest.png

apitoken2.png

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”.

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
http://support.ideascale.com/kb/ideascale-setup/single-sign-on-mult...

REST Endpoints to Retrieve Data

Get Campaigns

Get Top Ideas

Get Recent Ideas

Get All Campaign Ideas

Get Recent Campaign Ideas

Get Top Campaign Ideas

Get Member Ideas

Get Member Information

Get Member Information by Email

  • Sample URL: christoph.schebel@ideascale.com">http://ideas.ideascale.com/a/rest/v1/members/email/christoph.schebe...
  • Method: GET
  • Expected Response: JSON Member Info structure

Note: This endpoint is only available to Community Admin users or SSO communities.

Common JSON Structures for Date Retrieval

Campaign Info JSON Structure

Returned by: /campaigns

Field Name Type Description
id Number Capaign ID
name String Campaign name
description String Campaign description

Sample:

[ { "name" : "User Interface", "id" : 12358, "description" : "Suggested changes or enhancements to the User Interface or workflow within the UI." }, { "name" : "Moderation", "id" : 12046, "description" : "Items related to community moderation (editing ideas, changing status, etc)." }, { "name" : "iPhone SDK", "id" : 12339, "description" : "Feedback related to the IdeaScale iPhone SDK. Learn more at http://ideascale.com/iphone" }, { "name" : "Facebook App", "id" : 12341, "description" : "Tell us what you think of our Facebook app. What can we improve to make it better?" }, { "name" : "Community Development", "id" : 10709, "description" : "Ideas and suggestions around community development" }, { "name" : "API", "id" : 12038, "description" : "Issues and enhancements with the API" }, { "name" : "Bugs/Issues", "id" : 10710, "description" : "Any bugs and issues related to IdeaScale. Note: if the issue is urgent, please post to http://support.ideascale.com or email support@ideascale.com." } ]

Member Info JSON Structure

Returned by: /members/{memberId}

Field Name Type Description
id Number Member ID within this community
name String Member name
email String Member email address *Note: This field is only populated for Admin users or SSO communties.*
personId Number Person ID. Member ID is specific to the community; while Person ID is IdeaScale-wide

Sample:

{ "name" : "Christoph Schebel", "id" : 131455, "personId" : 2448182 }

Idea Info JSON Structure

Returned by:

/idea
/ideas/{ideaId}/vote
/ideas/{ideaId}/comment
/ideas/top
/ideas/recent
/campaigns/{campaignId}/ideas/top
/campaigns/{campaignId}/ideas/recent
/ideas/tag/{tag}
/campaigns/{campaignId}/ideas/tag/{tag}
/members/{memberId}/ideas


Field Name Type Description
id Number Idea ID
creationDateTime Datetime Time the idea was created
title String Idea title
text String Idea text
campaignId Number Campaign ID
authorId Number Author ID
authorInfo Object Member Info Structure for the Idea's author
voteCount Number Total votes
myVote Number Vote for the current user. Zero if this user has not voted.
commentCount Number Number of comments.
url String Idea URL
tags Array String array of tags for the idea.

Sample:

[ { "id" : 26197, "text" : "I would like to use the Ideascale application on multiple Facebook Pages, but the current design only allows one. Could you make it so we could put multiple Facebook Page ID's in so the application could point to the same community from a variety of Facebook pages.", "tags" : [ "facebook app", "ideascale" ], "url" : "http://ideas.ideascale.com/a/dtd/26197-3339", "title" : "Allow same Ideascale Facebook App on Multiple FB Pages", "campaignId" : 12341, "commentCount" : 2, "voteCount" : 4, "creationDateTime" : "2010-05-25T10:44:58.000-07:00", "authorId" : 112445, "authorInfo" : { "name" : "Jonathan Brier", "id" : 112445, "personId" : 927039 }, "myVote" : 0 }, { "id" : 26156, "text" : "add a link to Facebook page in addition to:\n \nSubscribe\n\nFollow us on Twitter\nNew Ideas RSS Feed\nTop Ideas RSS Feed\nNew Comments RSS Feed", "tags" : [ ], "url" : "http://ideas.ideascale.com/a/dtd/26156-3339", "title" : "add a link to Facebook page ", "campaignId" : 12341, "commentCount" : 0, "voteCount" : 3, "creationDateTime" : "2010-05-20T13:03:17.000-07:00", "authorId" : 113253, "authorInfo" : { "name" : "greencentralar", "id" : 113253, "personId" : 927043 }, "myVote" : 0 }, { "id" : 23087, "text" : "i would like to have my fb page visitors contribute ideas directly from FB", "tags" : [ ], "url" : "http://ideas.ideascale.com/a/dtd/23087-3339", "title" : "idea posting from facebook", "campaignId" : 12341, "commentCount" : 0, "voteCount" : 5, "creationDateTime" : "2009-09-18T23:46:32.000-07:00", "authorId" : 95559, "authorInfo" : { "name" : "spikmattansandraliv", "id" : 95559, "personId" : 602177 }, "myVote" : 0

Error Info JSON Structure

Returned by: All calls with errors

Field Name Type Description
Code String Error code
description String Error description

{ "code" : "555", "description" : “Invalid api token” }


REST Endpoints to Create/Update Data

Create New Idea


Create Idea JSON Structure

Used by: /idea

Field Name Type Required? Description
title String Required Idea title
text String Required Idea text
campaignId Number Optional Campaign ID
tags Array Optional String array of tags for the idea


Sample:

{ "text":"Idea description via rest API", "tags":["API","SDK"], "title":"Idea Title via rest API", "campaignId":202 }


Vote on Idea

Vote on Idea JSON Structure

Used by: /ideas/{ideaId}/vote

Field Name Type Required? Description
MyVote Number Optional 1 for agree (default if not specified) -1 for disagree

Sample:

{ "myVote":1 }

Add a comment to an Idea

Comment on Idea JSON Structure

Used by: /ideas/{ideaId}/vote

Field Name Type Required? Description
comment String Required Comment to add

Sample:

{ "comment":”Text of new comment” }

Known API Issues:

  • Error Info JSON is not being returned
  • top ideas are sometimes not ordered correctly
  • specifying version as “v1.0” returns 404
  • /ideas/{ideaId}/vote always votes “agree”
  • Add comment returns 404
Section:
Developers
Last Updated:
01 Oct, 2011 09:59 AM

Recent Discussions

16 May, 2012 09:13 PM Links in email notifications do not work
16 May, 2012 07:01 PM Reports

Recent Articles

Custom Field Settings
Reports: Export Idea Data
Uploading your Company Logo for Branded Emails
Global System Settings: Abuse Notification Threshold
Look & Feel Settings: Site HTML Pages