ForeSee Developer Portal

Everything you need to set up and optimize your ForeSee product. Home of developer documentation, implementation guides, and question/answer forums.

Blueprint

Feedback Export API

Overview

The Feedback Export API allows you to export all Feedback survey response data, as well as CPPs (Customer Passed Parameters).

Uses of the API

There are many potential uses of the API.

Some common applications are:

  • Exporting ForeSee data into Business Intelligence or other internal data/reporting tools
  • Exporting ForeSee data for ad-hoc analysis

Prerequisites

The API requires the following:

  1. An understanding of how REST protocol works. There are several online resources available, including Wikipedia and YouTube.
  2. Understanding of the OAuth 2.0 Protocol, specifically the workings of Client Credentials Grant Flow.
  3. A Consumer Key and Consumer Secret registered for the application consuming the APIs. Note that these credentials are different from those you might have had for older APIs. These new credentials give your application full access to only your data.

If you do not have a Consumer Key and/or Consumer Secret, contact Foresee Support.

Endpoints

The following list consists of endpoints which are currently available. Click an endpoint to view details of what data is provided:

Projects

This endpoint returns a list of the Feedback Projects (surveys)under contract. Each object within the JSON response contains information for an individual Feedback survey.

Settings:

Properties:

  • hasMore - Indicates the returned data is a segment of, and not all of the available data for this end point.
  • id - A unique identifier for the survey which is used in the URL of calls to other various endpoints. The id property is often referred to as the Project_ID.
  • name - The title of the Feedback project
  • createdDateTime - Survey creation date and time stamp in ISO Date Format: YYYY-MM-DDTHH:mm:SS.SSSZZZZZ.
  • modelInstanceId - Indicates if the Model Instance ID associated with the survey
  • Sitekey - Indicates if the Site Key the survey is associated with
  • Status - Indicates if the survey is currently available to respondents and collecting data.
{
    "items": [
    	{
        "id": 7521,
        "name": "Search Survey",
        "createdDateTime": "2018-08-17T20:24:35Z",
        "modelInstanceId": "KsxH7VYZUQTXTgKAnV8e5qeU8NKwwmE6",
        "siteKey": "America Site",
        "status": "ACTIVE"
        "links": [
                {
                    "rel": "FEEDBACK_DATA",
                    "href": "/projects/7521/data"
                },
                {
                    "rel": "FEEDBACK_DEFINITION",
                    "href": "/projects/7521/definition"
                }
  	  },
   	 {
        "id": 7522,
        "name": "Contact Us Survey",
        "createdDateTime": "2018-08-17T20:30:08Z",
        "modelInstanceId": "HMQI1qyvZjwDhEwwGS00xGuqr6XULfL8",
        "siteKey": "Canada Site",
        "status": "NEW"
      	"links": [
                {
                    "rel": "FEEDBACK_DATA",
                    "href": "/projects/7522/data"
                },
                {
                    "rel": "FEEDBACK_DEFINITION",
                    "href": "/projects/7522/definition"
                }
    	}
	]
    "links": [
        {
            "rel": "self",
            "href": "/projects"
        }
    ]
}

Project Definition

This endpoint returns the definition for a specified survey.

Prerequisites:

  • Project ID - The id property of Projects.

Settings:

Properties:

  • id - A unique identifier for the measure which is used in the URL of calls to other various endpoints. The id property is often referred to as the Project ID.
  • name - The title of the Feedback survey
  • description - Description of the survey
  • createdDateTime - Survey creation date and time stamp in ISO Date Format: YYYY-MM-DDTHH:mm:SS.SSSZZZZZ.
  • modelInstanceId - Indicates if the Model Instance ID associated with the survey
  • Sitekey - Indicates if the Site Key the survey is associated with
  • Status - Indicates if the survey is currently available to respondents and collecting data.
  • CQ (Custom Questions)
    • id - A unique identifier for the question.
    • type - The type of the question. Options are: RATING, TOPIC, SCALED, DROP_DOWN, RADIO_BUTTON, CHECKBOX, TEXT_AREA, TEXT_FIELD
    • text - Wording of the question
    • required- Indicates if question is required
    • answers- Indicates the answer choices. Not applicable to rating, scaled, text_area and text_field types. For rating and scaled choices are always 1-5.
      • label - The text of the answer choice (not applicable to rating, scaled and text_area, and text_field types)
{
    "id": 8311,
    "name": "Product Images Survey",
    "description": "Survey of the product images on the detail pages",
    "createdDateTime": "2018-10-09T19:31:56Z",
    "modelInstanceId": "7SRyjK0l80FtSJXVdUaYKfI0AsmfSZGZ",
    "siteKey": "demo_test",
    "status": "ACTIVE",
    "CQ": [
        {
            "id": "XIA0046271",
            "type": "RATING",
            "text": "How was your experience?",
            "required": false,
        },
        {
            "id": "XIA0046272",
            "type": "TOPIC",
            "text": "<p>Topic Description</p>",
            "required": true,
            "answers": [
             	"Topic One",
              "Topic Two"
            ]
        },
        {
            "id": "XIA0046273",
            "type": "SCALED",
            "text": "<p>One Rating</p>",
            "required": false,
        },
        {
            "id": "XIA0046274",
            "type": "DROP_DOWN",
            "text": "<p>One dropdown</p>",
            "required": false,
            "answers": [
             	"Choice One",
              "Choice Two"
            ]
        }
              {
            "id": "XIA0046277",
            "type": "TEXT_AREA",
            "text": "<p>One Comment</p>",
            "required": false
        }
     "links": [
        {
            "rel": "FEEDBACK_DATA",
            "href": "/projects/8311/data"
        }
}     

Project Data

This endpoint returns the responses to each survey. Each object within the JSON response contains information for an individual response.

Prerequisites:

  • Project ID - The id property of Projects.

Settings:

  • *https://https://api.foresee.com/v1/projects/PROJECT_ID/data
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/Options:
    • from - Required. Set the start date of responses to limit data to a specific week, month, quarter, etc. Note that this is applies to the survey submission date.
    • to - Required. Set the end dates of responses to limit data to a specific week, month, quarter, etc. Note that this is applies to the survey submission date.
    • offset - This refers to a specific page of the paginated data, starting with zero. For example, page 1 is offset 0, page 2 is offset 1, etc. Use offset to request a specific page of data. Paging is a process where data set is broken up into subsets to improve response time since the user is only viewing a portion of the data, i.e., one page of data. Each page has the number of records specified in the limit parameter below.
    • limit - This is the number of records per page, with the maximum of 100 records. If nothing is specified, the default is 25 records.
      Properties:
  • hasMore - Indicates the returned data is a segment of, and not all of the available data for this end point.
  • total - Indicates the number of respondents within the date range.
  • id - The Respondent Identifier assigned to each submitted survey.
  • responseTime - Date and time stamp of when the survey was submitted in ISO Date Format: YYYY-MM-DDTHH:mm:SS.SSSZZZZZ.
  • rating - The score provided for the main rating question
  • topic - The response provided to the topic question
  • url - The URL the survey was completed on
  • response - Other questions the user responded to
    • id - Question ID
    • type - Type of the question, either CQ (Custom Question) or CPP (Customer Passed Parameter)
    • answers - The answer provided to the question

Sample return using the dateRange parameter (required) - https://api-dev.foresee.com/v1/projects/8311/data?from=2013-08-01&to=2013-08-07:

{
    "hasMore": false,
    "total": 6,
    "items": [
        {
            "id": "0Nolkwodoghkp5BtF948kA4C",
            "responseTime": "2018-10-09T19:42:29Z",
            "rating": 2,
            "topic": "Topic One",
            "url": "https://survey-dev.foresee.com/f/yFeS5ZdxAL",
            "response": [
                {
                    "id": "XIA0046271",
                    "type": "CQ",
                    "answers": [
                        "2"
                    ]
                },
                {
                    "id": "XIA0046272",
                    "type": "CQ",
                    "answers": [
                        "Site is too slow"
                    ]
                },
                {
                    "id": "device_version",
                    "type": "CPP",
                    "answers": [
                        "Chrome"
                    ]
                },
                {
                    "id": "os",
                    "type": "CPP",
                    "answers": [
                        "Windows 10"
                    ]
                }
         }
 }