Welcome, Guest Login

Support Center

IdeaScale REST API

Last Updated: Mar 16, 2017 12:06PM PDT

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.

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 http://support.ideascale.com/customer/portal/articles/1001474-single-sign-on-multipass-token-based-cookie-based-

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

http://support.ideascale.com/customer/portal/articles/1001474-single-sign-on-multipass-token-based-cookie-based

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)


List of API Calls

Action

Method URL

Method

Create New Member

/members

POST

Get Campaigns

/campaigns

GET

Get Member Information

/members/{memberId}

GET

Get Member Information By Name

/members/name/{name}

GET

Get Member Information By Email

/members/email/{email}

GET

Get Member Ideas

/members/{memberId}/ideas

/members/{memberId}/ideas/{pageNumber}/{pageSize}

GET

Get Idea Details

/ideas/{ideaId}

GET

Get All Idea Details

/ideas

GET

Get All Comments

/comments

/comments/{pageNumber}/{pageSize}

GET

Create New Idea

/idea

POST

Vote UP An Idea

/ideas/{ideaId}/vote/up

POST

Vote DOWN An Idea

/ideas/{ideaId}/vote/down

POST

Get Vote Information of an Idea

/ideas/{ideaId}/votes

GET

Get Vote Information For All Ideas

/ideas/votes

GET

Get Vote Information of a Comment

/comments/{commentId}/votes

GET

Get Vote Information For All Comments

/comments/votes

GET

Get Vote Information For All Ideas of a Member

/members/{memberId}/ideas/votes

GET

Get Vote Information For All Comments of a Member

/members/{memberId}/comments/votes

GET

Add a comment to an Idea

/idea/{ideaId}/comment

POST

Add a comment to comment

/comments/{commentId}/comment

POST

Delete a comment

/comments/{commentId}/delete

POST

Get all comments by its ID

comments/{commentId}

GET

Get all comments on an Idea

/ideas/{ideaId}/comments

GET

Get Comment Information By Member ID

/members/{memberId}/comments

GET

Get All Campaign Ideas

/campaigns/{campaignId}/ideas

/campaigns/{campaignId}/ideas/{pageNumber}/{pageSize}

GET

Order Campaign by Creation Date in Descending

/campaigns/{campaignId}/ideas/{pageNumber}/{pageSize}/{orderkey}

GET

Get Ideas by status (Custom)

/ideas/status/custom/{statusKey}

/ideas/status/custom/{statusKey}/{pageNumber}/{pageSize}

/campaigns/{campaignId}/ideas/status/custom/{statusKey}

/campaigns/{campaignId}/ideas/status/custom/{statusKey}/{pageNumber}/{pageSize}

GET

Order by Status Changed Date Descending

/ideas/status/custom/{statusKey}/{pageNumber}/{pageSize}/{orderkey}

/campaigns/{campaignId}/ideas/status/custom/{statusKey}/{pageNumber}/{pageSize}/{orderkey}

GET

Get Top Ideas

/ideas/top

/ideas/top/{pageNumber}/{pageSize}

/campaigns/{campaignId}/ideas/top

/campaigns/{campaignId}/ideas/top/{pageNumber}/{pageSize}

GET

Order by Top Ideasin Descending

/ideas/top/{pageNumber}/{pageSize}/{orderkey}

/campaigns/{campaignId}/ideas/top/{pageNumber}/{pageSize}/{orderkey}

GET

Get Recent Ideas

/ideas/recent

/ideas/recent/{pageNumber}/{pageSize}

/campaigns/{campaignId}/ideas/recent

/campaigns/{campaignId}/ideas/recent/{pageNumber}/{pageSize}

GET

Order by Recent Ideas in Descending

/ideas/recent/{pageNumber}/{pageSize}/{orderkey}

/campaigns/{campaignId}/ideas/recent/{pageNumber}/{pageSize}/{orderkey}

GET

Get Hot (Popular) Ideas

/ideas/hot

/ideas/hot/{pageNumber}/{pageSize}

/campaigns/{campaignId}/ideas/hot

/campaigns/{campaignId}/ideas/hot/{pageNumber}/{pageSize}

GET

Order by Hot Ideas in Descending

/ideas/hot/{pageNumber}/{pageSize}/{orderkey}

/campaigns/{campaignId}/ideas/hot/{pageNumber}/{pageSize}/{orderkey}

GET

Get Ideas In Review

/ideas/inreview

/ideas/inreview/{pageNumber}/{pageSize}

/campaigns/{campaignId}/ideas/inreview

/campaigns/{campaignId}/ideas/inreview/{pageNumber}/{pageSize}

GET

Order by Status Changed (In Review) in Descending

/ideas/inreview/{pageNumber}/{pageSize}/{orderkey}

/campaigns/{campaignId}/ideas/inreview/{pageNumber}/{pageSize}/{orderkey}

GET

Get Ideas In Progress

/ideas/inprogress

/ideas/inprogress/{pageNumber}/{pageSize}

/campaigns/{campaignId}/ideas/inprogress

/campaigns/{campaignId}/ideas/inprogress/{pageNumber}/{pageSize}

GET

Order by Status Changed (In Progress) in Descending

/ideas/inprogress/{pageNumber}/{pageSize}/{orderkey}

/campaigns/{campaignId}/ideas/inprogress/{pageNumber}/{pageSize}/{orderkey}

GET

Get Ideas in Complete state

/ideas/complete

/ideas/complete/{pageNumber}/{pageSize}

/campaigns/{campaignId}/ideas/complete

/campaigns/{campaignId}/ideas/complete/{pageNumber}/{pageSize}

GET

Order by Status Changed (Complete) in Descending

/campaigns/{campaignId}/ideas/complete/{pageNumber}/{pageSize}/{orderkey}

GET

Get Ideas by Tag

/ideas/tag/{tag}

/ideas/tag/{tag}/{pageNumber}/{pageSize}

/campaigns/{campaignId}/ideas/tag/{tag}

/campaigns/{campaignId}/ideas/tag/{tag}/{pageNumber}/{pageSize}

GET

Get Tag count and size metric

/tags/counts
/tags/counts/{pageNumber}/{pageSize}

GET

Order by Status Changed (Tags) in Descending

/ideas/tag/{tag}/{pageNumber}/{pageSize}/{orderkey}

/campaigns/{campaignId}/ideas/tag/{tag}/{pageNumber}/{pageSize}/{orderkey}

GET

Get All Tags For All Ideas

/ideas/tags

GET

Get Pending Ideas

/ideas/pending

/ideas/pending/{pageNumber}/{pageSize}

/campaigns/{campaignId}/ideas/pending

/campaigns/{campaignId}/ideas/pending/{pageNumber}/{pageSize}

GET

Order by Pending in Descending

/ideas/pending/{pageNumber}/{pageSize}/{orderkey}

/campaigns/{campaignId}/ideas/pending/{pageNumber}/{pageSize}/{orderkey}

GET

Get Pending Comments

/comments/pending

/comments/pending/{pageNumber}/{pageSize}

GET

Get Pending Members

/members/pending

/members/pending/{pageNumber}/{pageSize}

GET

Approve/Reject Pending member

/members/{memberId}/approve

/members/{memberId}/reject

POST

Approve/Reject Pending Idea

/ideas/{ideaId}/approve

/ideas/{ideaId}/reject

POST

Get Nonpending Ideas of A Campaign

/campaigns/{campaignId}/ideas/nonpending/{pageNumber}/{pageSize}

GET

Approve/Reject Pending Comment

/comments/{commentId}/approve

/comments/{commentId}/reject

POST

Get list of Flag event

/ideas/flag/events/{days}

/campaigns/{campaignId}/ideas/flag/events/{days}

/ideas/{ideaId}/flag/events

GET

Get list of Moderation event

/ideas/moderation/events/{days}

/campaigns/{campaignId}/ideas/moderation/events/{days}

/ideas/{ideaId}/moderation/events

/comments/moderation/events/{days}

/comments/{commentId}/moderation/events

GET

Change Idea Status

/idea/{ideaId}/status/set/{statusId}

GET

Get Assign owner to idea(downloads member info of eligible owners)

ideas/owners

GET

Add owner to an Idea

/ideas/owners
/ideas/{ideaID}/owner

POST

Assign owner to idea(takes array of member id's on request body, and adds those members to owner list)

/ideas/owners

POST

Assign owner to idea

/ideas/{ideaID}/owner

POST

Delete Ideas

/idea/{ideaId}/delete

DELETE

Delete all Ideas, Comments and Vote

/community/delete/ideas

DELETE

Delete all members and ideas including votes and comments from community

/community/delete/ideasAndMembers

DELETE

Get All Idea status

/idea/status/all

GET

Get Idea Information By Idea Number

/idea/number/{ideaNumber}

GET

Get Attachment Information By Member ID

/members/{memberId}/attachments

GET

Get Attachment Information By Idea ID

/ideas/{ideaId}/attachments

GET

Get All Attachment Information

/attachments

GET

Filter by campaign template for top and recent (ideation/qna)

/campaigns/templates/{templateID}/ideas/top
/campaigns/templates/{templateID}/ideas/top/{pageNumber}/{pageSize}
/campaigns/templates/{templateID}/ideas/top/{pageNumber}/{pageSize}/{orderkey}
/campaigns/templates/{templateID}/ideas/recent
/campaigns/templates/{templateID}/ideas/recent/{pageNumber}/{pageSize}
/campaigns/templates/{templateID}/ideas/recent/{pageNumber}/{pageSize}/{orderkey}

GET

Get Active ideas contents

/campaigns/active
/campaigns/active/ideas/status/custom/{statusKey}
/campaigns/active/ideas/top
/campaigns/active/ideas/recent
/campaigns/active/templates/{templateID}/ideas/recent
/campaigns/active/ideas/hot
/campaigns/active/ideas/inreview
/campaigns/active/ideas/inprogress
/campaigns/active/ideas/complete
/campaigns/active/ideas/tag/{tag}
/campaigns/active/ideas
/campaigns/active/ideas/pending

GET

Get Archived idea contents

/campaigns/archived
/campaigns/archived/ideas/status/custom/{statusKey}
/campaigns/archived/ideas/top
/campaigns/archived/ideas/recent
/campaigns/archived/templates/{templateID}/ideas/recent
/campaigns/archived/ideas/hot
/campaigns/archived/ideas/inreview
/campaigns/archived/ideas/inprogress
/campaigns/archived/ideas/complete
/campaigns/archived/ideas/tag/{tag}
/campaigns/archived/ideas
/campaigns/archived/ideas/pending

GET

Get custom field info of the campaign including community

/customFields/idea/campaigns/{campaignID}

GET

Get list of member custom fields of the community

/customFields/member

GET

Upload member Avatar image file

 /members/{MEMBER_ID}/avatar/upload

POST


Please Note:
{templateID} should be 0/1(ideation/qna)

Few {orderkey} points are given below to retrieve data in Descending or Ascending order:

date-down : This orders by creation date Descending.
date-up : This orders by creation date Ascending.
votes-down : This orders by most voted Descending.
votes-up : This orders by most voted Ascending.
comments-down : This orders by most commented Descending.
random-down : This orders by random column Descending.
status-down : This order by status Descending.
status.change.date-down : This orders by status changed date Descending.
amount-pledged-down : This orders by most funded Descending.
vote.and.comments-down : This order by voted and commented most Descending.

How to attach files to an idea using API:



How to attach avatar  using API:



Note: Page number starts from 0 (zero). Default page size is 25 when not specified.
When pagination is used, the response headers contain following information.
pager_total_count - total available items
pager_page_size    - current page size
pager_current_page_number - current page number
pager_first_index    - index of first item in current page (starts from 0)
pager_last_index - index of last item in current page

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

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):
/ideas
/ideas/{ideaId}/votes
/ideas/{ideaId}/comments
/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


Sample:
{ "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

campaign Id

Number

Optional

Campaign ID

tags

Array

Optional

String array of tags for the idea

customFields

Array

Optional

String array of custom fields choices


Sample:
Create Idea using JSON Structure:
{ "text":"Idea description via rest API", "tags":["API","SDK"], "title":"Idea Title via rest API", "campaignId":202 }

Create Idea with custom field value:
For example we have a multi-select custom field named "Department" and three choices "Account", "Admin" and "HR". The following request body will create an idea with the custom field value.
{"text":"My first idea from API call","title":"More Idea","tags":["API","SDK"],"campaignId":261,"customFields":{"Department":"Account"}}

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 }


Vote Down on Idea JSON Structure
Used by: /ideas/{ideaId}/vote/down

Field Name

Type

Required

Description

MyVote

Number

Optional

1 for disagree


Sample:
{ "myVote":1 }

Add a comment to an Idea


Comment on Idea JSON Structure
Used by: /ideas/{ideaId}/comment

Field Name

Type

Required?

Description

comment

String

Required

Comment to add


Sample:
{"text":"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

Contact Us

support@ideascale.com
http://assets2.desk.com/
false
ideascale
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete