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.
    Survey Software Help Image

An example for API call to export Rewards Stats:

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

All the API calls are explained below:

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
Parameter DataType Description
apiKey* String Encrypted alphanumeric string to authenticate your credentials.Please refer the following link for further information: API KEY

* - 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 :
Parameter Description
emailAddress* Email Address of the panel Member whose profile needs to be updated. Panel member is identified on the basis of email Address. It is a required field. NOTE:- If panel member is not found for the given email address new panel member will be created .
firstName First name of the panel member.
address1 Address1
address2 Address2
City City
State State
zipCode Zip code
Country Country
fields Profile fields array where each element is the profile field that needs to be updated. The details for how to construct each element for this array is given below.
Parameters for 'fields' array:
Parameter Description
id* ID of the profile field that needs to be updated. This will be provided by us. It is unique for each profile field.
answers* This field is required ONLY for single-select and multiple-select profile field Types. It is a JSON array with each element being the index of the option selected. For e.g. If the field is multiple-select and has five options. And user selects 1st and 3rd option the values sent should be 0 & 2. For single-select field only one value needs to be sent. NOTE:- The answer index starts from 0.
date* This field is only required for date/birthday profile field type. The date must be in the format : “MM-dd-yyyy” .
text* This field is only required for free form profile field types (large text, single line text box, numeric) and zip code profile field type.
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 (abc@abc.com & xyz@xyz.com). For both panel members we are updating four fields. Where profile fields are:

Field id-1001 is a Multiple-select field type having 5 options. abc has selected 2nd & 4th option and xyz has selected 1st , 3rd & 5th option. Note that option index starts from 0.
Field id-1002 is Single-select having 4 options. abc has selected 3rd option and xyz has selected 4th option.
Field id-1003 is Date type. Date must be in format ‚MM-dd-yyyy. Field id- 1004 is a Large text description type.

{ "panelMembers": [ { "emailAddress": "abc@abc.com", "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": "xyz@xyz.com", "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
Parameter DataType Description
apiKey* String Encrypted alphanumeric string to authenticate your credentials.Please refer the following link for further information: API KEY

* - 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": "vishal.chd@gmail.com", "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": "anish.bhanwala@surveyanalytics.com", "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
Parameter DataType Description
apiKey* String Encrypted alphanumeric string to authenticate your credentials.Please refer the following link for further information: API KEY

* - 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
Parameter DataType Description
apiKey* String Encrypted alphanumeric string to authenticate your credentials.Please refer the following link for further information: API KEY

* - 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": "anish.bhanwala@surveyanalytics.com", "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": "anish.bhanwala@surveyanalytics.com", "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": "anish.bhanwala@surveyanalytics.com", "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 :

Parameter Description
title Panel name.
customFieldCriteria Array of all the profile fields (only single-select & multi-select)
customFieldID Profile field ID. This is required for other API calls: getCountForSample & getPricingForSample
title Profile field title
type Profile field type. 21=Multi-select, 20=Single-select
customFieldChoices Array of choices available for the given profile field
name Profile field choice name
choiceID Profile field choice ID. This is required for other API calls: getCountForSample & getPricingForSample
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
Parameter DataType Description
apiKey* String Encrypted alphanumeric string to authenticate your credentials.Please refer the following link for further information: API KEY

* - 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 :
Parameter Description
customFieldCriteria* JSON array in which each element is a profile field for which you want to filter panel members.
Parameters for 'customFieldCriteria' array:
Parameter Description
customFieldID* ID of the profile field. It is unique for each profile field. See getSampleCriteria API call on how to get the profile field IDs. NOTE: Only single-select & multi-select fields are allowed in selection criteria.
customFieldChoices* It is a JSON array with each element being the choice ID of the profile field choices. See getSampleCriteria API call on how to get the profile field IDs and choice IDs.
NOTE:

    * - Mandatory parameter.

    All the parameter names are Case Sensitive.

Input JSON Example:

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

Response JSON Parameters :

Parameter Description
availableSampleCount Number of panel members available for the give sample/selection criteria.
title Panel name/title.
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
Parameter DataType Description
apiKey* String Encrypted alphanumeric string to authenticate your credentials.Please refer the following link for further information: API KEY

* - 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 :
Parameter Description
customFieldCriteria* JSON array in which each element is a profile field for which you want to filter panel members.
Parameters for 'customFieldCriteria' array:
Parameter Description
customFieldID* ID of the profile field. It is unique for each profile field. See getSampleCriteria API call on how to get the profile field IDs. NOTE: Only single-select & multi-select fields are allowed in selection criteria.
customFieldChoices* It is a JSON array with each element being the choice ID of the profile field choices. See getSampleCriteria API call on how to get the profile field IDs and choice IDs.
NOTE:

    * - Mandatory parameter.

    All the parameter names are Case Sensitive.

Input JSON Example:

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

Response JSON Parameters :

Parameter Description
costPerResponse Cost per response for give selection/sample criteria.
title Panel name/title.
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
Parameter DataType Description
apiKey* String Encrypted alphanumeric string to authenticate your credentials.Please refer the following link for further information: API KEY

* - Mandatory parameter

JSON Parameters :
Parameter Description
customFieldCriteria* JSON array in which each element is a profile field for which you want to filter panel members.
isExternalSurvey* True if you are using system OTHER than SurveyAnalytics. For more information see 'External Passback Link' in 'You may also be interested in...' section at the bottom of page.
externalSurveyURL Required if 'isExternalSurvey' parameter is true. For more information see 'External Passback Link' in 'You may also be interested in...' section at the bottom of page.
surveyName Required if 'isExternalSurvey' parameter is true. Name of the external survey.
surveyID Required if 'isExternalSurvey' parameter is false. ID of the survey you want to deploy.
emailSubject* Email Subject
emailMessage* Email message body.
completePoint Points to be awarded to panel member for completing survey.
terminatePoint Points to be awarded to panel member if survey is terminated.
quotaPoint Points to be awarded to panel member if survey quota is over.
surveyLength* Duration of Survey in minutes
isStickyMode Allow survey to be taken multiple times by same panel member.
Parameters for 'customFieldCriteria' array:
Parameter Description
customFieldID* ID of the profile field. It is unique for each profile field. See getSampleCriteria API call on how to get the profile field IDs. NOTE: Only single-select & multi-select fields are allowed in selection criteria.
customFieldChoices* It is a JSON array with each element being the choice ID of the profile field choices. See getSampleCriteria API call on how to get the profile field IDs and choice IDs.
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 :

Parameter Description
success 'success' message if batch was sent successfully
errors Array of errors.
title Panel name/title.
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
Parameter DataType Description
apiKey* String Encrypted alphanumeric string to authenticate your credentials.Please refer the following link for further information: API KEY

* - Mandatory parameter

JSON Data Format

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

JSON Parameters :
Parameter Description
panelID* Panel ID of the panel for which Rewards List is required.
memberEmailAddress* Email Address of the panel member. Panel member is identified on the basis of email Address. It is a required field.
NOTE:

    * - Mandatory parameter.

    All the parameter names are Case Sensitive.

Input JSON Example:

{"memberEmailAddress":"a@a.com"}

Response JSON Parameters :

Parameter Description
panelID An unique ID of the Panel
panelMemberID This is an unique ID of the panel member
Rewards It is a JSON array where each element represents reward details
Parameters for 'Rewards' array:
Parameter Description
qPointRewardID An unique ID of the Reward
giftCardDescription Reward gift card description
imageUrl gift card image url
points Reward points
isEligibleForRedemption A flag with values of "Y" or "N" indicating rewards eligibility for redemption
eligibleForRedemptionMessage Rewards eligibility for redemption message
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
Parameter DataType Description
apiKey* String Encrypted alphanumeric string to authenticate your credentials.Please refer the following link for further information: API KEY

* - Mandatory parameter

JSON Data Format

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

JSON Parameters :
Parameter Description
panelID* Panel ID of the panel for which Rewards List is required.
memberEmailAddress* Email Address of the panel member. Panel member is identified on the basis of email Address. It is a required field.
rewardID* The id of the Reward for which the points has to be redeemed
disclaimerAccepted Survey Analytics is not liable for redemption related issues
NOTE:

    * - Mandatory parameter.

    All the parameter names are Case Sensitive.

Input JSON Example:

{"memberEmailAddress":"a@a.com","rewardID":315,"disclaimerAccepted":"Survey Analytics is not liable for redemption related issues"}

Response JSON Parameters :

Parameter Description
panelID An unique ID of the Panel
panelMemberID This is an unique ID of the panel member
amountRedeemed The amount which is redeemed
redeemMessage Reward redemption status message
redeemedDate Reward redemption date
rewardIdentifier Reward description
qPointRewardID Reward ID
orderID This is the merchant transaction ID for the Tango Card
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" } }

War dieser Artikel hilfreich?
Das tut uns leid
Wie können wir es verbessern?
einreichen