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:
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 |