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

Client Credentials Grant

 

This is the API endpoint for obtaining an access token to the ForeSee API.

Read an overview of the API at this link.

Token Endpoint

 
posthttps://api.foresee.com/v1/token
curl --request POST \
  --url 'https://api.foresee.com/v1/token?scope=r_cx_basic&grant_type=client_credentials' \
  --header 'authorization: Basic akhGY0VGN3h4UzRnU1pTNjZ0aldCcTFzblh6UzA4dDg6aGsyQmF2YmJZQ0xpMTNscE5hUXk=' \
  --header 'content-type: application/json'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.foresee.com/v1/token',
  qs: 
   { scope: 'r_cx_basic',
     grant_type: 'client_credentials' },
  headers: 
   { authorization: 'Basic akhGY0VGN3h4UzRnU1pTNjZ0aldCcTFzblh6UzA4dDg6aGsyQmF2YmJZQ0xpMTNscE5hUXk=',
     'content-type': 'application/json' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.foresee.com/v1/token?scope=r_cx_basic&grant_type=client_credentials")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["authorization"] = 'Basic akhGY0VGN3h4UzRnU1pTNjZ0aldCcTFzblh6UzA4dDg6aGsyQmF2YmJZQ0xpMTNscE5hUXk='

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.foresee.com/v1/token?scope=r_cx_basic&grant_type=client_credentials");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Basic akhGY0VGN3h4UzRnU1pTNjZ0aldCcTFzblh6UzA4dDg6aGsyQmF2YmJZQ0xpMTNscE5hUXk=");

xhr.send(data);
import requests

url = "https://api.foresee.com/v1/token"

querystring = {"scope":"r_cx_basic","grant_type":"client_credentials"}

headers = {
    'content-type': "application/json",
    'authorization': "Basic akhGY0VGN3h4UzRnU1pTNjZ0aldCcTFzblh6UzA4dDg6aGsyQmF2YmJZQ0xpMTNscE5hUXk="
    }

response = requests.request("POST", url, headers=headers, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

scope
string
required

The scope for authorization request

grant_type
string
required

The grant type of authorization request

Headers

Content-Type
string
required

The media type of the body of the request

Authorization
string
required

HTTP basic authentication credentials

Response

Successful response

access_tokenstring

The access token is used by the client to make authenticated requests.

token_typestring

Representation of how the access token will be generated and presented for resource access calls.

expires_instring

The number of seconds left in the life time of the access token.

scopestring

Limitation of the authorization granted.

Bad request - one or more request parameters or payload attributes is not valid

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

There is either not an encoded client credentials provided or it is provided incorrectly or what is provided is invalid or expired. Examine the details for more information

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

Caller does not have access to the requested API resource either by way of scopes or more fine grained access control violations. Examine the details for more information

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

The content type supplied in Accepts is not an acceptable content type

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

Caller exceeded the throttling limits set for the API and / or the account

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

An unexpected error occured on the server. Caller is requested to retry

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

The service is unavailable. Caller is requested to refer to maintenance notifications or contact support

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

An unexpected error occured downstream. Caller is requested to retry

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

Consumption

 

Here are the data consumption APIs

Measure Definition

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.foresee.com/v1/measures/measurementKey/definition
curl --request GET \
  --url https://api.foresee.com/v1/measures/measurementKey/definition \
  --header 'accept: application/json'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.foresee.com/v1/measures/measurementKey/definition',
  headers: { accept: 'application/json' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.foresee.com/v1/measures/measurementKey/definition")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.foresee.com/v1/measures/measurementKey/definition");
xhr.setRequestHeader("accept", "application/json");

xhr.send(data);
import requests

url = "https://api.foresee.com/v1/measures/measurementKey/definition"

headers = {'accept': 'application/json'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

Try the API to see results

Path Params

measurementKey
int32
required

The measurement key for the measure

Query Params

excludeQuestions
boolean

Allows excluding questions

excludeAnswers
boolean

Allows excluding answers

Headers

Accept
string
required

Content-Types that are acceptable for the response

Response

Successful response

linksarray
CQarray
CPParray
EPParray
MQobject

List of measured questions

MQ.latentsarray

Bad request - one or more request parameters or payload attributes is not valid

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

There is either not an Oauth2 token provided or it is provided incorrectly or what is provided is invalid or expired. Examine the details for more information

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

Caller does not have access to the requested API resource either by way of scopes or more fine grained access control violations. Examine the details for more information

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

There was no resource found for the specified identifier

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

The content type supplied in Accepts is not an acceptable content type

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

Caller exceeded the throttling limits set for the API and / or the account

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

An unexpected error occured on the server. Caller is requested to retry

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

The service is unavailable. Caller is requested to refer to maintenance notifications or contact support

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

An unexpected error occured downstream. Caller is requested to retry

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

Measure Data

 

OAuth2 Auth

Bearer
 Authentication is required for this endpoint.
gethttps://api.foresee.com/v1/measures/measurementKey/data
curl --request GET \
  --url 'https://api.foresee.com/v1/measures/measurementKey/data?from=from&to=to' \
  --header 'accept: application/json'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.foresee.com/v1/measures/measurementKey/data',
  qs: 
   { from: 'from',
     to: 'to' },
  headers: { accept: 'application/json' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.foresee.com/v1/measures/measurementKey/data?from=from&to=to")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.foresee.com/v1/measures/measurementKey/data?from=from&to=to");
xhr.setRequestHeader("accept", "application/json");

xhr.send(data);
import requests

url = "https://api.foresee.com/v1/measures/measurementKey/data"

querystring = {"from":"from","to":"to"}

headers = {'accept': 'application/json'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

Try the API to see results

Path Params

measurementKey
int32
required

The measurement key for the measure

Query Params

from
date
required

The start date for the query. Should be in YYYY-MM-DD format

to
date
required

The end date for the query. Should be in YYYY-MM-DD format

excludeResponseDetails
boolean

Allows excluding details of questions and answers for every respondent

excludeMQ
boolean

Allows excluding measured questions

excludeCQ
boolean

Allows excluding custom questions

excludePassedParams
boolean

Allows excluding CPPs and EPPs

excludeLatentScores
boolean

Allows excluding latent scores from respondent detail as well as from the summary

offset
integer

0 based integer that indicates the page number

limit
integer

1 based integer that indicates the page size. Max allowed is 100

Headers

Accept
string
required

Content-Types that are acceptable for the response

Response

Successful response

hasMoreboolean

Indicates if there are additional respondents to be queried for. Applicable during paging

itemsarray

Bad request - one or more request parameters or payload attributes is not valid

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

There is either not an Oauth2 token provided or it is provided incorrectly or what is provided is invalid or expired. Examine the details for more information

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

Caller does not have access to the requested API resource either by way of scopes or more fine grained access control violations. Examine the details for more information

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

There was no resource found for the specified identifier

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

The content type supplied in Accepts is not an acceptable content type

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

Caller exceeded the throttling limits set for the API and / or the account

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

An unexpected error occured on the server. Caller is requested to retry

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

The service is unavailable. Caller is requested to refer to maintenance notifications or contact support

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors

An unexpected error occured downstream. Caller is requested to retry

timestampstring

The timestamp of the error

statusnumber

This will be an HTTP Status Code will correspond to the HTTP status code in response header

messagestring

The exact error message shown

errorCodestring

This could be an error code that can help uniquely identify the issue

detailedErrorsarray

An array of additional messages that describe the error. Will be only populated when there is a need E.g. for bad data errors