defaultheader

API

Brightidea API is a RESTful interface to features provided by Brightidea web application. Through the use of the API requests, you have the ability to get, create, update and in some cases delete Brightidea data. Prior to making any requests, read the list below on requirements and behaviors:

  • Authentication is required prior to making API requests for most cases. See Authentication for information on the process.
  • To make a request, Access Token and Host Name are the two basic components needed.
  • All must requests goes through HTTPS.
  • Response is in JSON. You have the option to receive in XML by passing the proper parameter on each request.
  • All timestamps included in responses are in Eastern Standard Time.
  • All requests are subject to rate limiting. Exceeding any rate limits will result in error response. The default limit is set to 300 request per hour.
  • All parameter value must be URL encoded.
  • Request content type must be set to application/x-www-form-urlencoded




Construct an API Request

There are a few basic url structures to Brightidea API requests:

  • https://{host_name}/api3/{object}

  • https://{host_name}/api3/{object}/{id}

  • https://{host_name}/api3/widget/{object}

Parameters | Detail ----------------------- | ------------- {host_name} |This is host name of the Brightidea system that the API request is accessing. It's always in domain form.
Example: example.brightidea.com {object} |This is the name of the object your app is trying to take action on.
Example: member, idea, group... {id} |ID of an object.
Example: ../idea/11111111-1111-1111-1111-111111111111 request against idea with idea ID: 11111111-1111-1111-1111-111111111111.
../member/22222222-2222-2222-2222-222222222222 request against the member with that member ID. widget |For requesting widget API data.


Access Token

A valid access token must be present for most cases. Access token is obtained at the end of the Authentication process. There 2 ways access token can be passed in the API request.

  • Header: When access token is passed in header, it must use the attribute name "Authorization". Value must be prefixed with the string "Bearer", follow by a space, then the token value. Example: Authorization=Bearer 85f7b2462570acdde9a458ba6495b8763dcd040c.

  • Parameter: When passed as a POST or GET parameter, it must use the attribute name "accesstoken". Value is the token string. Example: accesstoken=85f7b2462570acdde9a458ba6495b8763dcd040c.


Parameters

Parameter requirements are different for each API function. Visit the Parameter section of each object page to understand what it takes to make a request.


Sample Requests

Get a list of member with last name "Smith".

  • Method: GET
  • Header: Authorization=Bearer 85f7b2462570acdde9a458ba6495b8763dcd040c
  • URL: https://example.brightidea.com/api3/member

  • Parameter: last_name=smith

    ~~~ { "memberlist": [ { "id": "80F31FEF-0802-4B7C-9B22-E9711B583036", "email": "BSmith@brightidea.com", "screenname": "Brett Smith", "firstname": "Brett", "lastname": "Smith", "jobtitle": "Assount Manaqueer", "address": "Relationschip Manaqueement", "phone": "8939200525852", "mobilephone": "52095295808", "externaluserid": "80888", "skills": "", "workhistory": "", "datecreated": "2013-03-07 18:20:17.797", "active": true }, { "id": "1B2777C8-CE9F-47AE-9B14-12C3E92DDCD1", "email": "larriesmith@brightidea.com", "screenname": "larriesmith", "firstname": "Larrie", "lastname": "Smith", "jobtitle": "Enqueineerinque Siestems Analiest", "address": "9509 Msckinneie St.", "phone": "0093-5298-529008", "mobilephone": "832-209-85528", "externaluserid": "larriesmith", "skills": "", "workhistory": "", "datecreated": "2013-03-07 18:20:01.053", "active": true }, { "id": "8FA49B96-3693-4282-8919-014618D7B3B8", "email": "lbondarenko@brightidea.com", "screenname": "Lillian Smith", "firstname": "Lillian", "lastname": "Smith", "jobtitle": "", "address": "", "phone": "", "mobilephone": "", "externaluserid": "", "skills": "", "workhistory": "", "photourl": "", "datecreated": "2013-03-07 17:10:13.627", "datemodified": "2013-04-16 15:42:16.430", "active": true, "department": "" } ], "stats": { "total": "3", "pagecount": 1, "currentpage": 1 } } ~~~



Update the title of a specific idea.

  • Method: PUT
  • Header: Authorization=Bearer 85f7b2462570acdde9a458ba6495b8763dcd040c
  • URL: https://example.brightidea.com/api3/idea/E62DB922-55EE-419D-9CB9-4C4DD8243ADA

  • Parameter: title="Test%20Idea%20Title%20Updated"

    ~~~ { "idea": { "id": "E62DB922-55EE-419D-9CB9-4C4DD8243ADA", "datecreated": "2013-04-15 15:42:39.360", "datemodified": "2013-04-16 15:54:18.027", "title": "Test Idea Title Updated", "description": "Test Idea Description.", "visible": true, "anonymous": false, "ideacode": "D629", "score": 1, "member": { "id": "866144B1-E302-42EF-AF80-75DE988885AE", "screenname": "John Doe", "firstname": "John", "lastname": "Doe", "jobtitle": "Sales", "address": "123 fake street", "phone": "123 456-789", "mobilephone": "987 654-3210", "externaluserid": "04567", "skills": "Selling Software", "workhistory": "Worked at sales.com", "photourl": "https://example.brightideatest.com/api3/file/02F11D0E-BA74-4A7D-B1BE-4F7F651B2507?format=binary&thumbsize=100", "datecreated": "2013-03-07 19:09:54.563", "datemodified": "2013-04-18 13:14:21.067", "active": true, "photofileid": "02F11D0E-BA74-4A7D-B1BE-4F7F651B2507", "department": "Some department" }, "category": { "id": "C893B9AF-0622-4568-B56F-77600DE1EFAC", "name": "Category 1" }, "status": { "id": "D329EF01-D051-40AB-BB18-F13C03F3BE9C", "name": "New" }, "campaign": { "id": "0A140858-AD8A-4F97-9926-D80AD156A130", "name": "Sample Campaign", "description": "Sample Campaign Description", "datecreated": "2013-03-07 17:10:38.107" } } } ~~~



Get post idea widget of a campaign.

  • Method: GET
  • Header: Authorization=Bearer 85f7b2462570acdde9a458ba6495b8763dcd040c
  • URL: https://example.brightidea.com/api3/widget/postIdea

  • Parameter: campaign_id="0A140858-AD8A-4F97-9926-D80AD156A130"

    ~~~ { "questions": [ { "id": "title", "description": "Title of your idea", "required": true, "type": "text" }, { "id": "description", "description": "Describe your idea clearly", "required": true, "type": "richtext" }, { "id": "categoryid", "description": "Select a Category", "required": true, "type": "select", "options": [ { "id": "4FF9AF25-D67A-4AD1-BA2E-2AF692620DEF", "order": 1, "numideasincat": 111, "description": "Category 1" }, { "id": "C893B9AF-0622-4568-B56F-77600DE1EFAC", "order": 2, "numideasin_cat": 100, "description": "Category 2" }, ] }, { "id": "attachments", "description": "Attachment", "required": false, "type": "attachment" },

    ]

    } ~~~




User and Data

The data returns from an API request is tied to the access permission of the authenticated user. This user is refered to as the "Requester" all through out the document. Requester receives only data that he has permission to access base on the Brightidea web application.

Besides data access, permission to certain action is restricted base on the Requester's role in the web application. For example, admin can create a member or a group where regular user cannot.

You can find details on who can see and do what in documentation of individual object.