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