Panel API

What is a Panel API?

The Panel API allows users to access their panel through an API and perform view, create and add operations. Users may want to know what fields are present in the panel, access specific member details and update the same.

How can users use this feature?

Users will have to call a URL entailing the request type and pass specific details as required by the API call. The information will be in JSON format.

What are the different API calls that can be made?

• Create/Update Panel Members Record
• Export Panel Members Data
• Export Reward Stats
• Export Panel Members Data for Active Campaigns Batches
• Get Available Sample Criteria to Select/Filter Members.
• Get Available Sample Count for given Selection/Sample Criteria
• Get the Price Per Response for the given Selection/Sample Criteria
• Send Survey Invitation to Panel Members
• Get the Rewards List for a Panel
• Redeem Points against the Rewards

What will the API call look like?

An API call looks like:

www.surveyanalytics.com/a/api/surveyanalytics.micropanel. {FUNCTION-NAME} ?apiKey= {API-KEY}

Where

1. {FUNCTION-NAME}: can be
   • panelMemberUpdate (For updating Panel Members Record)
   • panelDataExport (For panel data export)
   • exportRewardStats (For Rewards Stats export)
   • panelMemberExport (For Panel Members Data for Active campaigns export)
2. {API-KEY}:

   To set up API Key, go to:

   • Login »  Communities »  (Select Community) »  Modules »  SurveySwipe »  API Key
   Click on Register New API Key and the key will be generated. Use this key for setting up API integration.

An example for API call to export Rewards Stats:

www.surveyanalytics.com/a/api/surveyanalytics.micropanel.exportRewardStats?apiKey=7042c040-11a7-4344-a8b2-66cd473fee6b

1) panelMemberUpdate

Purpose

You can use the panelMemberUpdate method to update or modify the panel members profile.

Request URL

www.surveyanalytics.com/a/api/surveyanalytics.micropanel. panelMemberUpdate ?apiKey={ API-KEY }

Request Parameters

* - Mandatory parameter

NOTE :- For each member added through API call an email-verification Email will be sent if Double-Opt-In Verification is turned on. To disable got to: Login>>Panels>>Email Preferences>>(New User Email Verification Template)>>(Enable Double Opt/In Verification Email for Web-Signups - Template)

JSON Data Format:

The JSON format starts with the panelMembers object which is an array where each element has parameters for the specified panel Member to be updated. Each JSON parameter has been explained below. After the JSON parameters there is an example of JSON structure with explanation.

JSON Parameters : Parameters for 'fields' array: NOTE:

* - Mandatory parameter.

All the parameter names are Case Sensitive.

Example :

Below is an example of JSON format for updating details for two panel members ([email protected] & [email protected]). For both panel members we are updating four fields. Where profile fields are:

{ "panelMembers": [ { "emailAddress": "[email protected]", "firstName": "abc", "lastName": "last name", "address1": "1234 W Main St.", "address2": "Suite 102", "city": "Newark", "state": "New Jersey", "zipCode": "37064", "country": "USA", "fields": [ {"id": 1001, "answers": [1,3]}, {"id": 1002, "answers": [2]}, {"id": 1003, "date": "04-22-2012"}, {"id": 1004, "text": "No comments"} ] }, { "emailAddress": "[email protected]", "firstName": "xyz", "lastName": "last name", "fields": [ {"id": 1001, "answers": [0,2,4]}, {"id": 1002, "answers": [3]}, {"id": 1003, "date": "04-21-2012"}, {"id": 1004, "text": "It was a great experience."} ] } ] }

2) panelDataExport

Purpose

You can use the panelDataExport method to export details for all the Panel Members.

Request URL

www.surveyanalytics.com/a/api/surveyanalytics.micropanel. panelDataExport ?apiKey={ API-KEY }

Request Parameters

* - Mandatory parameter

Example :

{ "response": { "id": 9100, "title": "Panel Name", "name": "Panel Name", "report": { "title": "Panel Data Export", "data": [ { "US universities": "", "Last Invitation Date": "", "Surveys Sent": 0, "Profile Complete Date": "", "Completed Surveys": 0, "single select global": "", "Timestamp": "2012-03-23 01:44:17.0", "Zip code": "", "Signup IP Address": "Imported Member", "Source": "Survey", "Status": "New", "Birthday": "", "Total Points": 10, "ID": 789356, "Tracking Source": "", "Email Address": "[email protected]", "Zip Code": "", "US university 2": "", "Last Name": "Sharma", "First Name": "Vishal" }, { "US universities": "", "Last Invitation Date": "2012-03-11 08:26:15.0", "Surveys Sent": 10, "Profile Complete Date": "2012-02-15 21:37:31.0", "Completed Surveys": 3, "single select global": "1", "Timestamp": "2011-12-29 03:41:04.0", "Zip code": "1234", "Signup IP Address": "Imported Member", "Source": "Upload", "Status": "Verified", "Birthday": "1901-01-01", "Total Points": 90, "ID": 316486, "Tracking Source": "", "Email Address": "[email protected]", "Zip Code": "1234", "US university 2": "", "Last Name": "", "First Name": "" }, ] } }, "status": { "message": "OK", "id": 200, "method": "surveyanalytics.micropanel.panelDataExport", "serverUTC": 1335427753345, "url": "/a/api/surveyanalytics.micropanel.panelDataExport", "apiKey": "7042c040-11a7-4344-a8b2-66cd473fee6b" } }

3) exportRewardStats

Purpose

You can use the exportRewardStats method to export the Rewards Summary report and details for each reward.

Request URL

www.surveyanalytics.com/a/api/surveyanalytics.micropanel. exportRewardStats ?apiKey={ API-KEY }

Request Parameters

* - Mandatory parameter

Example :

{ "response": { "id": 9100, "title": "Panel Name", "name": "Panel Name", "report": { "sheets": [ { "title": "Rewards Summary Report", "data": [ { "Status": "Active", "Reward ": "$10 Amazon Gift Certificate", "ID": 673, "Points required to Claim": 0 } ] }, { "Reward ID": 673, "title": "Summary for $10 Amazon Gift Certificate", "Reward": "$10 Amazon Gift Certificate", "data": [] } ] } }, "status": { "message": "OK", "id": 200, "method": "surveyanalytics.micropanel.exportRewardStats", "serverUTC": 1335427846205, "url": "/a/api/surveyanalytics.micropanel.exportRewardStats", "apiKey": "7042c040-11a7-4344-a8b2-66cd473fee6b" } }

4) panelMemberExport

Purpose

You can use the panelMemberExport method to view panel member details for Active Campaign Batches. You can view each member's survey Status (completed, pending, etc.), reminder count, points, etc.

Request URL

www.surveyanalytics.com/a/api/surveyanalytics.micropanel. panelMemberExport ?apiKey={ API-KEY }

Request Parameters

* - Mandatory parameter

Example :

{ "response": { "id": 9100, "title": "Panel Name", "name": "Panel Name", "report": { "title": "Panel Member Data", "data": [ { "Status": "Pending", "Response ID": 0, "Survey ID": 2817650, "Survey Name": "One Question", "Panel Member ID": 316486, "Email Address": "[email protected]", "Points": 25, "Reminder Count": 0, "Timestamp": "2012-03-11 08:26:15.0" }, { "Status": "Pending", "Response ID": 0, "Survey ID": 2817650, "Survey Name": "One Question", "Panel Member ID": 316486, "Email Address": "[email protected]", "Points": 25, "Reminder Count": 0, "Timestamp": "2012-02-11 02:38:38.0" }, { "Status": "Terminated", "Response ID": 6231410, "Survey ID": 2903524, "Survey Name": "survey with terminate", "Panel Member ID": 316486, "Email Address": "[email protected]", "Points": 10, "Reminder Count": 0, "Timestamp": "2012-02-15 21:36:22.0" }, ] } }, "status": { "message": "OK", "id": 200, "method": "surveyanalytics.micropanel.panelMemberExport", "serverUTC": 1335427623336, "url": "/a/api/surveyanalytics.micropanel.panelMemberExport", "apiKey": "7042c040-11a7-4344-a8b2-66cd473fee6b" } }

5) getSampleCriteria

Purpose

You can use the getSampleCriteria call to get the available sample criteria to select/filter members.

Request URL

www.surveyanalytics.com/a/api/surveyanalytics.micropanel.getSampleCriteria?apiKey={API-KEY}

* - Mandatory parameter

Response JSON Parameters :

Response JSON Example :

{"response": {"title": "Sample Panel", "customFieldCriteria": [ { "customFieldID": 426, "title": "Which country do you live in?", "customFieldChoices": [ { "name": "India", "choiceID": 472 }, { "name": "USA", "choiceID": 473 }, { "name": "Canada", "choiceID": 474 }, { "name": "England", "choiceID": 475 }, { "name": "France", "choiceID": 493 } ], "label": "Which country do you live in?", "type": 21 }, { "customFieldID": 437, "title": "In which type of industry do you work?", "customFieldChoices": [ { "name": "Healthcare", "choiceID": 485 }, { "name": "Education", "choiceID": 486 }, { "name": "Banking/Finance", "choiceID": 487 }, { "name": "Government", "choiceID": 488 } ], "label": "In which type of industry do you work?", "type": 20 }, { "customFieldID": 438, "title": "Do you work full-time or part-time?", "customFieldChoices": [ { "name": "Full-Time", "choiceID": 489 }, { "name": "Part-Time", "choiceID": 490 } ], "label": "Do you work full-time or part-time?", "type": 20 } ], "description": "Sample Panel" }, "status": { "message": "OK", "id": 200, "method": "surveyanalytics.micropanel.getSampleCriteria", "serverUTC": 1391507297387, "url": "/a/api/surveyanalytics.micropanel.getSampleCriteria", "apiKey": "3d14fd32-5ec7-4c60-bc49-583e01fa528a" } }

6) getCountForSample

Purpose

You can use the getCountForSample call to get the available sample count for given selection/sample criteria.

Request URL

www.surveyanalytics.com/a/api/surveyanalytics.micropanel.getCountForSample?apiKey={API-KEY}

Request Parameters

* - Mandatory parameter

JSON Data Format:

The JSON format starts with the customFieldCriteria JSON array with each element being field for which you want to filter panel members.

JSON Parameters : Parameters for 'customFieldCriteria' array: NOTE:

* - Mandatory parameter.

All the parameter names are Case Sensitive.

Input JSON Example:

{"customFieldCriteria":[{"customFieldID":426, "customFieldChoices":[472]}]}

Response JSON Parameters :

Response JSON Example:

{"response":{"availableSampleCount":5291, "title":"Sample Panel"}, "status":{"message":"OK", "id":200, "method":"surveyanalytics.micropanel.getCountForSample", "serverUTC":1391512758696, "url":"/a/api/surveyanalytics.micropanel.getCountForSample", "apiKey":"3d14fd32-5ec7-4c60-bc49-583e01fa528a"}}

7) getPricingForSample

Purpose

You can use the getPricingForSample call to get the price per response for the given selection/sample criteria.

Request URL

www.surveyanalytics.com/a/api/surveyanalytics.micropanel.getPricingForSample?apiKey={API-KEY}

Request Parameters

* - Mandatory parameter

JSON Data Format:

The JSON format starts with the customFieldCriteria JSON array with each element being field for which you want to filter panel members.

JSON Parameters : Parameters for 'customFieldCriteria' array: NOTE:

* - Mandatory parameter.

All the parameter names are Case Sensitive.

Input JSON Example:

{"customFieldCriteria":[{"customFieldID":426, "customFieldChoices":[472]}]}

Response JSON Parameters :

Response JSON Example:

{"response":{"title":"Sample Panel", "costPerResponse":5}, "status":{"message":"OK", "id":200, "method":"surveyanalytics.micropanel.getPricingForSample", "serverUTC":1391513279758, "url":"/a/api/surveyanalytics.micropanel.getPricingForSample", "apiKey":"3d14fd32-5ec7-4c60-bc49-583e01fa528a"}}

8) executeSampleForCriteria

Purpose

You can use the executeSampleForCriteria API call to send survey invitation to panel members for the given selection/sample criteria.

Request URL

www.surveyanalytics.com/a/api/surveyanalytics.micropanel.executeSampleForCriteria?apiKey={API-KEY}

Request Parameters

* - Mandatory parameter

JSON Parameters : Parameters for 'customFieldCriteria' array: NOTE:

* - Mandatory parameter.

All the parameter names are Case Sensitive.

Input JSON Example:

{"customFieldCriteria":[{"customFieldID":426, "customFieldChoices":[472]}],"isExternalSurvey": false, "surveyID": 3652, "emailSubject": "Take survey now!", "emailMessage": "Thank you for joining the Panel research community. We have a very interesting study for you, which shouldn't take more than 8 minutes of your time. As always, we value your feedback and assure you that the data collected will only be used for research purposes. In essence, we ask that you provide your candid and honest opinion"}

Response JSON Parameters :

Response JSON Examples:

Success: {"response":{"title":"Sample Panel", "success":"Batch created successfully. Delivery in progress."}, "status":{"message":"OK", "id":200, "method":"surveyanalytics.micropanel.executeSampleForCriteria", "serverUTC":1391587759449, "url":"/a/api/surveyanalytics.micropanel.executeSampleForCriteria", "apiKey":"3d14fd32-5ec7-4c60-bc49-583e01fa528a"}}

Error: {"response":{"title":"Sample Panel", "errors":["Survey not found for ID 32652"]}, "status":{"message":"OK", "id":200, "method":"surveyanalytics.micropanel.executeSampleForCriteria", "serverUTC":1391588038334, "url":"/a/api/surveyanalytics.micropanel.executeSampleForCriteria", "apiKey":"3d14fd32-5ec7-4c60-bc49-583e01fa528a"}}

9) getRewardsListForMember

Purpose

You can use the getRewardsListForMember API call to view all the Rewards in the Panel. You can view each rewards details such as Reward ID, Points, Image Url, Gift card description, etc.

Request URL

www.surveyanalytics.com/a/api/surveyanalytics.micropanel. getRewardsListForMember ?apiKey={ API-KEY }

Request Parameters

* - Mandatory parameter

JSON Data Format

The JSON Format contains the key value pair of the required parameter.

JSON Parameters : NOTE:

* - Mandatory parameter.

All the parameter names are Case Sensitive.

Input JSON Example:

{"memberEmailAddress":"[email protected]"}

Response JSON Parameters :

Parameters for 'Rewards' array: Response JSON Example:

{ "response": { "panelID":571, "panelMemberID":1217, "Rewards": [ { "eligibleForRedemptionMessage":"Redeem Reward", "giftCardDescription":"$10 Amazon.com Gift Card", "imageUrl":"http://www.surveyanalytics.com/images/amazon.gif", "qPointRewardID":311, "points":100, "isEligibleForRedemption":"Y" }, { "eligibleForRedemptionMessage":"Redeem Reward", "giftCardDescription":"2 Movie Tickets", "imageUrl":"http://www.surveyanalytics.com/images/movie-ticket.jpg", "qPointRewardID":312, "points":100, "isEligibleForRedemption":"Y" }, { "eligibleForRedemptionMessage":"Not Available", "giftCardDescription":"1000 Points = $10 Donation", "imageUrl":"http://www.surveyanalytics.com/images/charity.png", "qPointRewardID":313, "points":100, "isEligibleForRedemption":"N" }, { "eligibleForRedemptionMessage":"Redeem Reward", "giftCardDescription":"$10 Amazon.ca", "imageUrl":"https://dwwvg90koz96l.cloudfront.net/graphics/item-images/amazon-canada-gift-card.png", "qPointRewardID":315, "points":100, "isEligibleForRedemption":"Y" } ] }, "status": { "message":"OK", "id":200, "method":"surveyanalytics.micropanel.getRewardsListForMember", "serverUTC":1403775450735, "url":"/a/api/surveyanalytics.micropanel.getRewardsListForMember", "apiKey":"44262182-f3d2-410c-9fb8-675042180785" } }

10) redeemReward

Purpose

You can use the redeemReward API call to redeem points against reward. You can view the redemption reward details such as rewardID, amount redeemed, reward identifier, redeem message, etc.

Request URL

www.surveyanalytics.com/a/api/surveyanalytics.micropanel. redeemReward ?apiKey={ API-KEY }

Request Parameters

* - Mandatory parameter

JSON Data Format

The JSON Format contains the key value pair of the required parameter.

JSON Parameters : NOTE:

* - Mandatory parameter.

All the parameter names are Case Sensitive.

Input JSON Example:

{"memberEmailAddress":"[email protected]","rewardID":315,"disclaimerAccepted":"Survey Analytics is not liable for redemption related issues"}

Response JSON Parameters :

Response JSON Example

{ "response": { "amountRedeemed":100, "redeemMessage":"Reward redeemed successfully", "redemmedDate":"24-25-2014 18:24:05", "orderID":114-06516166-25, "qPointRewardID":315, "rewardIdentifier":"$10 Amazon.ca", "panelMemberID":1217, "panelID":571 } , "status": { "message":"OK", "id":200, "method":"surveyanalytics.micropanel.redeemReward", "serverUTC":1403775969379, "url":"/a/api/surveyanalytics.micropanel.redeemReward", "apiKey":"44262182-f3d2-410c-9fb8-675042180785" } }