ForeSee Developer Portal

Everything you need to configure and optimize your ForeSee products. Home of developer documentation, implementation guides, and release notes.

Blueprint

CX Measure Import API

Bringing data into CX Suite.

Overview

The CX Measure Import API can be used to bring survey response data into CX Suite. The ForeSee Support Team can create a mirrored survey from another vendor or platform, essentially a ForeSee version of the survey, that allows you to import the existing data using this API. Any survey data can be imported. However, only surveys that match a ForeSee model can produce scores.

Please be aware that this API is currently in pilot testing and only available through the ForeSee Support Team. Anyone interested in the pilot program is encouraged to contact [email protected] for more information.

Example Scenario 1

You have a Net Promoter Score survey that you have been using for some time and would like to import the data collected during the lifespan of the survey. The ForeSee Support Team is able to identify a model, mirror the survey, and provide you with the necessary Question and Answer IDs. When you import data from this survey, you are able to generate scores and display trends in CX Suite.

###Example Scenario 2
You have a survey from another vendor that does not use, or match, a ForeSee model. The ForeSee Support Team is able to mirror the surveys and provide you with the necessary Question and Answer IDs. When you import the data, you can view response counts, answer distributions, open end comments, etc., but no scores are generated.

NOTE: When submitting a survey to the ForeSee Support Team, any historical variations of the survey must be included in order to import the corresponding data, e.g., questions removed or significantly revised.

Prerequisites

The API requires the following:

  1. Questions and Answer IDs for your survey. These are provided by the ForeSee Support Team when the mirrored survey has been created.
  2. An understanding of how REST protocol works. There are several online resources available, including Wikipedia and YouTube.
  3. Understanding of the OAuth 2.0 Protocol, specifically the workings of Client Credentials Grant Flow.
  4. A Consumer Key and Consumer Secret registered for the application consuming the APIs. Note that these credentials are different from those you might have for older APIs. These new credentials give your application full access to only your data.

Survey Ingestion Endpoint

This endpoint accepts a JSON object as a survey response. Each survey response must be a unique JSON object.

Settings:

Properties:
See below for a simple sample payload.
Here are the most common properties:

  • surveyDefinitionId: This is the ID of the survey which is provided by the ForeSee Support Team.
  • responses: This block holds the survey response as an array. The format is "QUESTION_ID":["ANSWER_ID"]. See below for examples.
  • isTest: This parameter is used for testing the API.
{
    "surveyDefinitionId": "I5hUs11dE8pw91J5hcsJFw==",
    "responses":{
        "M001535Q00010":["M001535Q00010A010"],
        "M001535Q00020":["M001535Q00020A010", "M001535Q00020A020"],
        "M001535Q00030":["Great information in the help center"]
    }

    "isTest": false
}

Survey Ingestion Full Payload

Here's a survey example with more details. The extra parameters not included in the earlier example are optional. Some explanation of the parameters are provided inline for non-obvious cases.

{
    "surveyDefinitionId": "I5hUs11dE8pw91J5hcsJFw==",
    "responseId": "bwft32t3whg9g8", // optional identifier
    "url": "https://www.abc.com",  //  URL where survey was presented
    "locale": "en",  // locale of the survey response
    "referrer": "Google",  // the name of a site providing a link the respondent used to access the URL where the survey was presented.
    "referrerUrl": "www.google.com",  // the URL of a site providing a link the respondent used to access the URL where the survey was presented.
    "pageVisits": "10", // the number of pages visited during the respondent's session
    "submissionTimestamp": null, // timestamp when survey was completed ISO 8601 formatted timestamp in UTC. This is generated by the system if not provided.
    "completionTimeInMs": 45353,  // the amount of time to complete the survey in milliseconds 
    "deviceDetails": {   // all of these are optional
        "deviceType":"DESKTOP",
        "deviceName":"Samsung Galaxy S7",
        "deviceVersion":"7.321",
        "brandName":"Samsung",
        "browser": "Chrome 51",
        "browserName":"Chrome",
        "browserVendor":"Microsoft",
        "browserVersion":"51",
        "os":"Android",
        "osName":"Android",
        "osVersion":"6.1",
        "screenWidth":100,
        "screenHeight":90,
        "resolutionWidth":90,
        "resolutionHeight":50,
        "pointingMethod": "touch",
        "isDualOrientation": false,
        "resolution": "1080x1920",
        "screen":"1080x1920"
    },
    "integrations":{ 
        "googleAnalyticsId":"13073028.1426794277",  // pass any partner vendor IDs in this format.
    },
    "responses":{
        "M001535Q00010":["M001535Q00010A010"],
        "M001535Q00020":["M001535Q00020A010", "M001535Q00020A020"],
        "M001535Q00030":["Nice products on your site"],
    "cpps": {    // pass any segmentation variables in this block.
        "properties": {      // 
            "Homepage": ["Y"],    // passes a variable called Homepage with value Y.
            "Categories": ["Home", "Garden"]
        },
       "metrics": {    
              "timeOnSite": 89.322,
              "cartValue": 2501.41
        },                     
        "data": {    // send IDs and other unique values in this section.
              "userID": "1242251",
        }     
    },

    "isTest": false
}

Response Codes

Success

Here's an example of a successful response.

{
  "responseType": "SUCCESS",
  "responseCode": 202,
  "timestamp": "2017-04-17T17:46:48.668Z",
  "responseId": "TuRZT2KobekMQNMOaRFuDxx279EtgiQV"
  }

Validation Error

Here's an example of a response for a validation error.

{
  "responseType": "ERROR",
  "responseCode": 400,
  "message": "One or more required attributes are missing",
  "timestamp": "2017-04-17T18:13:17.819Z",
  "errorCode": "API_MISSING_REQUIRED_ATTRIBUTES",
  "detailedErrors": [
    "MID is required"
  ]
}

Updated about a year ago

CX Measure Import API


Bringing data into CX Suite.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.