Retrieving Survey Response Data

8 min read

Updated 22 Jul 2026

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 *******************************************="

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 }
`product_reviews`	array	Array containing `product_review` objects. See below for the description of the `product_review` fields.
`product_review`	object	{ "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 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 *******************************************="

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"
}

{
  "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"
}