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). We also offer endpoints to export Text Analytics data.

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. Click an endpoint to view details of what data is provided:

CX Measurement Endpoints

Text Analytics Endpoints

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.
{
  "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.
    • responseType - Indicates the type of response, e.g., 'TEXT_AREA', 'CHECKBOX', etc.
  • 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.
{
  "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",
          "responseType": "MEASURED_QUESTION"
          "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.
  • 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.
  • 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,
  "total": 5227,
  "items": [
    {
      "id": "ABC2013234486504",
      "responseTime": "2013-08-01T04:14:00.000Z",
      "latentScores": [
        {
          "id": "M003703L0002",
          "name": "Product Images",
          "type": "ELEMENTS",
          "score": 87.81034
        }
      ],
      "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 -

Text Analytics Export ID

This endpoint generate an export ID for the requested TA data

Prerequisites:

  • Customer ID

Settings:

Body:

  • Available Parameters/Criteria:
    • a: as of
    • f: first date
    • l: last date
  • Project Parameters
    • projectType: CUSTOM_FEED, CX_MEASURE (Not supported currently) and FEEDBACK (Not supported currently)

Example Request:

{"criteria":{"dateRange":{"c":"G","r":"C","p":"D","n":"0","k":"418144","v":"","a":"2018-06-30","f":"2018-06-24","l":"2018-06-30","t":"DATE_ONLY","timezone":"America/Detroit"},"projectParameters": [
  
  {"projectType":"CUSTOM_FEED", "parameters":{"customerId":[418144]}}
  
  ]}}

Response

  • exportId: ID of export file, required for next steps to fetch data
{
    "exportId": "7615ac8a-f4b7-4bf2-87a8-56f3e36c6178",
    "completed": false,
    "failed": false
}

Text Analytics Processing Request

Use the export ID from Step 1 output to from the Text Analytics Export ID endpoint to request processing of the comments.

Settings:

Response

{
    "exportId": "7615ac8a-f4b7-4bf2-87a8-56f3e36c6178",
    "completed": true,
    "failed": false
}

Text Analytics Export Comments

Export the comments with export ID created from the Text Analytics Export ID endpoint

Settings:

Response

  • MEASURE_NAME: Name of the CX, Feedback or Custom Feed Measure
  • DATE_OF_SUBMISSION: Date of submission of the comment
  • SCORE: Depending on projectType:
  • CSAT (0-100) for CX_MEASURE
  • Rating (0-5) for FEEDBACK
  • Numeric Score for CUSTOM_FEED
  • SENTIMENT_SCORE: Probability of sentiment type
  • SENTIMENT_TYPE: positive, neutral, negative
  • KEYWORDS: Important Keywords identified in the comment. Examples: purchase, items, service etc.
  • TOPIC: Topic that the comment was categorized into based on the taxonomy. Please refer to the taxonomy configured for your account.
  • MID_LEVEL_THEME: Mid-Level Theme the comment was categorized into based on the taxonomy. Please refer to the taxonomy configured for your account.
  • HIGH_LEVEL_THEME: High-Level Theme the comment was categorized into based on the taxonomy. Please refer to the taxonomy configured for your account.
  • SURVEY_QUESTION: Question Text
  • COMMENT: Open end response
  • CUSTOM_FEED_DATA: Other fields passed in for custom feeds (For future use)
MEASURE_NAME,DATE_OF_SUBMISSION,SCORE,SENTIMENT_SCORE,SENTIMENT_TYPE,KEYWORDS,TOPIC,MID_LEVEL_THEME,HIGH_LEVEL_THEME,SURVEY_QUESTION,COMMENT,CUSTOM_FEED_DATA
,,,"0.0","neutral","fields",,,,,"This one has all of the fields that pass",
,,,"0.718752","positive","service","Responsiveness","Customer Service","Customer Service",,"I was happy with the service",
,,,"0.870888","positive","purchase,items","Intended Product Purchase","Purchasing","Purchasing",,"Very happy with my purchase. Both items fit, and are cute on.",
,,,"-0.78072","negative","agent id",,,,,"This one doesn't have an Agent ID",
,,,"0.837749","positive","perfect condition,time",,,,,"everything arrived on time and in perfect condition!",
,,,"0.0","neutral","email notification,package","Delivery services","Shipping","Services",,"It has been several days since your email notification of the delivered package. However, I have yet to receive anything. ",
,,,"-0.433057","negative","justfab",,,,,"I don't retreat shopping with JustFab tumps up",
,,,"-0.476853","negative","pair,shoes","Placing orders","UI/UX","Website",,"I had ordered a pair of shoes and they are taking forever to get here.",
,,,"0.872604","positive","fab experience",,,,,"Never disappointed with my just fab experience",
,,,"0.799825","positive","shoes,price","Product Pricing","Pricing and other charges","Pricing and other charges",,"Shoes came quickly and price was great!",
,,,"-0.439373","negative","bomb shoes,omg,bit,girl","Product packing","Add ons","Product",,"Bomb shoes although they were a bit hard to break in once I did omg, girl",
,,,"-0.700332","negative","jump suit,totally different item,chat agent erica/marie,smaller size,shen,gab,bag,time","Live chat experience","Customer Service","Customer Service",,"I ordered a jump suit. It was too big. Sent it back ordered a smaller size and was sent a totally different item wrapped in a bag labeled cross over jump suit. The Shen who helped me the second time tried to reorder and low and behold it's sold out! Beyond frustrating. Not to mention the first chat agent Erica/Marie whoever they really are are of no assistance at all! I've never been unhappy with just gab but I am now and am seriously considering canceling my membership. ",
,,,"-0.344777","negative","absurd cancellation process,shoes,nni,pairs,traction,rep,quality,items","Product quality","Quality","Product",,"I was overall not all all happy with the quality of the items I ordered. I ordered 3 pairs total with credits. No traction at all on ANY of the shoes. The shoes are ill fitting and uncomfortable. nnI also was very annoyed with the absurd cancellation process. I should not have to spend 10 minutes on the phone wasting my time telling a rep OVER AND OVER that I do not like the products and to please cancel the service. ",
,,,"-0.667616","negative","tops,thanks,reviews,size","Product ratings/reviews","Suggestions","Product",,"Got two tops and they got here earlier than it said it would be. Thanks to reviews, I ordered a size down and it fits pretty good so I didn't have to return it even though returning isn't that bad. Just takes longer to wear the top. ",
,,,"0.744797","positive","shopping,justfab",,,,,"shopping at justfab?_?so far so good",
,,,"0.846409","positive",,,,,," Wonderful all around!!!!!!!!",
,,,"-0.720201","negative","sleeve,quality,justfab","Product quality","Quality","Product",,"I had to resow a part of the sleeve. I know the quality is always cheaper with justfab, but it was annoying I had to resow it.",
,,,"0.777716","positive","live chat team,customer service,professionalism,issue,justfab,business","Live chat experience","Customer Service","Customer Service",,"I had an issue, and the Live Chat team resolved efficiently and with much professionalism. I value customer service over anything, and JustFab is obviously working very hard to execute this important part of business.",
,,,"0.958346","positive","wonderful shoes",,,,,"wonderful shoes! i love it",
,,,"0.913278","positive","pair,size,color,picture","Image/video quality","UI/UX","Website",,"Everything about my pair is perfect and true to size and color in the picture",

Public API v1.0