Retrieving Survey Response Data

In this article, we will go over the responses endpoint that the Bizrate Survey API offers for retrieving survey data. For more information on the API, please check out our ReadMe documentation.

In order to access the Bizrate Survey API, you must have an access token granted to you by following the steps in the previous article. Each request to the endpoints listed in this article must contain the access token in the Authorization field of the HTTP request header.

Example Header Request:

curl "https://api.bizratesurveys.com/v1/responses?beginTime=1617235200000&endTime=1622505600000"
-H "Authorization: Bearer *******************************************="

Retrieving responses given a date range

GET Retrieve all response data given a time frame (optional) and survey type(s) (optional) ordered by response date.

REQUEST:
Query Parameters Type Required Default Value Description
surveyType array false n/a Array of survey types that will be used to filter out responses that contain the given types. If empty, no filter will be applied to the responses.
cursor string false first response after the beginTime value The starting cursor index for filtering responses. If cursor is specified, but not size, then size defaults to 500. If size is specified, but not cursor, then cursor defaults to the first response after beginTime param.
size integer false 500 The max number of responses to return. If cursor is specified, but not size, then size defaults to 500. If size is specified, but not cursor, then cursor defaults to the first response after beginTime. Max size is 500 and any value greater will return a 400 error code.
beginTime integer true n/a Timestamp to start search from, epoch time in milliseconds. beginTime must be less than endTime and both should be within the duration of the merchant’s subscription period.
endTime integer true n/a Timestamp to stop searching at, epoch time in milliseconds. endTime should be greater than beginTime and both should be within the duration of the merchant’s subscription period.
RESPONSE:

The object returned will contain two “root-level” fields: responses and cursor. The responses array will contain one or more response objects that are also the ‘parent’ object to several child objects including device_info and meta_data. The second “root-level” field is cursor, which will provide a value that can be used as a query parameter in subsequent requests to retrieve the next set of responses.

Fields for Response object Type Description
response_id string Survey response ID
respondent_id string Unique id of the individual who took the survey
merchant_id string Merchant ID
survey_date string The date that the survey was taken. Dates are returned in Pacific Standard Time.
survey_type string Type of the survey taken. Refer to the section below to review the list of survey_type.
device_info object {
“device_type”: string
“browser”: string
“os”: string
“width”: string
“height”: string
“user_agent”: string
}
metadata object {
“custom”: object
“site_abandonment”: object
}
metadata.custom object {
“custom_value_1”: string,
“custom_value_2”: string
}
custom_value_1 and custom_value_2 are additional push values chosen by the merchant to be used in analytics.
metadata.site_abandonment object {
“timeOnSite”: string,
“pageId”: string,
“pageViews”: string
}
This object will only be included in the response for Site Abandonment (SA) type surveys.
response_answers array Array containing response_answer objects. See below for the description of the response_answer fields.
response_answer object {
“question_id”: string,
“question_label”: string,
“question_type”: string,
“answers”: array
}
Refer to the section below to review the list of question_type.
response_answer.answers array Array containing answer objects. See below for the description of the answer fields.
answer object {
“answer_text”: string,
“answer_value”: string
}
TYPES OF SURVEYS:

The table below shows a list of possible values for survey_type. The values returned in the response can change based on merchant implementation.

Survey Types Names
POS Point of Sale
FF Fulfillment
STFF Straight to Fulfillment
BOPIS Buy Online Pick Up In Store
SA Site Abandonment
CS Custom Surveys
EXAMPLE REQUEST:
curl -X GET "https://api.bizratesurveys.com/v1/responses?surveyType=POS&surveyType=FF&size=500&beginTime=1617235200000&endTime=1622505600000&cursor=MTYzNTEyNDQ5NDAwMCA1NDY5OTI4" 
-H "accept: application/json"
-H "Content-Type: application/json"
-H "Authorization: Bearer *******************************************="
EXAMPLE RESPONSE:
{
"responses": [
{
"response_id": "R_2eOrB9d1qIwPzXq",
"respondent_id": "1633543480093484437",
"merchant_id": "170739",
"survey_date": "Oct 7, 2021, 6:05:34 PM",
"survey_type": "POS",
"device_info": {
"device_type": "DESKTOP/LAPTOP",
"browser": "Chrome 94.0.4606.71",
"os": "Windows",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.71 Safari/537.36"
},
"metadata": {
"referrerUrl":"https://www.lockwood&alice.com/,
"webAnalyticsId": "GA1.2.323527645.1616337529",
"custom":
{
"customValue1": "Custom Text 1",
"customValue2": "Custom Text 2"
},
"siteAbandonment": {
"timeOnSite": "1:30",
"pageId": "/index",
"pageViews": 4
}
},
"response_answers": [
{
"question_id": "100DEL",
"question_label": "Which shipping option did you select for this order?",
"question_type": "Single Select",
"answers": [
{
"answer_text": "Ship to residence or business",
"answer_value": "1"
}
]
},
{
"question_id": "Q15_C11779",
"question_label": "Overall purchase experience",
"question_type": "Matrix",
"answers": [
{
"answer_text": "2",
"answer_value": "2"
}
]
},
{
"question_id": "Q16_C11780",
"question_label": "Likelihood to buy again",
"question_type": "Matrix",
"answers": [
{
"answer_text": "2",
"answer_value": "2"
}
]
}
]
},
{
"response_id": "R_SZdtaWNFIFeGhSF",
"respondent_id": "1633573466984586247",
"merchant_id": "170739",
"survey_date": "Oct 7, 2021, 3:19:37 AM",
"survey_type": "FF",
"device_info": {
"device_type": "IPAD",
"browser": "Mobile Safari 11.0",
"os": "iOS",
"width": "768",
"height": "1024"
},
"metadata": {
"custom": {},
"site_abandonment": {}
},
"response_answers": [
{
"question_id": "BO122",
"question_label": "Nickname:",
"question_type": "Open Text",
"answers": [
{
"answer_text": "Carla"
}
]
},
{
"question_id": "REGION",
"question_label": "Region",
"question_type": "Open Text",
"answers": [
{
"answer_text": "NY"
}
]
},
{
"question_id": "CITY",
"question_label": "City",
"question_type": "Open Text",
"answers": [
{
"answer_text": "New York"
}
]
}
]
}
]
"cursor": "MTYzNDY3Nzk2MTAwMCAxODQzNzgz"
}

Powered by BetterDocs