NAV
Node.js Python Go PHP

Introduction

Welcome to the Usabilla API documentation. Here you will find a detailed guide on how to access the data related to your customers' feedback.

You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right. On top of this, we've also included our client repositories we have on GitHub.

Usabilla maintains the following client libraries:

Client libraries maintained by third parties:

If you wrote a public client library that would be beneficial to fellow coders, we would love to hear about it and include it in our documentation, please send us a link to your project repository.

If you prefer to use a language we do not provide a client library for you can continue to the next section to see how our authentication method works. Please contact support if you need help calling our API.

Authentication

The authentication code for each language can be found under the respective GitHub pages:

The credentials consist in an access key and a secret key used for authentication purposes. You can acquire the credentials by logging into your Usabilla account and access the following link or navigating to the settings menu under the tab Usabilla API. If you're new to the Usabilla API then we recommend you to read through our support article on Getting Started with the Usabilla Public API. Our API authentication system is inspired by the signed AWS API requests.

  1. Create a Canonical Request
  2. Create a String to Sign
  3. Calculate the Signature
  4. Sign the Request

1. Create a Canonical Request

To begin the signing process, you create a string that includes information from your request in a standardized (canonical) format. This step will allow you to create a canonical request string which will be used by our servers to verify the signed request.

Follow the steps here to create a canonical version of the request. Otherwise, your version and the version calculated by our servers won't match, and the request will be denied.

The following example shows the pseudocode to create a canonical request:

CanonicalRequest =
HTTPRequestMethod + '\n' +
CanonicalURI + '\n' +
CanonicalQueryString + '\n' +
CanonicalHeaders + '\n' +
SignedHeaders + '\n' +
HexEncode(Hash(RequestPayload))

Example request

To show you how to construct the canonical form of an HTTP request, we'll use the following example request. The original request might look like this as it is sent from the client to our servers, except that this example does not include the signing information yet.

GET https://data.usabilla.com/ HTTP/1.1
Host: data.usabilla.com
Date: 20150830T123600Z

To create a canonical request, concatenate the following components from each step into a single string:

  1. Start with the GET, HTTP request method written in upper case, followed by a newline character. Example request method:

    GET

  2. Add the canonical URI parameter, followed by a newline character.

If the absolute path is empty, use a forward slash (/). In the example request, nothing follows the host in the URI, so the absolute path is empty.

Example canonical URI:

/button

  1. Add the canonical query string, followed by a newline character.

If the request does not include a query string, use an empty string (essentially, a blank line). The example request does not contain a query string:

Example canonical query string:

?limit=1&since=123456789

To construct the canonical query string, complete the following steps:

a. URI-encode each parameter name and value according to the following rules: do not URL-encode any of the unreserved characters that RFC 3986 defines: A-Z, a-z, 0-9, hyphen (-), underscore (_), period (.), and tilde (~); and percent-encode all other characters with %XY, where X and Y are hexadecimal characters (0-9 and uppercase A-F).

b. Sort the encoded parameter names by character code.

c. Build the canonical query string by starting with the first parameter name in the sorted list.

d. For each parameter, append the URI-encoded parameter name, followed by the character = (ASCII code 61), followed by the URI-encoded parameter value. Use an empty string for parameters that have no value.

e. Append the character & (ASCII code 38) after each parameter value except for the last value in the list.

Example authentication parameters in a query string:

The following example shows a query string that includes authentication information.

Algorithm=USBL1-HMAC-SHA256&
Version=2010-05-08&
Credential=AKIAIOSFODNN7EXAMPLE%2F20150112%2Fusbl1_request&
Date=20150112T135139Z&
SignedHeaders=date%3Bhost

  1. Add the canonical headers, followed by a newline character. The canonical headers consist of a list of all the HTTP headers. The required headers are host and date.

Example canonical headers:

host:data.usabilla.com\n
date:20150111T003735Z\n

To create the canonical headers list, convert all header names to lowercase and trim excess white space characters out of the header values. When you trim, remove leading spaces and trailing spaces, and convert sequential spaces in the value to a single space. However, do not remove extra spaces from any values that are inside quotation marks.

The following pseudocode describes how to construct the canonical list of headers:

CanonicalHeaders = CanonicalHeadersEntry[0] + CanonicalHeadersEntry[1] + ... + CanonicalHeadersEntry[n]
CanonicalHeadersEntry = lowercase(HeaderName) + ':' + trimall(HeaderValue) + '\n'

lowercase represents a function that converts all characters to lowercase, and trimall function removes excess white space before and after values and from inside non-quoted strings, per RFC 2616 Section 4.2.

Build the canonical headers list by iterating through the collection of header names and sorting the headers lowercase character code. Construct each header by using the following rules:

* Append the lowercase header name followed by a colon.

* Append a comma-separated list of values for that header. If there are duplicate headers, the values are comma-separated. Do not sort the values in headers that have multiple values.

* Append a new line (\n).

The following two samples compare a more complex set of headers with their canonical form:

Example original headers:

host:data.usabilla.com\n
date:20150111T003735Z\n

Example canonical form:

date:20150111T003735Z\n
host:data.usabilla.com\n

  1. To create the signed headers list, convert all header names to lowercase, sort them by character code, and use a semicolon to separate the header names. The following pseudocode describes how to construct a list of signed headers. lowercase represents a function that converts all characters to lowercase.

    SignedHeaders =
    lowercase(HeaderName0) + ';' + lowercase(HeaderName1) + ";"
    + ... + lowercase(HeaderNameN)

Build the signed headers list by iterating through the collection of header names, sorted by lowercase character code. For each header name except the last, append a semicolon (';') to the header name to separate it from the following header name.

Only the host and date headers are required. Optionally if the users have added additional headers to the CanonicalHeaders these will also be required. Note: Certain API calls require additional headers to be present in the signed headers list.

Example request: Signed headers

host;date

  1. Use the hash (digest) function SHA256 and create a hashed value from the RequestPayload in the body of the HTTP or HTTPS request. Since none of the current API calls support a request body the RequestPayload must always be the empty string. Therefore the RequestPayload will always be the hexadecimal SHA-256 hash of an empty string.

    HashedPayload = Lowercase(HexEncode(Hash(requestPayload)))

    Example request: RequestPayload

    empty string

    Example request: Hashed RequestPayload

    The following example shows the result of using SHA-256 to hash the example RequestPayload.

    3511de7e95d28ecd39e9513b642aee07e54f4941150d8df8bf94b328ef7e55e2

  2. To construct the finished canonical request, combine all the components from each step as a single string. As noted, each component ends with a newline character. If you follow the canonical request pseudocode explained earlier, the resulting canonical request is shown in the following example:

    Example canonical request:

    GET
    /live/website/button
    date:Mon, 12 Jan 2015 13:57:54 GMT
    host:data.usabilla.dev
    date;host
    3511de7e95d28ecd39e9513b642aee07e54f4941150d8df8bf94b328ef7e55e2

  3. Create a digest (hash) of the canonical request by using the same algorithm that you used to hash the RequestPayload. The hashed canonical request must be represented as a string of lowercase hexademical characters.

    Example hashed canonical request:

    3511de7e95d28ecd39e9513b642aee07e54f4941150d8df8bf94b328ef7e55e2

2. Create a String to Sign

The string to sign includes meta information about your request and about the canonical request. To create the string to sign, concatenate the algorithm, date, credential scope, and the digest of the canonical request, as shown in the following pseudocode:

Structure of the String to Sign:

StringToSign =
Algorithm +
RequestDate +
CredentialScope +
HashedCanonicalRequest

Example of a HTTPS request:

GET
/live/website/button
date:Mon, 12 Jan 2015 13:57:54 GMT
host:data.usabilla.dev
date;host
3511de7e95d28ecd39e9513b642aee07e54f4941150d8df8bf94b328ef7e55e2

To create the string to sign:

  1. Start with the algorithm designation, followed by a newline character. This value is the hashing algorithm that you're using to calculate the digests in the canonical request.

    USBL1-HMAC-SHA256\n

  2. Append the request date value, followed by a newline character. The date is specified by using the ISO8601 Basic format via the Date header in the YYYYMMDD'T'HHMMSS'Z' format. This value must match the value you used in any previous steps.

    20150112T135139Z\n

  3. Append the credential scope value, followed by a newline character. This value is a string that includes the date and termination string (usbl1_request) in lowercase characters.

    20150112/usbl1_request\n

    The date must be in the YYYYMMDD format. Note that the date does not include a time value.

  4. Append the hash of the canonical request that you created in task 1; Create a canonical Request. This value is not followed by a newline character. The hashed canonical request must be lowercase base-16 encoded, as defined by Section 8 of RFC 4648

    daf6b02d8ae6809bf3b2445c480c1ee6038da1a19a2bd5ad21b7a30acd0fdec2

Example string to sign:

USBL1-HMAC-SHA256
20150112T135139Z
20150112/usbl1_request
daf6b02d8ae6809bf3b2445c480c1ee6038da1a19a2bd5ad21b7a30acd0fdec2

3. Calculate the Signature

Before you calculate a signature, you derive a signing key from your Usabilla secret key.

To calculate a signature:

  1. Derive your signing key. To do this, you use your secret access key to create a series of hash-based message authentication codes (HMACs) as shown by the following pseudocode, where HMAC(key, data) represents an HMAC-SHA256 function that returns output in binary format. The result of each hash function becomes input for the next one.

    Pseudocode for deriving a signing key:

    kSecret = Your Usabilla Secret Key
    kDate = HMAC("USBL1" + kSecret, Date)
    kSigning = HMAC(kDate, "usbl1_request")

    Use the digest for the key derivation. Most languages have functions to compute either a binary format hash, commonly called a digest, or a hex-encoded hash, called a hexdigest. The key derivation requires that you use a digest.

    Example inputs:

    HMAC(HMAC("USBL1" + kSecret,"20110909"),"usbl1_request")

    The following example shows the derived signing key that results from this sequence of HMAC hash operations, using the inputs shown in the previous example. This representation shows the digit representation of each byte in the binary derived key.

    Example signing key:

    152 241 216 137 254 196 244 66 26 220 82 43 171 12 225 248 46 105 41 194 98 237 21 229 169 76 144 239 209 227 176 231

  2. Calculate the signature. To do this, use the signing key that you derived and the string to sign as inputs to the keyed hash function. After you've calculated the signature as a digest, convert the binary value to a hexadecimal representation.

    Pseudocode for calculating the signature:

    signature = HexEncode(HMAC(derived-signing-key, string-to-sign))

    Note: Make sure you specify the HMAC parameters in the correct order for the programming language you are using. This example shows the key as the first parameter and the data (message) as the second parameter, but the function that you use might specify the key and data in a different order.

    Example signature:

    ced6826de92d2bdeed8f846f0bf508e8559e98e4b0199114b84c54174deb456c

4. Sign the Request

After you have calculated the signature, add it to the Authorization header of your request.

The following pseudocode shows the construction of the Authorization header:

Authorization: algorithm
Credential=access key ID/credential scope,
SignedHeaders=SignedHeaders,
Signature=signature

The following example shows a finished Authorization header:

Authorization: USBL1-HMAC-SHA256
Credential=AccessKey/20130524/usbl1_request,
SignedHeaders=date;host;user-agent,
Signature=fe5f80f77d5fa3beca038a248ff027d0
445342fe2855ddc963176630326f1024

Note the following:

Request URL structure

This section covers the resources that can be requested.

https://data.usabilla.com/live/<product-name>/<resource-type>/<id>/<nested-resource>?params

Parameters

Field Type Description
id String The id of the resource
params String Query URL parameters

200 OK

{
  "items": [
    ...
  ],
  "count": 0,
  "hasMore": false,
  "lastTimestamp": 1419340238645
}
Field Type Description
items Array An array containing items of the requested resource type
count Integer The number of items returned
hasMore Integer A flag that indicates whether more items can be requested
lastTimestamp Timestamp The timestamp of the last item in the items array. Can be used to request more items when hasMore is true

Errors

403 Forbidden

{
  "error": "Invalid client key"
}
Field Description
DateError Date is not valid
SignatureDoesNotMatch The signature does not match the content
SignatureMissing Request doesn't have a signature
TokenMismatch Token not found
HostError Requested host is not valid

404 Not Found

Field Description
NotFound Invalid URL

429 Too Many Requests

Field Description
TooManyRequests Request limit reached, please contact your Usabilla account manager
RateLimitExceeded Request rate too high

500 Internal Server Error

{
    "error": "The server has encountered an error."
}

Field Description
DatabaseError Account Provider not available
WrongCodec Signed algorithm is not valid
QueryFailed Could not query
AuthenticationFailed Please re-authenticate

Usabilla for Websites

Feedback Button

This section covers the resources that can be requested regarding Usabilla's Feedback buttons. The feedback button is a button widget that is shown on your website at a visible but non-obtrusive location to enable visitors to leave feedback on their experience.

Get Buttons

/**
 * argv[0] Access Key
 * argv[1] Secret Key
 */
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');

const usabilla = new Usabilla(args[0], args[1]);

// Get all buttons for this account.
usabilla.websites.buttons
  .get()
  .then(buttons => {
    const button = buttons[0];
    if (!button) {
      return;
    }
  })
  .catch(reason => {
    // If the usabilla call fails, we want to see the error message
    console.error(reason);
  });
import usabilla as ub

if __name__ == '__main__':
    # Create an API client with access key and secret key
    api = ub.APIClient('YOUR-ACCESS-KEY', 'YOUR-SECRET-KEY')

    # Get all buttons for this account
    buttons = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_WEBSITES,api.RESOURCE_BUTTON)

    # Print first button
    first_button = buttons['items'][0]
    print first_button['name']
<?php

require 'autoload.php';

use Usabilla\API\Client\UsabillaClient;

// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');

// Gets the command.
$command = $client->getCommand('GetWebsiteButtons');

// Executes the command.
$response = $client->execute($command);

// Prints the received response.
print_r($response);
package main

import (
    "os"
    "fmt"
    "github.com/usabilla/api-go"
)

func main() {
    key := os.Getenv("USABILLA_API_KEY")
    secret := os.Getenv("USABILLA_API_SECRET")

    // Pass the key and secret which should be defined as ENV vars
    usabilla := usabilla.New(key, secret, nil)

    resource := usabilla.Buttons()

    // Get the first ten buttons
    params := map[string]string{"limit": "10"}
    buttons, _ := resource.Get(params)
}

The data will be received in JSON format like this:

{
    "id": "8d73568ac2be",
    "name": "My website feedback button"
}

Endpoint

GET /live/websites/button

This request returns all your feedback buttons in JSON format as shown to the right.

Success response

Field Type Description
id String Unique identifier for a button. 12 characters long.
name String The name of the button given when created. Can be updated in the button setup page.

Get Feedback Items

/* eslint-disable no-console */
/**
 * argv[0] Access Key
 * argv[1] Secret Key
 */
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');

const usabilla = new Usabilla(args[0], args[1]);
    // Use a button id to get feedback for a specific button.
    let buttonFeedbackQuery = {
      id: button.id,
      params: {
        limit: 10
      }
    };
    usabilla.websites.buttons.feedback
      .get(buttonFeedbackQuery)
      .then(feedback => {
        console.log('# button feedback', feedback.length);
      })
      .catch(reason => {
        console.error(reason);
      })
  .catch(reason => {
    // If the usabilla call fails, we want to see the error message
    console.error(reason);
  });
import usabilla as ub

if __name__ == '__main__':
    # Create an API client with access key and secret key
    api = ub.APIClient('YOUR-ACCESS-KEY', 'YOUR-SECRET-KEY')

    # Get the feedback items from a specific button
    feedback_items = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_WEBSITES, api.RESOURCE_FEEDBACK, 'button_id', iterate=True)
    print len([item for item in feedback_items])
<?php

require 'autoload.php';

use Usabilla\API\Client\UsabillaClient;

// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');

// Specify the parameters as mentioned in the service description:
    //NonMandatoryIdParam defaults to * if not set, must be of type string
    //NonMandatoryLimitParam must be of type integer
    //NonMandatorySinceParam must be of type integer
$params = ['id' => 'NonMandatoryIdParam', 'limit' => NonMandatoryLimitParam, 'since' => NonMandatorySinceParam];

// Gets the command.
$command = $client->getCommand('GetWebsiteFeedbackItems', $params);

// Executes the command.
$response = $client->execute($command);

// Prints the received response.
print_r($response);
package main

import (
    "os"
    "fmt"
    "github.com/usabilla/api-go"
)

func main() {
    key := os.Getenv("USABILLA_API_KEY")
    secret := os.Getenv("USABILLA_API_SECRET")

    // Pass the key and secret which should be defined as ENV vars
    usabilla := usabilla.New(key, secret, nil)

    resource := usabilla.Buttons()

    // Get the first ten buttons
    params := map[string]string{"limit": "10"}
    buttons, _ := resource.Get(params)

    // Print all feedback items for each button
    for _, button := range buttons.Items {
        feedback, _ := resource.Feedback().Get(button.ID, nil)
        fmt.Printf("Feedback for button: %s\n%v\n", button.ID, feedback.Items)
    }
}

The data will be received in JSON format like this:

{
    "buttonId": "07f5ec0c3b93",
    "comment": "asd",
    "custom": null,
    "date": "2015-04-28T14:48:39.289Z",
    "email": "",
    "id": "553f9dc7d350221532dfa715",
    "image": "",
    "labels": [],
    "location": "Netherlands",
    "nps": 10,
    "publicUrl": "https://www.usabilla.com/feedback/item/538ce51b93804a7f568324fbef81e6559743ba7e",
    "rating": 5,
    "tags": [],
    "url": "https://staging.usabilla.com/",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.90 Safari/537.36"
}

After a visitor leaves feedback on a button it becomes a feedback item that consists of several data fields.

Endpoint

GET /live/websites/button/:id/feedback

Parameters

Field Type Description
id String The button id. If you wish to get all available feedback items use * (asterisk) as value.
limit Integer Optional URL query parameter that limits the number of retrieved results between 1 and 100. Default value is 100.
since Timestamp [Optional] UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value.

Success response

Field Type Description
id String Unique identifier of the feedback item.
userAgent String Information about the browser's user-agent.
comment String Comment given by the user in the feedback form.
commentTranslated String The translated version of the comment given by the user.
commentTranslatedFrom String The language from which the translation was made.
location String String containing geographical information about the location of the user based on the user's ip address.
date Date The creation date of the feedback item, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601.
custom Map Custom variables that have been assigned in the button setup page.
email String Optional field that the user fills in in case he wishes to be contacted.
image String The screenshot of the specific item that has been selected to give feedback on.
labels Map An array of labels that have been assigned to the feedback item.
nps Integer The Net Promoter Score given by the user (0-10).
publicUrl String When the owner of the button has publicized the feedback item it becomes publicly accesible through this URL.
rating Integer Rating given by the user (0-5).
buttonId String The source button of the feedback item.
tags Array An array of tags assigned to the feedback item.
url Integer The link through which the source button can be accessed in the backend.

Campaigns

This section covers how to retrieve data for Usabilla Campaigns. These surveys are aimed towards web users with specific targeting options set up. The survey will trigger without the users intent, actively asking for feedback.

Get Campaigns

/**
 * argv[0] Access Key
 * argv[1] Secret Key
 */
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');

const usabilla = new Usabilla(args[0], args[1]);

// Get all campaigns
usabilla.websites.campaigns
  .get()
  .then(campaigns => {
    const campaign = campaigns[0];

    console.log('# campaigns', campaigns.length);

    if (!campaign) {
      return;
    }});
import usabilla as ub

if __name__ == '__main__':
    # Create an API client with access key and secret key
    api = ub.APIClient('YOUR-ACCESS-KEY', 'YOUR-SECRET-KEY')

    # Get all campaigns
    campaigns = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_WEBSITES, api.RESOURCE_CAMPAIGN)
    first_campaign = campaigns['items'][0]
    print first_campaign['name']
<?php

require 'autoload.php';

use Usabilla\API\Client\UsabillaClient;

// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');

// Specify the parameters as mentioned in the service description:
    //NonMandatoryLimitParam must be of type integer
    //NonMandatorySinceParam must be of type integer
$params = ['limit' => NonMandatoryLimitParam, 'since' => NonMandatorySinceParam];

// Gets the command.
$command = $client->getCommand('GetWebsiteCampaigns', $params);

// Executes the command.
$response = $client->execute($command);

// Prints the received response.
print_r($response);
// Go example under construction

The data will be received in JSON format like this:

{
    "id": "5499612ec4698839368b4573",
    "date": "2014-01-15T19:48:06.003Z",
    "buttonId": "8d73568ac2be",
    "analyticsId": "901f1d832a55",
    "status": "active",
    "name": "My campaign",
    "type": "boost",
    "url": ""
}

Endpoint

GET /live/websites/campaign

This request returns a list of your Usabilla for Websites Campaigns.

Parameters

Field Type Description
limit Integer Optional. URL query parameter that limits the number of retrieved results between 1 and 100. Defaults to 100 when omitted.
since Timestamp Optional. UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value.

Success response

Field Type Description
id String Unique identifier for a campaign.
date Date The creation date of the campaign, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601.
buttonId String The source button that triggers the campaign.
analyticsId String Analytics ID.
status String The status of the campaign. Possible values are created, active, paused and finished.
name String The name of the campaign given when created. Can be updated in the campaign setup page.
type String The type of the campaign.
url String The url of the campaign when the campaign is of type Survey, empty otherwise.

Get Campaign Results

/**
 * argv[0] Access Key
 * argv[1] Secret Key
 */
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');

const usabilla = new Usabilla(args[0], args[1]);

// Specify a campaign id
let campaignQuery = {
    id: campaign.id
};

// Get the responses from a campaign with the specific id
usabilla.websites.campaigns.results
    .get(campaignQuery)
    .then(responses => {
        console.log('# web campaign responses', responses.length);
    })
    .catch(reason => {
        console.error(reason);
    });
import usabilla as ub

if __name__ == '__main__':

# Get the responses of a specific campaign
    responses = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_WEBSITES, api.RESOURCE_CAMPAIGN_RESULT, <CAMPAIGN_ID>, iterate=True)
    print len([item for item in responses])
// Go example under construction
<?php

require 'autoload.php';

use Usabilla\API\Client\UsabillaClient;

// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');

// Specify the parameters as mentioned in the service description:
    //MandatoryIdParam must be of type string
    //NonMandatoryLimitParam must be of type integer
    //NonMandatorySinceParam must be of type integer
$params = ['id' => 'MandatoryIdParam', 'limit' => NonMandatoryLimitParam, 'since' => NonMandatorySinceParam];

// Gets the command.
$command = $client->getCommand('GetWebsiteCampaignResults', $params);

// Executes the command.
$response = $client->execute($command);

// Prints the received response.
print_r($response);

The data will be received in JSON format like this:

{
    "id": "549972d5c469885e548b4570",
    "campaignId": "5499612ec4698839368b4573",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.95 Safari/537.36",
    "location": "Amsterdam, Netherlands",
    "date": "2014-01-15T19:48:06.003Z",
    "customData": {
        "form_name": "form1"
    },
    "data": {
        "text": "test"
    },
    "time": 5000,
    "url": "https://usabilla.com"
}

Endpoint

GET /live/websites/campaign/:id/results

This request returns the responses of a campaign with a specific id.

Parameters

Field Type Description
id String The campaign id. Use * (asterisk) to request feedback of all campaigns.
limit Integer Optional. URL query parameter that limits the number of retrieved results between 1 and 100. Defaults to 100 when omitted.
since Timestamp Optional. UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value.

Success 200

Field Type Description
id String Unique identifier for a campaign result.
date Date The creation date of the campaign result item, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601.
campaignId String Unique identifier for the campaign it belongs to.
userAgent String Information about the browser user agent.
url String Origin URL where the campaign result was registered.
customData Map Custom variables that have been assigned to the campaign result.
data Array An array containing the values of the campaign form fields.
time Integer The amount of time the user has taken to complete the survey. Expressed in miliseconds.
location String String containing geographical information about the location of the user based on the user's IP address.

Get Campaign Statistics

/**
 * argv[0] Access Key
 * argv[1] Secret Key
 */
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');

const usabilla = new Usabilla(args[0], args[1]);

// Get the stats of the first campaign
usabilla.websites.campaigns.stats
    .get(campaignQuery)
    .then(stats => {
    console.log('# web campaign stats', stats);
    })
    .catch(reason => {
    console.error(reason);
    });
import usabilla as ub

if __name__ == '__main__':
# Get the stats of the first campaign
    stats = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_WEBSITES, api.RESOURCE_CAMPAIGN_STATS, first_campaign['id'])
    print stats
// Go example under construction
<?php

require 'autoload.php';

use Usabilla\API\Client\UsabillaClient;

// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');

// Specify the parameters as mentioned in the service description:
    //MandatoryIdParam must be of type string
    //NonMandatoryLimitParam must be of type integer
    //NonMandatorySinceParam must be of type integer
$params = ['id' => 'MandatoryIdParam', 'limit' => NonMandatoryLimitParam, 'since' => NonMandatorySinceParam];

// Gets the command.
$command = $client->getCommand('GetWebsiteCampaignStats', $params);

// Executes the command.
$response = $client->execute($command);

// Prints the received response.
print_r($response);

The data will be received in JSON format like this:

{
    "id": "549972d5c469885e548b4570",
    "completed": 5,
    "conversion": 83,
    "views": 6
}

Endpoint

GET /live/websites/campaign/:id/stats

This endpoint returns the statistics of a campaign with a specific id.

Parameters

Field Type Description
id String The campaign id. Use * (asterisk) to request feedback of all campaigns.

Success response

Field Type Description
id String Unique identifier for a campaign result.
completed Integer The amount of completed campaign forms that were submitted.
views Integer The amount of views the campaign form got by counting how many times it was opened.
conversion Integer The percentage of conversion (views to completion).

In-Page

This section is regarding the Usabilla In-Page product and how to retrieve the feedback data. The In-Page widget can be placed anywhere on your webpage for users to give valuable feedback on the web content.

Get In-Page Widgets

/**
 * argv[0] Access Key
 * argv[1] Secret Key
 */
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');

const usabilla = new Usabilla(args[0], args[1]);

// Get all inpage widgets for this account.
usabilla.websites.inpage.get()
import usabilla as ub

# Create an API client with access key and secret key
api = ub.APIClient('ACCESS_KEY', 'SECRET_KEY')

api.set_query_parameters({'limit': 10})

# Get all In - Page Widgets for this account
widgets = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_WEBSITES, api.RESOURCE_INPAGE)

print(widgets)

# Get one specific widget
specific_widget = widgets['items'][1]
print(specific_widget)

// Go example under construction
<?php

require 'autoload.php';

use Usabilla\API\Client\UsabillaClient;

// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');

// Specify the parameters as mentioned in the service description:
    //NonMandatoryLimitParam must be of type integer
    //NonMandatorySinceParam must be of type integer
$params = ['limit' => NonMandatoryLimitParam, 'since' => NonMandatorySinceParam];

// Gets the command.
$command = $client->getCommand('GetInpageWidgets', $params);

// Executes the command.
$response = $client->execute($command);

// Prints the received response.
print_r($response);

The data will be received in JSON format like this:

{
    "id": "5499612ec4698839368b4573",
    "date": "2014-01-15T19:48:06.003Z",
    "name": "My In-Page widget"
}

Endpoint

GET /live/websites/inpage

This endpoint returns a list of your Usabilla for Websites In-Page widgets.

Parameters

Field Type Description
limit Integer Optional. URL query parameter that limits the number of retrieved results between 1 and 100. Defaults to 100 when omitted.
since Timestamp Optional. UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value.

Success response

Field Type Description
id String Unique identifier for an In-Page widget.
date Date The creation date of the In-Page widget, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601.
name String The name of the In-Page widget given when created. Can be updated in the In-Page widget setup page.

Get In-Page Feedback

/**
 * argv[0] Access Key
 * argv[1] Secret Key
 */
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');

const usabilla = new Usabilla(args[0], args[1]);

// Get all inpage widgets for this account.
usabilla.websites.inpage
  .get()
  .then(inPageWidgets => {
    // Get the feedback for an inpage widget with id.
    let inPageQuery = {
      id: inPageWidgets[0].id
    };

    // Get the feedback of the first inpage widget
    usabilla.websites.inpage.feedback
      .get(inPageQuery)
      .then(feedback => {
        console.log('# inpage feedback', feedback.length);
      })
      .catch(reason => {
        console.error(reason);
      });
  })
  .catch(reason => {
    // If the Usabilla call fails, we want to see the error message
    console.error(reason);
  });
import usabilla as ub

# Create an API client with access key and secret key
api = ub.APIClient('ACCESS_KEY', 'SECRET_KEY')

# Get feedback of the first widget
feedback = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_WEBSITES, api.RESOURCE_INPAGE_RESULT, 'WIDGET_ID', iterate=False)

print(feedback)
// Go example under construction
<?php

require 'autoload.php';

use Usabilla\API\Client\UsabillaClient;

// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');

// Specify the parameters as mentioned in the service description:
    //MandatoryIdParam must be of type string
    //NonMandatoryLimitParam must be of type integer
    //NonMandatorySinceParam must be of type integer
$params = ['id' => 'MandatoryIdParam', 'limit' => NonMandatoryLimitParam, 'since' => NonMandatorySinceParam];

// Gets the command.
$command = $client->getCommand('GetInpageWidgetFeedbackItems', $params);

// Executes the command.
$response = $client->execute($command);

// Prints the received response.
print_r($response);

The data will be received in JSON format like this:

{
    "id": "549972d5c469885e548b4570",
    "date": "2014-01-15T19:48:06.003Z",
    "widgetId": "5499612ec4698839368b4573",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.95 Safari/537.36",
    "location": "Amsterdam, Netherlands",
    "geo": {
        "city": "Schoten",
        "country": "BE",
        "region": "01"
    },
    "comment": "Very nice indeed",
    "data": {
        "Did_you_enjoy_th": 5
    },
    "customData": {
        "form_name": "form1"
    },
    "mood": 3,
    "rating": 0.5,
    "nps": 5,
    "url": "https://usabilla.com"
}

Endpoint

GET /live/websites/inpage/:id/feedback

This endpoint returns a list of your Usabilla for Websites In-Page feedback.

Parameters

Field Type Description
id String The In-Page widget id. Use * (asterisk) to request feedback of all In-Page widgets.
limit Integer Optional. URL query parameter that limits the number of retrieved results between 1 and 100. Defaults to 100 when omitted.
since Timestamp Optional. UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value.

Success response

Field Type Description
id String Unique identifier for the In-Page widget feedback item.
date Date The creation date of the in-page widget, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601.
data Array An array containing the values of the In-Page widget form fields.
customData Array An array containing the values of the widget's custom fields.
widgetId String Unique identifier for the In-Page widget it belongs.
mood Integer Mood given by the user (0-5).
rating Float32 Rating from 0.0 to 1.0.
nps Integer The Net Promoter Score given by the user (0-10).
comment String Comment given by the user in the feedback form.
userAgent String Information about the browser user agent.
url String Origin URL where the In-Page widget result was registered.
geo Map Geographic location of user, consisting of city, country and region.

Usabilla for Email

Usabilla for Email is a real-time customer feedback solution for integration with your email system. This section covers the resources that can be requested regarding the Usabilla for Email product.

Get Email Widgets

The email feedback widget is a widget usually placed in the footer of an email. Your recipients can click on the feedback widget after reading your email in order to give feedback.

/**
 * argv[0] Access Key
 * argv[1] Secret Key
 */
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');

const usabilla = new Usabilla(args[0], args[1]);

// Get all email widgets for this account.
usabilla.email.widgets.get()
import usabilla as ub

if __name__ == '__main__':
    # Create an API client with access key and secret key
    api = ub.APIClient('YOUR-ACCESS-KEY', 'YOUR-SECRET-KEY')

    # Get all email widgets for this account
    widgets = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_EMAIL, api.RESOURCE_BUTTON)
    first_widget = widgets['items'][0]
    print first_widget['name']
// Go example under construction
<?php

require 'autoload.php';

use Usabilla\API\Client\UsabillaClient;

// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');

// Gets the command.
$command = $client->getCommand('GetEmailButtons');

// Executes the command.
$response = $client->execute($command);

// Prints the received response.
print_r($response);

The data will be received in JSON format like this:

{
    "date": "2015-03-11T14:35:04.536Z",
    "groups": [
        {
            "active": true,
            "date": "2015-03-11T14:35:04.539Z",
            "id": "af8c54de7067",
            "name": "Joshua's email footer"
        }
    ],
    "id": "e4b5a0661176",
    "introText": "We'd love your input",
    "locale": "en_US",
    "name": "Mail campaign"
}

Endpoint

GET /live/email/widget

This endpoint returns a list of your email widgets

Parameters

Field Type Description
limit Integer Optional URL query parameter that limits the number of retrieved results between 1 and 100. Defaults to 100 when omitted.
since Timestamp Optional UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value.

Success response

Field Type Description
id String Unique identifier of the widget. 12 characters long.
date Date The creation date of the email widget, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601.
name String The name of the widget.
introText String The name of the widget given when created. Can be updated in the widget setup page.
locale String Regional language of the widget and form text items.
groups Array List of groups this campaign item is member of.

Get Email Feedback

After the reader leaves feedback on an email widget it becomes a feedback item that you can view in your Usabilla account.

/**
 * argv[0] Access Key
 * argv[1] Secret Key
 */
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');

const usabilla = new Usabilla(args[0], args[1]);

// Get all email widgets for this account.
usabilla.email.widgets
  .get()
  .then(emailWidgets => {
    // Get the feedback for a email widget with id.
    let emailQuery = {
      id: emailWidgets[0].id
    };

    // Get the feedback of the first email widget
    usabilla.email.widgets.feedback
      .get(emailQuery)
      .then(feedback => {
        console.log('# email feedback', feedback.length);
      })
      .catch(reason => {
        console.error(reason);
      });
  })
  .catch(reason => {
    // If the usabilla call fails, we want to see the error message
    console.error(reason);
  });
import usabilla as ub

if __name__ == '__main__':
    # Create an API client with access key and secret key
    api = ub.APIClient('YOUR-ACCESS-KEY', 'YOUR-SECRET-KEY')

    # Get all email widgets for this account
    widgets = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_EMAIL, api.RESOURCE_BUTTON)
    first_widget = widgets['items'][0]
    print first_widget['name']

    # Get the feedback of the first email widget
    feedback = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_EMAIL, api.RESOURCE_FEEDBACK, first_widget['id'], iterate=True)
    print len([item for item in feedback])
// Go example under construction
<?php

require 'autoload.php';

use Usabilla\API\Client\UsabillaClient;

// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');

// Specify the parameters as mentioned in the service description:
    //NonMandatoryIdParam defaults to * if not set, must be of type string
    //NonMandatoryLimitParam must be of type integer
    //NonMandatorySinceParam must be of type integer
$params = ['id' => 'NonMandatoryIdParam', 'limit' => NonMandatoryLimitParam, 'since' => NonMandatorySinceParam];

// Gets the command.
$command = $client->getCommand('GetEmailFeedbackItems', $params);

// Executes the command.
$response = $client->execute($command);

// Prints the received response.
print_r($response);

The data will be received in JSON format like this:

{
    "id": "5499612ec4698839368b4573",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.95 Safari/537.36",
    "comment": "Thx for your email.",
    "location": "Amsterdam, Netherlands",
    "date": "2014-01-15T19:48:06.003Z",
    "customData": {
        "form_name": "form1"
    },
    "email": "dev@usabilla",
    "labels": [
        "label 1",
        "label 2"
    ],
    "nps": 10,
    "rating": 5,
    "widgetId": "8d73568ac2be",
    "tags": [
        "interesting",
        "unattractive"
    ],
    "urlParams": {
        "utm_campaign": "1234576_20160101_my_campaign",
        "utm_medium": "email",
        "utm_source": "email_feedback_form"
    }
}

Endpoint

GET /live/email/widget/:id/feedback

This request returns a list of your email widget feedback.

Parameters

Field Type Description
id String The widget id. If you wish to get all available feedback items use * (asterisk) as value.
limit Integer Optional URL query parameter that limits the number of retrieved results between 1 and 100. Defaults to 100 when omitted.
since Timestamp Optional UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value.

Success response

Field Type Description
id String Unique identifier of the feedback item.
userAgent String Information about the browser user agent.
comment String Commentary left by the user in the feedback form.
location String String containing geographical information about the location of the user based on the user's ip address.
date Date The creation date of the email widget, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601.
customData Map Custom variables that have been assigned in the widget setup page.
email String Optional field that the user fills in in case he wishes to be contacted.
labels Map An array of labels that have been assigned to the feedback item.
nps Integer The Net Promoter Score given by the user (0-10).
rating Integer Rating given by the user (0-5).
widgetId String The source widget of the feedback item.
tags Array An array of tags assigned to the feedback item.
urlParams Map The URL parameters passed via the feedback URL.

Usabilla for Apps

Usabilla for Apps is a real-time user feedback system for analysis of customer experience on your mobile applications. This section covers the resources that can be requested regarding the Usabilla for Apps product.

Get App Forms

/**
 * argv[0] Access Key
 * argv[1] Secret Key
 */
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');

const usabilla = new Usabilla(args[0], args[1]);

// Get all apps forms for this account.
usabilla.apps.forms.get().then(appsForms => {
    const appsForm = appsForms[0];

    if (!appsForm) {
      return;
    }
});
import usabilla as ub

from datetime import datetime, timedelta

if __name__ == '__main__':
    # Create an API client with access key and secret key
    api = ub.APIClient('YOUR-ACCESS-KEY', 'YOUR-SECRET-KEY')

    # Set the limit of buttons to retrieve to 1
    if False:
        api.set_query_parameters({'limit': 1})

    # Set a limit for last 7 days
    # NB: You might need to convert the since_unix calculation from scientific notation or set the since parameter manually
    if False:
        epoch = datetime(1970, 1, 1)
        since = timedelta(days=7)
        since_unix = (datetime.utcnow() - since - epoch).total_seconds() * 1000
        api.set_query_parameters({'since': since_unix})

    # Get all apps forms for this account
    forms = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_APPS, api.RESOURCE_APP)
    first_form = forms['items'][0]
    print first_form['name']
// Go example under construction
<?php

require 'autoload.php';

use Usabilla\API\Client\UsabillaClient;

// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');

// Gets the command.
$command = $client->getCommand('GetApps');

// Executes the command.
$response = $client->execute($command);

// Prints the received response.
print_r($response);

The data will be received in JSON format like this:

{
    "date": "2014-08-22T13:34:07.043Z",
    "id": "53f746cfc469889e628b4568",
    "name": "New untitled App Form",
    "status": "active"
}

Each App has a feedback button placed somewhere in the mobile application. App users can click on the feedback button at any time in order to give feedback. The feedback form (App Form) is initialized in the mobile application by calling the Usabilla SDK with the Form ID.

Endpoint

GET /live/apps

This endpoint returns a list of your App Forms that are created in your Usabilla dashboard.

Parameters

Field Type Description
limit Integer Optional URL query parameter that limits the number of retrieved results between 1 and 100. Defaults to 100 when omitted.
since Timestamp Optional UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value.

Success response

Field Type Description
id String Unique identifier of the Form. 24 characters long.
date Date The creation date of the Form, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601.
name String The name of the Form.
status String The status the Form.

Get App Form Feedback

/**
 * argv[0] Access Key
 * argv[1] Secret Key
 */
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');

const usabilla = new Usabilla(args[0], args[1]);

// Get all apps forms for this account.
usabilla.apps.forms
  .get()
  .then(appsForms => {
    const appsForm = appsForms[0];

    if (!appsForm) {
      return;
    }

    // Get the feedback for a apps form with id.
    let appsQuery = {
      id: appsForm.id
    };

    // Get the feedback of the second app form
    usabilla.apps.forms.feedback
      .get(appsQuery)
      .then(feedback => {
        console.log('# apps feedback', feedback.length);
      })
      .catch(reason => {
        console.error(reason);
      });
  })
  .catch(reason => {
    // If the usabilla call fails, we want to see the error message
    console.error(reason);
  });
import usabilla as ub

from datetime import datetime, timedelta

if __name__ == '__main__':
    # Create an API client with access key and secret key
    api = ub.APIClient('YOUR-ACCESS-KEY', 'YOUR-SECRET-KEY')

    # Set the limit of buttons to retrieve to 1
    if False:
        api.set_query_parameters({'limit': 1})

    # Set a limit for last 7 days
    # NB: You might need to convert the since_unix calculation from scientific notation or set the since parameter manually
    if False:
        epoch = datetime(1970, 1, 1)
        since = timedelta(days=7)
        since_unix = (datetime.utcnow() - since - epoch).total_seconds() * 1000
        api.set_query_parameters({'since': since_unix})

    # Get all apps forms for this account
    forms = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_APPS, api.RESOURCE_APP)
    first_form = forms['items'][0]
    print first_form['name']

    # Get the feedback of the first app form
    feedback = api.get_resource(
        api.SCOPE_LIVE,
        api.PRODUCT_APPS,
        api.RESOURCE_FEEDBACK,
        first_form['id'],
        iterate=True)
    print len([item for item in feedback])
// Go example under construction
<?php

require 'autoload.php';

use Usabilla\API\Client\UsabillaClient;

// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');

// Specify the parameters as mentioned in the service description:
    //NonMandatoryIdParam defaults to * if not set, must be of type string
    //NonMandatoryLimitParam must be of type integer
    //NonMandatorySinceParam must be of type integer
    $params = ['id' => 'NonMandatoryIdParam', 'limit' => NonMandatoryLimitParam, 'since' => NonMandatorySinceParam];

// Gets the command.
$command = $client->getCommand('GetAppFeedbackItems', $params);

// Executes the command.
$response = $client->execute($command);

// Prints the received response.
print_r($response);

The data will be received in JSON format like this:

{
    "appId": "53f746cfc469889e628b4568",
    "appName": "Usabilla Test Frame",
    "appVersion": "48",
    "batteryLevel": -1,
    "connection": "WiFi",
    "customData": {
        "custom_variable": "one",
        "shaken": 1,
        "user_id": "786690"
    },
    "data": {
        "name": "pablo",
        "nps": 8,
        "rating": 4,
        "speed": 5,
        "subject": "Compliment"
    },
    "date": "2015-04-20T08:12:13.382Z",
    "deviceName": "iPhone Simulator",
    "freeMemory": 224776,
    "freeStorage": 131880204,
    "geoLocation": {
        "country": "NL",
        "region": "07",
        "city": "Amsterdam",
        "lat": 52.35,
        "lon": 4.9167
    },
    "id": "5534b4dcea5b09b33557bb20",
    "ipAddress": "80.101.117.33",
    "language": "en",
    "location": "Amsterdam, Netherlands",
    "orientation": "Portrait",
    "osName": "ios",
    "osVersion": "8.3",
    "rooted": false,
    "screenshot": "https://usabilla-feedback-app.s3.amazonaws.com/staging/media/55/34/5534b4dcea5b09b33557bb20/screenshot",
    "screensize": "320x568",
    "timestamp": "1429517532",
    "totalMemory": 14032256,
    "totalStorage": 243924992
}

After the user sends feedback using the feedback button it becomes a feedback item that you can view in your Usabilla dashboard.

Endpoint

GET /live/apps/:id/feedback

This endpoint returns a list of your feedback items that are connected to a specific App Form. The App Form is loaded in from the Usabilla SDK once a user clicks on the feedback button in the application.

Parameters

Field Type Description
id String The Form ID. For feedback items of all Forms use * (asterisk) as value.
limit Integer Optional URL query parameter that limits the number of retrieved results between 1 and 100. Defaults to 100 when omitted.
since Timestamp Optional UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value.

Success response

Field Type Description
id String Unique identifier of the feedback item.
date Date The creation date of the Form, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601.
timestamp String Date and time (Unix timestamp) when feedback was sent by the App.
deviceName String Device name on which the app is running.
data Map Map containing the Feedback data ("mood" and "nps" scores).
customData Map Map containing the optionally configured custom values.
appId String ID of the feedback form the feedback item belongs to.
appName String Name of the feedback form
appVersion String Version of the app.
osName String Operating System name on which the app is running.
osVersion String Operating System version on which the app is running.
location String Readable location (City, Country).
geoLocation Map Geographic location details ("country", "region", "city", "lat", "lon").
freeMemory Integer Bytes of RAM left unused.
totalMemory Integer Bytes of RAM in total.
freeStorage Integer Bytes of storage memory left unused.
totalStorage Integer Bytes of storage memory in total.
screenshot String Screenshot URL.
screensize String Screen property size.
connection String Current connections.
ipAddress String Current IP address.
language String Language used.
orientation String The orientation of the screen at time of feedback ['Portrait','Landscape'].
batteryLevel Float32 Battery level from 0.0 to 1.0 (-1 means unknown).

Get App Campaigns

// JavaScript example under construction 
import usabilla as ub

from datetime import datetime, timedelta

if __name__ == '__main__':
    # Create an API client with access key and secret key
    api = ub.APIClient('YOUR-ACCESS-KEY', 'YOUR-SECRET-KEY')

    # Set the limit of buttons to retrieve to 1
    if False:
        api.set_query_parameters({'limit': 1})

    # Set a limit for last 7 days
    # NB: You might need to convert the since_unix calculation from scientific notation or set the since parameter manually
    if False:
        epoch = datetime(1970, 1, 1)
        since = timedelta(days=7)
        since_unix = (datetime.utcnow() - since - epoch).total_seconds() * 1000
        api.set_query_parameters({'since': since_unix})

    # Campaigns for apps
    app_campaigns = api.get_resource(
        api.SCOPE_LIVE,
        api.PRODUCT_APPS,
        api.RESOURCE_CAMPAIGN)
    first_campaign = app_campaigns['items'][0]
// Go example under construction
<?php

require 'autoload.php';

use Usabilla\API\Client\UsabillaClient;

// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');

// Gets the command.
$command = $client->getCommand('GetAppCampaigns');

// Executes the command.
$response = $client->execute($command);

// Prints the received response.
print_r($response);

The data will be received in JSON format like this:

{
    "id": "a705f2be-d55c-4a5e-8b35-32a472f860f1",
    "createdAt": "2018-02-27T16:56:42.555Z",
    "lastModifiedAt": "2019-01-24T16:00:51.623Z",
    "status": "active",
    "name": "checkout confirmation page",
    "appIds": [
        "f9604f35-6d9a-4f1c-a5fa-33402d7a4d96"
    ]
}

The App Campaigns are activated within the App by sending an event to our SDK.

Endpoint

GET /live/apps/campaign

This endpoint returns a list of your Usabilla for Apps Campaigns.

Parameters

Field Type Description
limit Integer Optional URL query parameter that limits the number of retrieved results between 1 and 100. Defaults to 100 when omitted.
since Timestamp Optional UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value.

Success response

Field Type Description
id String Unique identifier of the campaign.
createdAt Date The creation date of the campaign, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601.
lastModifiedAt Date The creation date of the campaign, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601.
status String The status of the campaign. Can be active or inactive.
name String The name of the campaign.
appIds Array Map containing the AppID's connected to the campaign.

Get App Campaign Feedback

// JavaScript example under construction
import usabilla as ub

from datetime import datetime, timedelta

if __name__ == '__main__':
    # Create an API client with access key and secret key
    api = ub.APIClient('YOUR-ACCESS-KEY', 'YOUR-SECRET-KEY')

    # Set the limit of buttons to retrieve to 1
    if False:
        api.set_query_parameters({'limit': 1})

    # Set a limit for last 7 days
    # NB: You might need to convert the since_unix calculation from scientific notation or set the since parameter manually
    if False:
        epoch = datetime(1970, 1, 1)
        since = timedelta(days=7)
        since_unix = (datetime.utcnow() - since - epoch).total_seconds() * 1000
        api.set_query_parameters({'since': since_unix})

    # Campaigns for apps
    app_campaigns = api.get_resource(
        api.SCOPE_LIVE,
        api.PRODUCT_APPS,
        api.RESOURCE_CAMPAIGN)
    first_campaign = app_campaigns['items'][0]
    responses = api.get_resource(
        api.SCOPE_LIVE,
        api.PRODUCT_APPS,
        api.RESOURCE_CAMPAIGN_RESULT,
        first_campaign['id'],
        iterate=True)
    print len([item for item in responses])
// Go example under construction
<?php

require 'autoload.php';

use Usabilla\API\Client\UsabillaClient;

// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');

// Specify the parameters as mentioned in the service description:
    //MandatoryIdParam must be of type string
    //NonMandatoryLimitParam must be of type integer
    //NonMandatorySinceParam must be of type integer
    $params = ['id' => 'MandatoryIdParam', 'limit' => NonMandatoryLimitParam, 'since' => NonMandatorySinceParam];

// Gets the command.
$command = $client->getCommand('GetAppCampaignResults', $params);

// Executes the command.
$response = $client->execute($command);

// Prints the received response.
print_r($response);

The data will be received in JSON format like this:

{
    "id": "bd1c5b72-2c77-4de3-b65c-b314cc540af4",
    "date": "2018-12-04T15:20:05.011Z",
    "campaignId": "e67e8b74-ca36-4a29-8fdd-1be78e32fabb",
    "appId": "15f2e909-fecc-4cee-871a-385c7bba3b54",
    "data": {
        "mood": 3
    },
    "context": null,
    "metadata": {
        "app_name": "Demo App",
        "app_version": "1",
        "battery": 1,
        "device": "x86_64",
        "language": "en",
        "network_connection": "WiFi",
        "orientation": "Portrait",
        "os_version": "12.0",
        "screen": "375 x 667",
        "sdk_version": "5.1.4",
        "system": "ios",
        "timestamp": "2018-12-04T15:17:36Z"
    },
    "complete": false
}

After the user gives feedback through the campaign it becomes a feedback item that you can view in your Usabilla account.

Endpoint

GET /live/apps/campaign/:id/results

This endpoint returns a list of your Usabilla for Apps Campaign feedback items.

Parameters

Field Type Description
limit Integer Optional URL query parameter that limits the number of retrieved results between 1 and 100. Defaults to 100 when omitted.
since Timestamp Optional UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value.

Success response

Field Type Description
id String Unique identifier of the campaign feedback.
date Date The date of the feedback, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601.
appId String App ID connected to the campaign feedback.
campaignId String Campaign ID connected to the campaign feedback.
data Map Contains all the feedback from the campaign.
context Map Custom variables connected to the campaign feedback
metadata Map Metadata from the device
complete String Equals to true if campaign feedback is fully completed. Equals to false if the user didn't finish the campaign

Get App Campaign Feedback schema

// JavaScript example under construction
// Python example under construction
// Go example under construction
// PHP example under construction

The data will be received in JSON format like this:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://data.usabilla.com/live/apps/campaign/50e463f7-4f44-4c96-b12c-47da71c9251d/results/schema",
    "description": "Usabilla for Apps Campaign feedback item.",
    "title": "Feedback",
    "type": "object",
    "properties": {
        "appId": {
            "description": "App ID connected to the campaign feedback.",
            "format": "uuid",
            "type": "string"
        },
        "campaignId": {
            "description": "Campaign ID connected to the campaign feedback.",
            "format": "uuid",
            "type": "string"
        },
        "complete": {
            "description": "Equals to true if campaign feedback is fully completed. Equals to false if the user didn't finish the campaign",
            "type": "boolean"
        },
        "context": {
            "description": "Custom variables connected to the campaign feedback",
            "type": [
                "object",
                "null"
            ],
            "properties": {
                "*": {
                    "type": "string"
                }
            }
        },
        "data": {
            "description": "Contains all the feedback from the campaign.",
            "type": ["object", "null"],
            "properties":
            {
                "nps": {
                    "type": [
                        "integer",
                        "null"
                    ]
                }
            }
        },
        "date": {
            "description": "The date of the feedback, in UTC.",
            "format": "date-time",
            "type": "string"
        },
        "id": {
            "description": "Unique identifier of the campaign feedback.",
            "format": "uuid",
            "type": "string"
        },
        "metadata": {
            "description": "Metadata from the device",
            "type": "object",
            "properties": {
                "app_name": {
                    "description": "Name of the Hosting Application",
                    "type": "string"
                },
                "app_version": {
                    "description": "Version of the Hosting Application",
                    "type": "string"
                },
                "battery": {
                    "description": "Level of battery (-1.0 ... 0  ... 1.0 )",
                    "maximum": 1,
                    "minimum": -1,
                    "type": "number"
                },
                "device": {
                    "description": "Name of the device app is runing on",
                    "type": "string"
                },
                "language": {
                    "description": "Locale of the device",
                    "type": "string"
                },
                "network_connection": {
                    "description": "Current networkconnection ('Cellular' | 'WiFi' | 'No Connection')",
                    "type": "string"
                },
                "orientation": {
                    "description": "Device orientation ('Portrait' | 'Landscape')",
                    "type": "string"
                },
                "os_version": {
                    "description": "Devices os version",
                    "type": "string"
                },
                "screen": {
                    "description": "Device Screen size",
                    "type": "string"
                },
                "sdk_version": {
                    "description": "Version of our SDK",
                    "type": "string"
                },
                "system": {
                    "description": "Operating system of device ('ios' | 'android')",
                    "type": "string"
                },
                "timestamp": {
                    "description": "Time of gathering above data in RFC3339 format",
                    "format": "date-time",
                    "type": "string"
                }
            }
        }
    },
    "required": [
        "appId",
        "campaignId",
        "complete",
        "date",
        "id"
    ]
}

After the user gives feedback through the campaign it becomes a feedback item that you can view in your Usabilla account.

Endpoint

GET /live/apps/campaign/:id/results/schema

This endpoint returns a JSON Schema that will describe all feedback items you can retrieve with the GET /live/apps/campaign/:id/results endpoint.

Parameters

This endpoint has no parameters.

Success response

The response follows the JSON Schema specification which you can find here. The version we're currently using is 2020-12.