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 ParametersTypeRequiredDefault ValueDescription
surveyTypearrayfalsen/aArray 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.
cursorstringfalsefirst response after the beginTime valueThe 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.
sizeintegerfalse500The 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.
beginTimeintegertruen/aTimestamp 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.
endTimeintegertruen/aTimestamp 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 objectTypeDescription
response_idstringSurvey response ID
respondent_idstringUnique id of the individual who took the survey
merchant_idstringMerchant ID
survey_datestringThe date that the survey was taken. Dates are returned in Pacific Standard Time.
survey_typestringType of the survey taken. Refer to the section below to review the list of survey_type.
device_infoobject{
“device_type”: string
“browser”: string
“os”: string
“width”: string
“height”: string
“user_agent”: string
}
metadataobject{
“custom”: object
“site_abandonment”: object
}
metadata.customobject{
“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_abandonmentobject{
“timeOnSite”: string,
“pageId”: string,
“pageViews”: string
}
This object will only be included in the response for Site Abandonment (SA) type surveys.
response_answersarrayArray containing response_answer objects. See below for the description of the response_answer fields.
response_answerobject{
“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.answersarrayArray containing answer objects. See below for the description of the answer fields.
answerobject{
“answer_text”: string,
“answer_value”: string
}
product_reviewsarrayArray containing product_review objects. See below for the description of the product_review fields.
product_reviewobject{
“star_rating”: string,
“customer_review”: string,
“gtin”: string,
“product_name”: 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 TypesNames
POSPoint of Sale
FFFulfillment
STFFStraight to Fulfillment
BOPISBuy Online Pick Up In Store
SASite Abandonment
CSCustom 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"
}