Using the REST Reporting API
Please note: this is a developer topic.
Our Enterprise plan allows for using the REST Reporting API to retrieve responses data from the Informizely server using HTTP requests.
In order to use the REST Reporting API, you need an API Key and an API Secret.
These can be found on the "
My Account" page
in your dashboard, if your subscription plan allows usage of the REST Reporting API.
If no API Secret has been set, you can click the "Generate" link to create one.
Authentication
The REST Reporting API uses HTTP Basic Authentication. This means that the API Key and Secret are sent in the HTTP header in Base64-encoded
form:
"[api-key]:[api-secret]". You can encode them yourself or use the "API Credentials" that are shown on the "My Account" page, which are
just the Base64-encoded string "[api-key]:[api-secret]".
All communication requires HTTPS, so all data is sent to the Informizely server in encrypted form.
API URL
The base URL for the REST Reporting API is
https://api.informizely.com/api/v1
.
Data can be requested in either JSON or XML format.
The generic form of a request URL is:
https://api.informizely.com/api/v1/[request]?[parameters]
.
Multiple parameters must be separated by '&'. Optionally, an 'id' parameter can also be specified unnamed after a '/':
https://api.informizely.com/api/v1/[request]/[id]?[other-parameters]
.
Example:
https://api.informizely.com/api/v1/responses/luodyjklq?fromDate=2017-08-01T00:00:00Z&excludeQuestions=true
.
Types
Date types should be specified in UTC, in
ISO 8601 format:
yyyy-MM-ddTHH:mm:ssZ
(the "Z" makes it UTC).
Boolean types should be specified as either
true
or
false
.
API Requests
https://api.informizely.com/api/v1/responses
Purpose: returns the responses for a survey.
Returns: an object of type Responses (see below).
Parameter |
Type |
Required |
Description |
Default |
id |
String |
Yes |
The ID of the survey for which to retrieve data. |
|
fromDate |
Date |
No |
The earliest date and time for which to retrieve responses. |
|
toDate |
Date |
No |
The latest date and time for which to retrieve responses. |
|
fromIndex |
Integer |
No |
The 0-based start index of the reponse to return, after applying a possible date range. |
|
toIndex |
Integer |
No |
The 0-based end index of the reponse to return, after applying a possible date range. |
|
includeRemoved |
Boolean |
No |
false if data for removed questions should be excluded. |
true |
includeEmpty |
Boolean |
No |
false if data for empty answers should be excluded. |
true |
excludeQuestions |
Boolean |
No |
true if question-info data should be excluded. |
false |
https://api.informizely.com/api/v1/questions
Purpose: returns the question data for a survey.
Returns: an array of objects of type Question (see below).
Parameter |
Type |
Required |
Description |
Default |
id |
String |
Yes |
The ID of the survey for which to retrieve data. |
|
https://api.informizely.com/api/v1/count
Purpose: returns the number of responses for a survey.
Returns: an integer that denotes the number of responses that would be returned by a call to responses when passed the same data.
Parameter |
Type |
Required |
Description |
Default |
id |
String |
Yes |
The ID of the survey for which to retrieve data. |
|
fromDate |
Date |
No |
The earliest date and time for which to retrieve responses. |
|
toDate |
Date |
No |
The latest date and time for which to retrieve responses. |
|
fromIndex |
Integer |
No |
The 0-based start index of the reponse to return, after applying a possible date range. |
|
toIndex |
Integer |
No |
The 0-based end index of the reponse to return, after applying a possible date range. |
|
includeRemoved |
Boolean |
No |
false if data for removed questions should be excluded. |
true |
includeEmpty |
Boolean |
No |
false if data for empty answers should be excluded. |
true |
https://api.informizely.com/api/v1/stats
Purpose: returns statistics for a survey.
Returns: an object of type SurveyStats (see below).
Parameter |
Type |
Required |
Description |
Default |
id |
String |
Yes |
The ID of the survey for which to retrieve data. |
|
https://api.informizely.com/api/v1/all
Purpose: returns all data for a survey.
Returns: an object of type AllSurveyData (see below).
Parameter |
Type |
Required |
Description |
Default |
id |
String |
Yes |
The ID of the survey for which to retrieve data. |
|
includeRemoved |
Boolean |
No |
false if data for removed questions should be excluded. |
true |
includeEmpty |
Boolean |
No |
false if data for empty answers should be excluded. |
true |
excludeQuestions |
Boolean |
No |
true if question-info data should be excluded. |
false |
https://api.informizely.com/api/v1/surveys
Purpose: returns meta data for all surveys of a site.
Returns: an array of objects of type SurveyMetaData (see below).
Parameter |
Type |
Required |
Description |
Default |
id |
String |
Yes |
The ID of the site for which to retrieve survey meta data. |
|
https://api.informizely.com/api/v1/sites
Purpose: returns meta data for all sites of the current account.
Returns: an array of objects of type SiteMetaData (see below).
Parameter |
Type |
Required |
Description |
Default |
includeSurveyData |
Boolean |
No |
false if meta data for the site's surveys should be excluded. |
true |
Returned objects
For ease of definition we specify the returned objects as C# classes, which will be serialized to either JSON or XML in the result
returned by the server.
class Responses // Result data for a responses HTTP request.
{
Question[] Questions; // List of 'Question' objects.
ResponseTag[] ResponseTags; // List of 'ResponseTag' objects that are assigned to at least one response.
Response[] Responses; // List of 'Response' objects.
}
class Response // Contains all data for one visitor response.
{
string Id; // Response ID.
string VisitorId; // Unique visitor ID.
DateTime TimeStamp; // Timestamp of this response.
int ShowCount; // The number of times the survey was shown to this visitor.
bool Completed; // True if the visitor answered all questions.
string OpenAction; // Why the survey was shown.
string CloseAction; // Why the survey was closed.
string Url; // The URL where the survey was shown.
string Device; // The type of device on which the survey was shown.
string OS; // The operating system of the visitor.
string Browser; // The browser used by the visitor.
int NrSiteVisits; // The number of times the visitor visited the site.
int NrPageVisits; // The number of pages visited in the survey's browser session.
string ReferrerUrl; // The URL of the page that referred to survey's URL.
string UserIdentity; // The User ID, if set by the JavaScript API.
string CallToActionIds;// Comma-separated list of page item IDs of activated call-to-action items.
string IpAddress; // The IP address of the visitor.
string UserAgent; // The user agent of the visitor's browser.
string[] TagIds; // List of IDs of 'ResponseTag' objects that are assigned to this response.
NameValue[] CustomDatas; // List of custom variables, as set by the JavaScript API.
NameValue[] Cookies; // List of targeting cookies.
Answer[] Answers; // List of answers to survey questions.
}
class ResponseTag // Contains data for the definition of a response tag.
{
string Id; // Tag ID.
string Name; // The name of the tag.
}
class Question // Contains data for the definition of a survey question.
{
string Id; // Question ID. Locally unique to a survey.
string Type; // The type of question.
string Text; // The question's text.
Choice[] Choices; // Choice data if 'Type' is "Choice" or "MultiChoice".
bool Removed; // True if the question was removed from the current survey.
}
class Choice // Contains data for the definition of a choice question.
{
string Id; // Choice ID. Locally unique to a choice question.
string Text; // The choice's text.
bool Removed; // True if the choice was removed from the current survey.
}
class Answer // Contains the data for an answer to a survey question.
{
string QuestionId; // Question ID. Identifies an entry in Responses.Questions.
string Text; // Text that the visitor entered for this answer.
string Value; // For single and multi choice questions: the choice ID.
// For rank questions: comma-separated list of ordered choice IDs.
// For matrix questions: comma-separated list of colon-separated choice IDs.
// For date questions: yyyy-MM-dd.
}
class NameValue // Contains the data for a name-value pair.
{
string Name; // Name-part of a name-value pair.
string Value; // Value-part of a name-value pair.
}
class SurveyStats // Contains data for survey totals.
{
DateTime FirstEventTime; // Timestamp of the first recorded event.
DateTime LastEventTime; // Timestamp of the last recorded event.
int NrOpened; // Nr times the survey was displayed.
int NrEmptyCompleted; // Nr times the survey was completed without answers or call-to-actions.
int NrEmptyClosedExplicit; // Nr times the survey was explicitly closed without answers by a user.
int NrEmptyClosedImplicit; // Nr times the survey was implicitly closed without answers for some reason.
int NrResponses; // Total nr of not-empty responses. Includes deleted responses.
int NrCompleted; // Nr completed not-empty responses. Includes deleted responses.
int NrDeleted; // Number of deleted responses.
}
class AllSurveyData
{
Question[] Questions; // List of 'Question' objects.
ResponseTag[] ResponseTags; // List of 'ResponseTag' objects that are assigned to at least one response.
Response[] Responses; // List of 'Response' objects.
SurveyStats Stats; // Statistics for this survey.
}
class SurveyMetaData // Contains meta data for a survey.
{
string Id; // Survey ID.
string Name; // Survey name.
}
class SiteMetaData // Contains meta data for a site and its surveys.
{
string Id; // Site ID.
string Domain; // Site domain.
SurveyMetaData[] Surveys; // List of 'SurveyMetaData' objects.
}
How to find your survey's ID
A survey's ID is shown on the survey's "Settings" page, as the first property of the survey.
The survey ID is also the part after the last '/' in the browser's page URL.
You can also use the
sites request to retrieve a list of all of your account's site IDs and survey IDs.
How to test the REST Reporting API
If you want to, you can test the REST Reporting API without writing integration code first.
To test in curl:
curl -u [api-key]:[api-secret] -X GET https://api.informizely.com/api/v1/[request]?[parameters]
For example, to show all responses for the survey with ID
luodyjklq, the URL would look something like:
curl -u IuZjFvXj:JkuLerv2 -X GET https://api.informizely.com/api/v1/responses?id=luodyjklq
To test in
Fiddler, you add the API URL in the composer:
https://api.informizely.com/api/v1/[request]?[parameters]
,
and add the following as header data:
Accept: text/json
Authorization: Basic [api-credentials]
[api-credentials] is simply the Base64-encoded string "[api-key]:[api-secret]",
which you can retrieve from the "My Account" page, or encode yourself using Fiddler's TextWizard.
If you want to retrieve XML, you can use
Accept: text/xml
.
We conclude with an example of how to retrieve response data using jQuery:
$.ajax({
type: "GET",
url: 'https://api.informizely.com/api/v1/responses',
parameters: { id: 'luodyjklq', fromDate: '2017-08-01T00:00:00Z', excludeQuestions: true },
dataType: "json", // or "xml"
beforeSend: function(xhr) {
xhr.setRequestHeader("Authorization", "Basic [api-credentials]"));
},
success: function(result) {
// Process the returned data.
}
});
See also:
Webhooks Integration