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

Public API v1.0

Overview

The ForeSee API allows you to export all CX Measure survey response data, as well as CPPs (Customer Passed Parameters) and EPPs (Externally 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 Public 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 for beta testing. Click an endpoint to view details of what data is provided:


Please refer to the Glossary of Terms for definitions of acronyms and unfamiliar terms.

Interactive API Explorer / Swagger link

You can use the API Explorer to test out calls to the API.
You can also look at the Swagger page at this link.

Measures

This endpoint returns information about each measure under contract. Each object within the JSON response contains information for an individual ForeSee measure. For example, if you have both a web measure and a mobile measure your JSON response contains two objects.

Settings:

  • https://api.foresee.com/v1/measures
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/Options: None

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 Measure Key.
  • name - The title of the measure, which is generally used as a label in ForeSee web applications and reports.
  • active - Indicates if the measure is currently available to respondents and collecting data.
  • dateCreated - ForeSee internal measure creation date and time stamp in ISO Date Format: YYYY-MM-DDTHH:mm:SS.SSSZZZZZ.
  • factType - Indicates if the measure supports hierarchy organization structure.
  • channel - The type of survey the measure is developed for, such as Web, Store, or Mobile.
  • modelInstanceID - The Model Instance ID
  • links - Contains the relationship (rel) and hypertext reference (href) to one or more available endpoints related to the ForeSee measure returned in that object. The href is intended for reference only and not a functioning link. However, some applications, such as Postman, may process this data as a hyperlink which may not work properly.

Sample return:

{
  "items": [
    {
      "id": 8840868, 'Measure Key
      "name": "ABC Browse v3",
      "active": true,
      "dateCreated": "2012-03-12",
      "factType": "STANDARD",
      "channel": "WEB",
      "modelInstanceId": "o14A8hoVJd8JhUtdJZtlQw4C",

      "links": [
        {
          "rel": "MEASURE_DEFINITION",
          "href": "/measures/8840868/definition"
        },
        {
          "rel": "MEASURE_DATA",
          "href": "/measures/8840868/data"
        }
      ]
    }
  ]
}

Measure Definition

This endpoint returns the definition or model for a specified measure.

Prerequisites:

  • Measure Key - The id property of Measures.

Settings:

  • https://api.foresee.com/v1/measures/MEASURE_KEY/definition
  • HTTP Method: GET
  • Response Type: JSON
  • Available Parameters/Options:
    • excludeQuestions - Defaults to False. When set to True, no questions are returned and excludeAnswers is automatically set to True with no answer choices being returned as well.
    • excludeAnswers - Defaults to False. When set to True, no answer choices are returned.
      Example: https://api.foresee.com/v1/measures/MEASURE_KEY/definition?excludeAnswers="true"

Properties:

  • links - Contains a list of available endpoints related to the ForeSee measure returned in that object.
  • id - A unique identifier for the question group.
  • name - The name of the group of questions, e.g. "Navigation".
  • type - The type of the group of questions, e.g. "Elements"
  • questions
    • id - A unique identifier for the question.
    • name - The question text as it is presented to the respondent.
    • phrase - A condensed version of the question text intended for reporting. In some cases, the phrase is intentionally the question text verbatim.
    • type - Indicates the type of question, usually "MQ" for Measured Question.
    • label - Indicates the question label.
  • answers
    • id - A unique identifier for the answer choice.
    • text - The answer text as it is presented to the respondent.
    • label - The survey label for the answer choice.
      Example: 1=Poor where "Poor" is the label.
    • value - The numeric value associated with the answer choice.
      Example: 1=Poor where "1" is the value.

Sample return:

{
  "MQ": [
    {
      "id": "M003703L0004",
      "name": "Look and Feel",
      "type": "ELEMENTS",
      "questions": [
        {
          "id": "ENM003703Q00110",
          "name": "Please rate the visual appeal of this site.",
          "phrase": "Please rate the visual appeal of this site.",
          "type": "MQ",
          "label": "Look and Feel - Appeal",
          "answers": [
            {
              "id": "3784547754",
              "text": "1=Poor",
              "label": "1=Poor",
              "value": 1
            }
          ]
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "/measures/8840868/definition"
    }
  ]
}

Measure Data

This endpoint returns information about each measure under contract with the client. Each object within the JSON response contains information for an individual ForeSee measure. For example, if you have both a web measure and a mobile measure your JSON response contains two objects.

Prerequisites:

  • Measure Key - The id property of Measures.

Settings:

  • https://api.foresee.com/v1/measures/MEASURE_KEY/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.
    • to - Required. Set the end dates of responses to limit data to a specific week, month, quarter, etc.
    • excludeLatentScores - Defaults to False. Set to True to omit the latentScores property of the response.
    • excludeMQ - Defaults to False. Set to True to omit measured question responses.
    • excludeCQ - Defaults to False. Set to True to omit custom question responses.
    • excludePassedParams - Defaults to False. Set to True to omit Customer Passed Parameters and External Passed Parameters.
    • 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.
    • limit - This is the number of records per page, with the maximum of 100 records.
    • excludeResponseDetails - Defaults to False. Set to True to omit the responses property.

Properties:

  • hasMore - Indicates the returned data is a segment of, and not all of the available data for this end point.
  • 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.
  • latentScores- A Latent is group of questions which focus on a particular aspect of the subject being measured. For example, the Look and Feel latent score of a web site is derived from responses to questions concerning the visual aspect, or appearance, of the user interface, such as color scheme or font size.
    • id - A unique identifier used by the system to store and retrieve the latent data.
    • name - The latent label used in reports and for display in web applications.
    • type - A categorization of the latent. For example, the latent Product Images pertains to Elements of what is being measured, e.g., store or web page, where as Likelihood to Return pertains to Future Behavior.
    • score - The overall rating from respondents for the latent.
  • responses
    • id - The response identifier.
    • name - The question text as it is presented to the respondent.
    • phrase - A condensed version of the question text intended for reporting. In some cases, the phrase is intentionally the question text verbatim.
    • type - The type of question, such as Custom Question (CQ) or Model Question.
    • answers - How the respondent replied to the question.

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

{
  "hasMore": true,
  "items": [
    {
      "id": "ABC2013234486504",
      "responseTime": "2013-08-01T04:14:00.000Z",
      "latentScores": [
        {
          "id": "M003703L0002",
          "name": "Product Images",
          "type": "ELEMENTS",
          "score": 87.81034581
        }
      ],
      "responses": [
        {
          "id": "ENM003703Q00100",
          "name": "Please rate the number of clicks to get where you want on this site.",
          "phrase": "Please rate the number of clicks to get where you want on this site.",
          "type": "MQ",
          "answers": [
            "9"
          ]
        }
      ]
    }
  ]
}

Sample object using the openEnds endpoint with dateRange and excludeMQ parameters -

Public API v1.0