NAV
cURL Ruby Python PHP Java JavaScript C#

Introduction

The Mouseflow REST API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs. JSON will be returned in most responses from the API, including errors.

Mouseflow was built API-first to make sure that any data and action available in the web UI is also available through the API.

You can view examples (in various programming languages) in the dark area to the right.

In case you're looking for ways to interact with our JavaScript tracking code, please visit our JS API documentation

Authentication

API endpoint:

https://api-us.mouseflow.com --or-- https://api-eu.mouseflow.com

...where "us" or "eu" represents your account datacenter location. You can check your API endpoint in your account under API Keys. In the following examples we will be using the US endpoint.

You authenticate to the Mouseflow API by providing your API key in the request. You can manage your API keys from your account. Your API keys have the same privileges as your user account, so be sure to keep them safe.

Authentication to the API occurs via HTTP Basic Auth. Provide your email address as the basic auth username, and provide your API key as the password.

All API requests must be made oer HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

Data formats

Date time format

The date/time format we use is the one defined by the ISO 8601 standard.

Examples:

Time spans

For representing time spans we typically use an integer value that represents the number of milliseconds.

Country codes and languages

Country codes

Countries are represented by their two-character country codes, defined by the ISO 3166-1 alpha-2 standard.

Examples:

Languages

Languages are represented by the IETF language tag definition.

Examples:

Common arguments in endpoints

Many arguments in the API calls use the same argument types. Here are the most common ones:

Websites

Website list

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The above command returns JSON structured like this:

[
    {
        "id": "8fc2ace2-75bc-8ba4-b424-c8916670b990",
        "name": "myshop.com",
        "created": "2015-04-25T18:20:55",
        "status": "Recording",
        "thumb": "4ba62c82-f3ae-4f62-94fb-8ebe0c86ea8e.png",
        "readOnly": false,
        "cdnDomainName": "cdn.mouseflow.com",
        "isDemo": false
    },
    {
        "id": "6793a2a8-9be8-42ce-4fb1-9107e379dfde",
        "name": "mysecondshop.com",
        "created": "2013-11-12T12:43:56",
        "status": "Recording",
        "thumb": "467d24f3-0f06-4e5c-b425-187aba10ab2b.png",
        "readOnly": true,
        "cdnDomainName": "cdn.mouseflow.com",
        "isDemo": false
    }
]

Get all available websites in the account.

GET /websites

Properties

Property Datatype Description
id String This the unique ID associated with the website
name String An alias or name you have given for your website (defaults to the website domain)
created DateTime The time the website was registered in Mouseflow
status String A string indicating whether the website is currently recording (values: NotInstalled, Recording, Stopped, Paused). Stopped means that you have manually stopped recording your users. Paused means that the website will start recording once you get credits in your account.
thumb String A partial URL for a thumbnail image generated from your website
readOnly bool A boolean value (true / false) that indicates whether you have readOnly or full access to the website
cdnDomainName String (internal) The domain used for hosting the recording script
isDemo bool (internal) Only set to true on the "Demo Website"

Re-ordering the list

curl -X PUT -u my@email.com:token1234 -H 'Content-Type: application/json' -d '{"websiteIds":["8fc2ace2-75bc-8ba4-b424-c8916670b990", "6793a2a8-9be8-42ce-4fb1-9107e379dfde"]}' https://api-us.mouseflow.com/websites/reorder
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Put.new('/websites/reorder')
request.basic_auth('my@email.com', 'token1234')
request.body = '{"recordingStatus":"Stopped"}'
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.put("https://api-us.mouseflow.com/websites/reorder", '{"websiteIds":["8fc2ace2-75bc-8ba4-b424-c8916670b990", "6793a2a8-9be8-42ce-4fb1-9107e379dfde"]}',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/reorder");
    curl_setopt_array($curl, array(
            CURLOPT_CUSTOMREQUEST => "PUT",
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234",
            CURLOPT_HTTPHEADER => array("Content-Type: application/json")
        ),
        CURLOPT_POSTFIELDS => '{"websiteIds":["8fc2ace2-75bc-8ba4-b424-c8916670b990", "6793a2a8-9be8-42ce-4fb1-9107e379dfde"]}'
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/reorder");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("PUT");
OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
wr.write("{\"websiteIds\":[\"8fc2ace2-75bc-8ba4-b424-c8916670b990\", \"6793a2a8-9be8-42ce-4fb1-9107e379dfde\"]}");
wr.flush();
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/reorder",
    dataType: "json",
    contentType: "application/json",
    type: "PUT",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    },
    data: JSON.stringify({"websiteIds":["8fc2ace2-75bc-8ba4-b424-c8916670b990", "6793a2a8-9be8-42ce-4fb1-9107e379dfde"]})
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.PutAsync("https://api-us.mouseflow.com/websites/reorder",
        new StringContent("{\"websiteIds\":[\"8fc2ace2-75bc-8ba4-b424-c8916670b990\", \"6793a2a8-9be8-42ce-4fb1-9107e379dfde\"]}"));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

If you want to re-order the list of websites, you simply send an ordered list of website-id's.

Note that the list must contain all website-id's.

PUT /websites/reorder

Website detail

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The above command returns JSON structured like this:

{
    "id": "8fc2ace2-75bc-8ba4-b424-c8916670b990",
    "name": "myshop.com",
    "created": "2013-08-18T19:37:07",
    "status": "Recording",
    "thumb": "18ad8222-ce62-43f0-8ba2-7db12146b0b4.png",
    "readOnly": true,
    "domains": [
        "myshop.com",
        "checkout.myshop.com"
    ],
    "recordingRate": 100,
    "alignment": "Center",
    "width": 984,
    "pageIdentifiers": [
        "query",
        "page_id"
    ],
    "encoding": "UTF-8",
    "anonymizeIps": false,
    "disableKeystrokes": false,
    "excludedIps": [
        "56.78.45.23",
        "120.340.210.*"
    ],
    "mergeUrls": [
        "/search/*"
    ],
    "cdnDomainName": "cdn.mouseflow.com",
    "isDemo": false
}

Get details about one website

GET /websites/{website-id}

Properties

Property Datatype Description
id String This the unique ID associated with the website
name String An alias or name you have given for your website (defaults to the website domain)
created DateTime The time the website was registered in Mouseflow
status String A string indicating whether the website is currently recording (values: NotInstalled, Recording, Stopped, Paused). Stopped means that you have manually stopped recording your users. Paused means that the website will start recording once you get credits in your account.
thumb String A partial URL for a thumbnail image generated from your website
readOnly bool A boolean value (true / false) that indicates whether you have readOnly or full access to the website
domains String[] A list of the domains you have whitelisted for this website.
recordingRate int The percentage of sessions you want to record. Set to 100 if you want to record all visitors. Setting it to 50 means that you record 50 percent of visitors, selected randomly.
alignment String The alignment of your website (Center, Left, Right, Flexible). This setting is used to make the mouse movement heatmaps more precise.
width String The width in pixels of you website. This setting is used to make the mouse movement heatmaps more precise.
pageIdentifiers String[] An alias or name you have given for your website (defaults to the website domain)
encoding String An alias or name you have given for your website (defaults to the website domain)
anonymizeIps bool A setting that controls whether to anonymize users' IP addresses by removing the last digits.
disableKeystrokes bool A setting that controls whether to completely disable keystroke logging
excludedIps String[] A list of IP addresses or patterns to exclude from recording. Use asterisk (*) at the end of the string as wildcard. Example: 100.100.*
mergeUrls String[] Used for merging several URLs into one in the heatmap lists. Use asterisk (*) as wildcard, or use regular expressions.
cdnDomainName String (internal) The domain used for hosting the recording script
isDemo bool (internal) Only set to true on the "Demo Website"

Create new website

Your website object should be structured like this. The domain field is mandatory.

{
    "domain": "myshop2.com",
    "recordingRate": 50,
    "anonymizeIps": false,
    "disableKeystrokes": false,
    "excludedIps": [
        "56.78.45.23",
        "120.340.210.*"
    ]
}
curl -X POST -u my@email.com:token1234 -d '{"domain": "myshop2.com", "recordingRate": 50}' https://api-us.mouseflow.com/websites
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new('/websites')
request.basic_auth('my@email.com', 'token1234')
request.body = '{"domain": "myshop2.com", "recordingRate": 50}'
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.post("https://api-us.mouseflow.com/websites", '{"domain": "myshop2.com", "recordingRate": 50}',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites");
    curl_setopt_array($curl, array(
            CURLOPT_POST => TRUE,
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234",
            CURLOPT_HTTPHEADER => array("Content-Type: application/json")
        ),
        CURLOPT_POSTFIELDS => '{"domain": "myshop2.com", "recordingRate": 50}'
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("POST");
OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
wr.write("{\"domain\": \"myshop2.com\", \"recordingRate\": 50}");

wr.flush();
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites",
    dataType: "json",
    contentType: "application/json",
    type: "POST",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    },
    data: JSON.stringify({"domain": "myshop2.com", "recordingRate": 50})
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.PostAsync("https://api-us.mouseflow.com/websites",
        new StringContent("{\"domain\": \"myshop2.com\", \"recordingRate\": 50}"));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The above command returns JSON structured like this:

{
    "id": "8fc2ace2-75bc-8ba4-b424-c8916670b990",
    "name": "myshop2.com",
    "created": "2013-08-18T19:37:07",
    "status": "NotInstalled",
    "readOnly": false,
    "domains": [
        "myshop2.com"
    ],
    "recordingRate": 50,
    "anonymizeIps": false,
    "disableKeystrokes": false,
    "excludedIps": [
        "56.78.45.23",
        "120.340.210.*"
    ]
}

POST /websites

Properties - Request

Property Datatype Description
domain String The domain you have whitelisted for this website.
recordingRate int The percentage of sessions you want to record. Set to 100 if you want to record all visitors. Setting it to 50 means that you record 50 percent of visitors, selected randomly.
anonymizeIps bool A setting that controls whether to anonymize users' IP addresses by removing the last digits.
disableKeystrokes bool A setting that controls whether to completely disable keystroke logging
excludedIps String[] A list of IP addresses or patterns to exclude from recording. Use asterisk (*) at the end of the string as wildcard. Example: 100.100.*

Properties - Response

Property Datatype Description
id String This the unique ID associated with the website
name String An alias or name you have given for your website (defaults to the website domain)
created DateTime The time the website was registered in Mouseflow
status String A string indicating whether the website is currently recording (values: NotInstalled, Recording, Stopped, Paused). Stopped means that you have manually stopped recording your users. Paused means that the website will start recording once you get credits in your account.
readOnly bool A boolean value (true / false) that indicates whether you have readOnly or full access to the website
domains String[] A list of the domains you have whitelisted for this website.
recordingRate int The fraction of sessions you want to record. Set to 100 if you want to record all visitors. Setting it to 50 means that you record 50 percent of visitors, selected randomly.
anonymizeIps bool A setting that controls whether to anonymize users' IP addresses by removing the last digits.
disableKeystrokes bool A setting that controls whether to completely disable keystroke logging
excludedIps String[] A list of IP addresses or patterns to exclude from recording. Use asterisk (*) at the end of the string as wildcard. Example: 100.100.*

Change recording status

curl -X PUT -u my@email.com:token1234 -H 'Content-Type: application/json' -d '{"recordingStatus":"Stopped"}' https://api-us.mouseflow.com/websites/{website-id}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Put.new('/websites/{website-id}')
request.basic_auth('my@email.com', 'token1234')
request.body = '{"recordingStatus":"Stopped"}'
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.put("https://api-us.mouseflow.com/websites/{website-id}", '{"recordingStatus":"Stopped"}',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}");
    curl_setopt_array($curl, array(
            CURLOPT_CUSTOMREQUEST => "PUT",
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234",
            CURLOPT_HTTPHEADER => array("Content-Type: application/json")
        ),
        CURLOPT_POSTFIELDS => '{"recordingStatus":"Stopped"}'
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("PUT");
OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
wr.write("{\"recordingStatus\":\"Stopped\"}");
wr.flush();
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}",
    dataType: "json",
    contentType: "application/json",
    type: "PUT",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    },
    data: JSON.stringify({"recordingStatus": "Stopped"})
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.PutAsync("https://api-us.mouseflow.com/websites/{website-id}",
        new StringContent("{\"recordingStatus\":\"Stopped\"}"));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

Stop recording visitors on a website

PUT /websites/{website-id} {"recordingStatus":"Stopped"}

curl -X PUT -u my@email.com:token1234 -H 'Content-Type: application/json' -d '{"recordingStatus":"Recording"}' https://api-us.mouseflow.com/websites/{website-id}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Put.new('/websites/{website-id}')
request.basic_auth('my@email.com', 'token1234')
request.body = '{"recordingStatus": "Recording"}'
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.put("https://api-us.mouseflow.com/websites/{website-id}", '{"recordingStatus":"Recording"}',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}");
    curl_setopt_array($curl, array(
            CURLOPT_CUSTOMREQUEST => "PUT",
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234",
            CURLOPT_HTTPHEADER => array("Content-Type: application/json")
        ),
        CURLOPT_POSTFIELDS => '{"recordingStatus":"Recording"}'
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("PUT");
OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
wr.write("{\"recordingStatus\":\"Recording\"}");
wr.flush();
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}",
    dataType: "json",
    contentType: "application/json",
    type: "PUT",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    },
    data: JSON.stringify({"recordingStatus":"Recording"})
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.PutAsync("https://api-us.mouseflow.com/websites/{website-id}",
        new StringContent("{\"recordingStatus\": \"Recording\"}"));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

Start recording visitors on a website

PUT /websites/{website-id} {"recordingStatus":"Recording"}

Update website details

curl -X PUT -u my@email.com:token1234 -H 'Content-Type: application/json' -d '{"name": "myshop2.com", "recordingRate": 50}' https://api-us.mouseflow.com/websites/{website-id}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Put.new('/websites/{website-id}')
request.basic_auth('my@email.com', 'token1234')
request.body = '{"name": "myshop2.com", "recordingRate": 50}'
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.put("https://api-us.mouseflow.com/websites/{website-id}", '{"recordingStatus":"Recording"}',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}");
    curl_setopt_array($curl, array(
            CURLOPT_CUSTOMREQUEST => "PUT",
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234",
            CURLOPT_HTTPHEADER => array("Content-Type: application/json")
        ),
        CURLOPT_POSTFIELDS => '{"name": "myshop2.com", "recordingRate": 50}'
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("PUT");
OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
wr.write("{\"name\": \"myshop2.com\", \"recordingRate\": 50}");

wr.flush();
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}",
    dataType: "json",
    contentType: "application/json",
    type: "PUT",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    },
    data: JSON.stringify({"name": "myshop2.com", "recordingRate": 50})
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.PutAsync("https://api-us.mouseflow.com/websites/{website-id}",
        new StringContent("{\"name\": \"myshop2.com\", \"recordingRate\": 50}"));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

Your website object should be structured like this. No fields are mandatory. Use only the ones you want to update.

{
    "name": "myshop2.com",
    "recordingRate": 50,
    "alignment": "Center",
    "width": 984,
    "pageIdentifiers": [
        "query",
        "page_id"
    ],
    "encoding": "UTF-8",
    "anonymizeIps": false,
    "disableKeystrokes": false,
    "excludedIps": [
        "56.78.45.23",
        "120.340.210.*"
    ],
    "mergeUrls": [
        "/search/*"
    ]
}

PUT /websites/{website-id}

Properties

Property Datatype Description
name String An alias or name you have given for your website (defaults to the website domain)
status String A string indicating whether the website is currently recording (values: NotInstalled, Recording, Stopped, Paused). Stopped means that you have manually stopped recording your users. Paused means that the website will start recording once you get credits in your account.
domains String[] A list of the domains you have whitelisted for this website.
recordingRate int The percentage of sessions you want to record. Set to 1 if you want to record all visitors. Setting it to 50 means that you record 50 percent of all visitors, selected randomly.
alignment String The alignment of your website (Center, Left, Right, Flexible). This setting is used to make the mouse movement heatmaps more precise.
width String The width in pixels of you website. This setting is used to make the mouse movement heatmaps more precise.
pageIdentifiers String[] An alias or name you have given for your website (defaults to the website domain)
encoding String An alias or name you have given for your website (defaults to the website domain)
anonymizeIps bool A setting that controls whether to anonymize users' IP addresses by removing the last digits.
disableKeystrokes bool A setting that controls whether to completely disable keystroke logging
excludedIps String[] A list of IP addresses or patterns to exclude from recording. Use asterisk (*) at the end of the string as wildcard. Example: 100.100.*
mergeUrls String[] Used for merging several URLs into one in the heatmap lists. Use asterisk (*) as wildcard, or use regular expressions.

Recordings

Recording list

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/recordings
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}/recordings')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}/recordings",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/recordings");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/recordings");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/recordings",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}/recordings");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The above command returns JSON structured like this:

{
    "recordings": [
        {
            "id": "0953400cc896bc93ccf0013b839e7618",
            "token": "oyINpOigE06kH2R-7LIw4Q",
            "created": "2015-09-23T09:46:08.5452158+02:00",
            "lastActivity": "2015-09-23T09:48:59.1706692+02:00",
            "duration": 158952,
            "pages": 6,
            "country": "de",
            "city": "Braunschweig",
            "isp": "Business Communication Company GmbH",
            "ip": "213.252.153.###",
            "lang": "de-DE",
            "userAgent": "Mozilla/5.0 (Windows NT 6.1; Trident/7.0; rv:11.0) like Gecko",
            "browser": "IE",
            "browserVersion": "11.0",
            "os": "Windows",
            "osVersion": "7",
            "device": "Desktop",
            "referrer": "http://www.googleadservices.com/pagead/aclk?sa=L&ai=C4PU4dslgCVoazd87gbr2dLvgdBMXr-cIH5e-92cUB8db-9VwIABABYJX6l4KsB6ABk6HSzwPIAQGpAuAxl68mqrI-qgQhT9A50Xst7h6phswpdV3K-UzZb5IFcZkNnioAiKNcEKgDugUTCI2",
            "referrerType": "Search",
            "screenRes": "1920x1200",
            "entry": "https://shop.myshop.com/landing?ecid=sea_google&gclid=CM-VxfLUjMgCFSLnwgod-rgHiA",
            "entryPage": "shop.myshop.de/landing",
            "tags": [
                "form-interact",
                "submit"
            ],
            "variables": [],
            "watched": false,
            "starred": false,
            "lng": 10.4979,
            "lat": 52.3022,
            "visitorId": "7359eec3c0b8b4bb3c2837b1f09fe80d",
            "visitorName": "John Doe",
            "playbackUrl": "/websites/47ed74ad-f36e-4ba0-be1b-ca9d79b69688/recordings/0953400cc896bc93ccf0013b839e7618/play"
        },
        {
            "id": "c6952ffd03588d04b0a39ed5ae1e3096",
            "created": "2015-09-23T09:47:52.0699665+02:00",
            "lastActivity": "2015-09-23T09:48:59.1706692+02:00",
            "duration": 70043,
            "pages": 1,
            "country": "de",
            "city": "Frankfurt Am Main",
            "isp": "Deutsche Telekom AG",
            "ip": "79.255.13.###",
            "lang": "de-DE",
            "userAgent": "Mozilla/5.0 (Linux; Android 4.4.4; SM-T533 Build/KTU84P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.94 Safari/537.36",
            "browser": "Chrome",
            "browserVersion": "45.0.2454.94",
            "os": "Android",
            "osVersion": "4.4 KitKat",
            "device": "Desktop",
            "referrer": "https://www.google.de/",
            "referrerType": "Search",
            "screenRes": "1280x800",
            "entry": "https://www.myshop.de/offers/?marketSearch=1",
            "entryPage": "/offers",
            "tags": [],
            "variables": [],
            "watched": false,
            "starred": false,
            "lng": 8.6809,
            "lat": 50.1223,
            "visitorId": "a1dd2422ff2483682ce1f2d5a1de8432",
            "playbackUrl": "/websites/47ed74ad-f36e-4ba0-be1b-ca9d79b69688/recordings/c6952ffd03588d04b0a39ed5ae1e3096/play"
        }
    ],
    "chart": {
        "2015-08-30": 13286,
        "2015-08-31": 17184,
        "2015-09-01": 23102
    },
    "count": 373709
}

Get the latest recordings in the specified website, with the most recent ones first.

GET /websites/{website-id}/recordings

Properties

Property Datatype Description
id String This the unique ID associated with the recording
token String The token for the recording, if it is shared
created DateTime The time the recording started
lastActivity DateTime The time of the last recorded activity on the recording
duration int The total duration of the recording, in ms.
pages int The number of pageviews in the recording
country String The 2-char country code of the origin country (ISO 3166-1 alpha-2)
city String The origin city (based on the IP address)
isp String The user's ISP or Organization (registered with the IP address)
ip String The user's IP address (may be anonymized - last digits masked)
lang String The user's language, according to the browser (IETF language tag)
userAgent String The user-agent string of the user's browser
browser String The browser family (Chrome, Firefox, Safari, IE, Opera, ...)
browserVersion String The browser version
os String The user's operating system family (Windows, Mac OS, Android, iOS, Linux, etc.)
osVersion String The version of the operating system
device String The device type (Desktop, Tablet, Phone)
referrer String The URL of the web page that referred the user
referrerType String The referrer type (Search, Social, Email, Link, Direct). Direct means that there was no referrer. Link is any referring link that is not recognized as being a search engine, a social media site or an email link.
screenRes String The URL of the web page that referred the user
entry String The URL of the entry page
entryPage String The normalized path of the entry page
tags String[] A list of tags used in this recording (See Tags section)
variables String[] A list of key-value pairs (ex: cart-value=345) associated with the recording (See Variables section)
watched bool A boolean value indicating whether the current user has watched the recording
starred bool A boolean value indicating whether the current user has starred the recording
lng double The longitude of the user, according to the IP address
lat double The latitude of the user, according to the IP address
visitorId String The unique ID associated with the visitor
visitorName String A visitor name you have associated with the visitor (can be non-existing)
playbackUrl String The path of the playback URL
chart Date / int list A chart showing the number of recordings per day
count int The total number of recordings in the date range with the current filters, independent of the limit of the list

Optional arguments (appended to the querystring)

Argument Datatype Description
limit int The number of items to retrieve (default: 50)

For a full list of filtering options, please see the Filters section.

Recording detail

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}/recordings/{recording-id}')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The above command returns JSON structured like this:

{
    "id": "833bcb110b688e8e182731fadc11430d",
    "token": "oyINpOigE06kH2R-7LIw4Q",
    "created": "2015-10-06T11:11:14.2556125+02:00",
    "lastActivity": "2015-10-06T11:11:41.7782514+02:00",
    "pageViews": [
        {
            "id": "10063571ed03c1ff56c6a2735749a40fb075fd68",
            "startTime": "2015-10-06T11:11:14.2556125+02:00",
            "endTime": "2015-10-06T11:11:41.7782514+02:00",
            "title": "My home page",
            "uri": "https://mywebsite.com/",
            "websitePage": "/",
            "visitTime": 29511,
            "engagementTime": 19119,
            "scroll": 37,
            "tags": []
        },
        {
            "id": "21563521ab42bff2566a2735749b73dc591af51",
            "startTime": "2015-10-06T11:12:05.2452125+02:00",
            "endTime": "2015-10-06T11:13:45.2584314+02:00",
            "title": "Our products",
            "uri": "https://mywebsite.com/products",
            "websitePage": "/products",
            "visitTime": 67424,
            "engagementTime": 35431,
            "scroll": 89,
            "tags": [
                "add-to-cart",
                "form-interact"
            ]
        }
    ],
    "duration": 29511,
    "country": "tn",
    "region": "",
    "city": "",
    "isp": "Tunet",
    "ip": "43.248.211.212",
    "lang": "fr",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2522.0 Safari/537.36",
    "browser": "Chrome",
    "browserVersion": "47.0.2522.0",
    "screenRes": "1920x1080",
    "os": "Windows",
    "osVersion": "10",
    "device": "Desktop",
    "referrerType": "Search",
    "referrer": "http://www.google.fr",
    "tags": [
        "form-interact",
        "submit"
    ],
    "variables": [
        "plan=upgraded",
        "cart-value=345"
    ],
    "watched": false,
    "starred": false,
    "lng": 10.4979,
    "lat": 52.3022,
    "visitorId": "7359eec3c0b8b4bb3c2837b1f09fe80d",
    "visitorName": "John Doe"
}

Get details of a recording, including each recorded pageviews

GET /websites/{website-id}/recordings/{recording-id}

Properties

Property Datatype Description
id String This the unique ID associated with the recording
token String The token for the recording, if it is shared
created DateTime The time the recording started
lastActivity DateTime The time of the last recorded activity on the recording
pageViews list See table below
duration int The total duration of the recording, in ms.
pages int The number of pageviews in the recording
country String The 2-char country code of the origin country (ISO 3166-1 alpha-2)
city String The origin city (based on the IP address)
isp String The user's ISP or Organization (registered with the IP address)
ip String The user's IP address (may be anonymized - last digits masked)
language String The user's language, according to the browser (IETF language tag)
userAgent String The user-agent string of the user's browser
browser String The browser family (Chrome, Firefox, Safari, IE, Opera, ...)
browserVersion String The browser version
screenRes String The URL of the web page that referred the user
os String The user's operating system family (Windows, Mac OS, Android, iOS, Linux, etc.)
osVersion String The version of the operating system
device String The device type (Desktop, Tablet, Phone)
referrer String The URL of the web page that referred the user
tags String[] A list of tags used in this recording (See Tags section)
variables String[] A list of key-value pairs (ex: cart-value=345) associated with the recording (See Variables section)
starred bool A boolean value indicating whether the current user has starred the recording
lng double The longitude of the user, according to the IP address
lat double The latitude of the user, according to the IP address
visitorId String The unique ID associated with the visitor
visitorName String A visitor name you have associated with the visitor (can be non-existing)

Properties - pageViews

Property Datatype Description
id String This the unique ID associated with the recording
startTime DateTime The time the recording started
endTime DateTime The time of the last recorded activity on the recording
title String The 2-char country code of the origin country (ISO 3166-1 alpha-2)
uri String The origin city (based on the IP address)
websitePage String The user's ISP or Organization (registered with the IP address)
visitTime int The total duration of the recording, in ms.
engagementTime int The total duration of the recording, in ms.
scroll int The total duration of the recording, in ms.
tags String[] A list of tags used in this recording (See Tags section)

Star

curl -X POST -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/star
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new('/websites/{website-id}/recordings/{recording-id}/star')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.post("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/star", '',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/star");
    curl_setopt_array($curl, array(
            CURLOPT_POST => TRUE,
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234"
        )
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/star");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("POST");
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/star",
    dataType: "json",
    type: "POST",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.PostAsync("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/star",
        new StringContent(""));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

Star a recording

POST /websites/{website-id}/recordings/{recording-id}/star

The above code stars a recording. The below one unstars a recording.

curl -X DELETE -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/star
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Delete.new('/websites/{website-id}/recordings/{recording-id}/star')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.delete("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/star", '',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/star");
    curl_setopt_array($curl, array(
            CURLOPT_CUSTOMREQUEST => "DELETE",
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234"
        )
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/star");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("DELETE");
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/star",
    dataType: "json",
    type: "DELETE",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.DeleteAsync("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/star",
        new StringContent(""));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

Unstar a recording

DELETE /websites/{website-id}/recordings/{recording-id}/star

Tags

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/recordings/tags
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}/recordings/tags')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}/recordings/tags",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/recordings/tags");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/recordings/tags");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/recordings/tags",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}/recordings/tags");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The above command returns JSON structured like this:

[
    "form-interact",
    "submit",
    "my-tag",
    "drop-off",
    "interesting",
    "erratic"
]

Get the list of tags used on a website

GET /websites/{website-id}/recordings/tags

Properties

The result is a string array containing all the used tags.

Arguments

Argument Datatype Description
limit int The maximum number of variables in the list

Add a tag to a recording

curl -X POST -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/tag?tag={my-tag}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new('/websites/{website-id}/recordings/{recording-id}/tag?tag={my-tag}')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.post("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/tag?tag={my-tag}", '',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/tag?tag={my-tag}");
    curl_setopt_array($curl, array(
            CURLOPT_POST => TRUE,
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234"
        )
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/tag?tag={my-tag}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("POST");
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/tag?tag={my-tag}",
    dataType: "json",
    type: "POST",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.PostAsync("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/tag?tag={my-tag}",
        new StringContent(""));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

POST /websites/{website-id}/recordings/{recording-id}/tag?tag={my-tag}

Remove a tag from a recording

curl -X DELETE -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/tag?tag={my-tag}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Delete.new('/websites/{website-id}/recordings/{recording-id}/tag?tag={my-tag}')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.delete("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/tag?tag={my-tag}", '',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/tag?tag={my-tag}");
    curl_setopt_array($curl, array(
            CURLOPT_CUSTOMREQUEST => "DELETE",
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234"
        )
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/tag?tag={my-tag}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("DELETE");
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/tag?tag={my-tag}",
    dataType: "json",
    type: "DELETE",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.DeleteAsync("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/tag?tag={my-tag}",
        new StringContent(""));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

DELETE /websites/{website-id}/recordings/{recording-id}/tag?tag={my-tag}

Variables

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/recordings/variables
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}/recordings/variables')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}/recordings/variables",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/recordings/variables");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/recordings/variables");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/recordings/variables",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}/recordings/variables");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The above command returns JSON structured like this:

[
    "cart-id",
    "cart-value",
    "account",
    "plan"
]

Get the list of variable keys used on a website

GET /websites/{website-id}/recordings/variables

Argument Datatype Description
limit int The maximum number of variable keys in the list
curl -X PUT -u my@email.com:token1234 -H 'Content-Type: application/json' -d '{"cart-id": "df342", "cart-value": 43}' https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/variables
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Put.new('/websites/{website-id}/recordings/{recording-id}/variables')
request.basic_auth('my@email.com', 'token1234')
request.body = '{"cart-id": "df342", "cart-value": 43}'
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.put("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/variables", '{"cart-id": "df342", "cart-value": 43}',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/variables");
    curl_setopt_array($curl, array(
            CURLOPT_CUSTOMREQUEST => "PUT",
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234",
            CURLOPT_HTTPHEADER => array("Content-Type: application/json")
        ),
        CURLOPT_POSTFIELDS => '{"cart-id": "df342", "cart-value": 43}'
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/variables");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("PUT");
OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
wr.write("{\"cart-id\": \"df342\", \"cart-value\": 43}");
wr.flush();
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/variables",
    dataType: "json",
    contentType: "application/json",
    type: "PUT",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    },
    data: JSON.stringify({"cart-id": "df342", "cart-value": 43})
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.PutAsync("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/variables",
        new StringContent("{\"cart-id\": \"df342\", \"cart-value\": 43}"));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

Edit the list of custom variables on one recording

PUT /websites/{website-id}/recordings/{recording-id}/variables

{ "cart-id": "dbn435m2ba", "cart-value": "456" }

Remove custom variables

To remove (or reset) custom variables, simply set each one to an empty string.

PUT /websites/{website-id}/recordings/{recording-id}/variables

{ "cart-id": "", "cart-value": "" }

Sharing

curl -X POST -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/share
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new('/websites/{website-id}/recordings/{recording-id}/share')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.post("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/share", '',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/share");
    curl_setopt_array($curl, array(
            CURLOPT_POST => TRUE,
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234"
        )
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/share");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("POST");
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/share",
    dataType: "json",
    type: "POST",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.PostAsync("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/share",
        new StringContent(""));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The above command returns the sharing token as a string value:

"HQ7068MglEuUZlA6WOSF-w"

The above code shares a recording. The below one stops sharing a recording.

curl -X DELETE -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/share
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Delete.new('/websites/{website-id}/recordings/{recording-id}/share')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.delete("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/share", '',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/share");
    curl_setopt_array($curl, array(
            CURLOPT_CUSTOMREQUEST => "DELETE",
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234"
        )
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/share");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("DELETE");
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/share",
    dataType: "json",
    type: "DELETE",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.DeleteAsync("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/share",
        new StringContent(""));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

Start sharing a recording

POST /websites/{website-id}/recordings/{recording-id}/share

Stop sharing a recording

DELETE /websites/{website-id}/recordings/{recording-id}/share

Watched

curl -X POST -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/watched
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new('/websites/{website-id}/recordings/{recording-id}/watched')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.post("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/watched", '',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/watched");
    curl_setopt_array($curl, array(
            CURLOPT_POST => TRUE,
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234"
        )
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/watched");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("POST");
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/watched",
    dataType: "json",
    type: "POST",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.PostAsync("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/watched",
        new StringContent(""));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The above code marks a recording as watched. The below one marks it as unwatched.

curl -X DELETE -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/watched
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Delete.new('/websites/{website-id}/recordings/{recording-id}/watched')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.delete("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/watched", '',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/watched");
    curl_setopt_array($curl, array(
            CURLOPT_CUSTOMREQUEST => "DELETE",
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234"
        )
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/watched");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("DELETE");
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/watched",
    dataType: "json",
    type: "DELETE",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.DeleteAsync("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}/watched",
        new StringContent(""));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

Mark a recording as watched

POST /websites/{website-id}/recordings/{recording-id}/watched

Mark a recording as unwatched

DELETE /websites/{website-id}/recordings/{recording-id}/watched

Delete

curl -X DELETE -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Delete.new('/websites/{website-id}/recordings/{recording-id}')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.delete("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}", '',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}");
    curl_setopt_array($curl, array(
            CURLOPT_CUSTOMREQUEST => "DELETE",
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234"
        )
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("DELETE");
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}",
    dataType: "json",
    type: "DELETE",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.DeleteAsync("https://api-us.mouseflow.com/websites/{website-id}/recordings/{recording-id}",
        new StringContent(""));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

Delete a recording

DELETE /websites/{website-id}/recordings/{recording-id}

Heatmaps

Heatmap page list

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/pagelist
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}/pagelist')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}/pagelist",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/pagelist");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/pagelist");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/pagelist",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}/pagelist");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The above command returns JSON structured like this:

{
    "pages": [
        {
            "displayUrl": "/",
            "uri": "https://myshop.com/tour",
            "token": "kDMH2ljDlkmKpzoCXuF7eA",
            "title": "MyShop - Tour",
            "views": 23410,
            "visitTime": 70593,
            "engagementTime": 10754,
            "clicks": 21299,
            "renderTime": 3526,
            "scroll": 39,
            "fold": 0,
            "height": 2444,
            "size": 19607
        },
        {
            "displayUrl": "/jobs/marketing-intern",
            "uri": "https://myshop.com/jobs/marketing-intern/",
            "title": "Marketing Intern - MyShop",
            "views": 13,
            "visitTime": 59073,
            "engagementTime": 19085,
            "clicks": 15,
            "renderTime": 1921,
            "scroll": 65,
            "fold": 0,
            "height": 1387,
            "size": 8629
        }
    ],
    "count": 186
}

Get the list of pages, including visitor statistics

GET /websites/{website-id}/pagelist

Arguments

Argument Datatype Description
limit int The maximum number of pages in the list (default: 50)

For a full list of filtering options, please see the Filters section.

Properties

Property Datatype Description
displayUrl string The path of the page used in the heatmap list
uri string The full URI of the page
token string The token for the heatmap, if it is shared
title int The title of the page
views int Number of views for the page
visitTime int Average pageview duration for the page
engagementTime int Average engagement time (duration minus inactivity) for the page
clicks int Number of clicks on the page
renderTime int Average time it has taken users to render the page
scroll int Average scroll reach, in percent
fold int The average height in pixels of the users' browser windows. Also known as the fold.
height int The average height in pixels of the rendered page for users
size int The average HTML size in bytes of the rendered page for users

Heatmap page details

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/pagelist?url={url}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}/pagelist?url={url}')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}/pagelist?url={url}",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/pagelist?url={url}");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/pagelist?url={url}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/pagelist?url={url}",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}/pagelist?url={url}");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The above command returns JSON structured like this:

{
    "uri": "https://myshop.com/jobs",
    "token": "kDMH2ljDlkmKpzoCXuF7eA",
    "title": "Positions available at MyShop",
    "views": 23410,
    "visitTime": 70593,
    "engagementTime": 10754,
    "clicks": 21299,
    "renderTime": 3526,
    "scroll": 39,
    "fold": 819,
    "height": 2444,
    "size": 19607
}

GET /websites/{website-id}/pagelist?url={url}

Required arguments (appended to the querystring)

Argument Datatype Description
url string The display url for the wanted page

For a full list of filtering options, please see the Filters section.

Properties

Properties Datatype Description
displayUrl string The path of the page used in the heatmap list
uri string The full URI of the page
token string The token for the heatmap, if it is shared
title int The title of the page
views int Number of views for the page
visitTime int Average pageview duration for the page
engagementTime int Average engagement time (duration minus inactivity) for the page
clicks int Number of clicks on the page
renderTime int Average time it has taken users to render the page
scroll int Average scroll reach, in percent
fold int The average height in pixels of the users' browser windows. Also known as the fold.
height int The average height in pixels of the rendered page for users
size int The average HTML size in bytes of the rendered page for users

Page url list

Use this to only get the list of displayUrls of the heatmap pages.

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/pagelist/urls
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}/pagelist/urls')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}/pagelist/urls",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/pagelist/urls");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/pagelist/urls");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/pagelist/urls",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}/pagelist/urls");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The above command returns JSON structured like this:

{
    "urls": [
        "/",
        "/products",
        "/demo",
        "/plans",
        "/products/shoes",
        "/sign-up",
        "/products/shirts",
        "/jobs/marketing-intern"
    ],
    "count": 185
}

Get the list of page urls

GET /websites/{website-id}/pagelist/urls

Arguments

Argument Datatype Description
limit int The maximum number of urls in the list (default: 50)
search String Search string (searching within the displayUrls).

No other filters can be used in the simple page list.

Properties

Property Datatype Description
urls string[] List of displayUrls
count int Number of urls in total

Sharing

curl -X POST -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/heatmaps/share?url={url}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new('/websites/{website-id}/heatmaps/share?url={url}')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.post("https://api-us.mouseflow.com/websites/{website-id}/heatmaps/share?url={url}", '',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/heatmaps/share?url={url}");
    curl_setopt_array($curl, array(
            CURLOPT_POST => TRUE,
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234"
        )
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/heatmaps/share?url={url}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("POST");
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/heatmaps/share?url={url}",
    dataType: "json",
    type: "POST",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.PostAsync("https://api-us.mouseflow.com/websites/{website-id}/heatmaps/share?url={url}",
        new StringContent(""));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The above code shares a heatmap. The below one stops sharing a heatmap.

curl -X DELETE -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/heatmaps/share?url={url}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Delete.new('/websites/{website-id}/heatmaps/share?url={url}')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.delete("https://api-us.mouseflow.com/websites/{website-id}/heatmaps/share?url={url}", '',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/heatmaps/share?url={url}");
    curl_setopt_array($curl, array(
            CURLOPT_CUSTOMREQUEST => "DELETE",
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234"
        )
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/heatmaps/share?url={url}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("DELETE");
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/heatmaps/share?url={url}",
    dataType: "json",
    type: "DELETE",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.DeleteAsync("https://api-us.mouseflow.com/websites/{website-id}/heatmaps/share?url={url}",
        new StringContent(""));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

Start sharing a heatmap

POST /websites/{website-id}/heatmaps/share?url={url}

Stop sharing a heatmap

DELETE /websites/{website-id}/heatmaps/share?url={url}

Funnels

Funnel list

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/funnels
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}/funnels')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}/funnels",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/funnels");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/funnels");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/funnels",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}/funnels");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The above command returns JSON structured like this:

[
    {
        "funnelId": "kvnbQCMbpUyDwLArFDOuXw",
        "name": "My Funnel",
        "steps": [
            {
                "name": "First step",
                "url": "/",
                "count": 500
            },
            {
                "name": "Second step",
                "url": "/second",
                "count": 250
            }
        ]
    },
    {
        "funnelId": "CDT6DWNrhESsIfFiDTa5cA",
        "name": "My Other Funnel",
        "steps": [
            {
                "name": "First step",
                "url": "/",
                "count": 500
            },
            {
                "name": "Second step",
                "url": "/second",
                "count": 250
            }
        ]
    }
]

Get the list of funnels

GET /websites/{website-id}/funnels

Properties

Property Datatype Description
funnelId String This the unique ID associated with the funnel
name String An alias or name you have given for your funnel
steps Object[] The list of steps in your funnel
steps.name String An alias or name you have given this funnel step
steps.url String The URL of the page for this funnel step
steps.count int The number of visitors on this funnel step

Funnel report

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/funnels/{funnel-id}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}/funnels/{funnel-id}')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}/funnels/{funnel-id}",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/funnels/{funnel-id}");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/funnels/{funnel-id}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/funnels/{funnel-id}",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}/funnels/{funnel-id}");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The above command returns JSON structured like this:

{
    "funnelId": "kvnbQCMbpUyDwLArFDOuXw",
    "name": "My Funnel",
    "steps": [
        {
            "name": "First step",
            "url": "/",
            "count": 500
        },
        {
            "name": "Second step",
            "url": "/second",
            "count": 250
        }
    ]
}

Get the full funnel report

GET /websites/{website-id}/funnels/{funnel-id}

Properties

Property Datatype Description
funnelId String This the unique ID associated with the funnel
name String An alias or name you have given for your funnel
steps Object[] The list of steps in your funnel
steps.name String An alias or name you have given this funnel step
steps.url String The URL of the page for this funnel step
steps.count int The number of visitors on this funnel step

Create a funnel

curl -X POST -u my@email.com:token1234 -d '{"name":"My Funnel","steps":[{"name":"First step","url":"/"},{"name":"Second step","url":"/second"}]}' https://api-us.mouseflow.com/websites/{website-id}/funnels
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new('/websites/{website-id}/funnels')
request.basic_auth('my@email.com', 'token1234')
request.body = '{"name":"My Funnel","steps":[{"name":"First step","url":"/"},{"name":"Second step","url":"/second"}]}'
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.post("https://api-us.mouseflow.com/websites/{website-id}/funnels", '{"name":"My Funnel","steps":[{"name":"First step","url":"/"},{"name":"Second step","url":"/second"}]}',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/funnels");
    curl_setopt_array($curl, array(
            CURLOPT_POST => TRUE,
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234",
            CURLOPT_HTTPHEADER => array("Content-Type: application/json")
        ),
        CURLOPT_POSTFIELDS => '{"name":"My Funnel","steps":[{"name":"First step","url":"/"},{"name":"Second step","url":"/second"}]}'
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/funnels");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("POST");
OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
wr.write("{\"name\":\"My Funnel\",\"steps\":[{\"name\":\"First step\",\"url\":\"/\"},{\"name\":\"Second step\",\"url\":\"/second\"}]}");
wr.flush();
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/funnels",
    dataType: "json",
    contentType: "application/json",
    type: "POST",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    },
    data: JSON.stringify({"name":"My Funnel","steps":[{"name":"First step","url":"/"},{"name":"Second step","url":"/second"}]})
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.PostAsync("https://api-us.mouseflow.com/websites/{website-id}/funnels",
        new StringContent("{\"name\":\"My Funnel\",\"steps\":[{\"name\":\"First step\",\"url\":\"/\"},{\"name\":\"Second step\",\"url\":\"/second\"}]}"));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

Your funnel object should be structured like this. Name and URL fields are mandatory.

{
    "name": "My Funnel",
    "steps": [
        {
            "name": "First step",
            "url": "/"
        },
        {
            "name": "Second step",
            "url": "/second"
        }
    ]
}

The above command returns JSON structured like this:

{
    "funnelId": "kvnbQCMbpUyDwLArFDOuXw",
    "name": "My Funnel",
    "steps": [
        {
            "name": "First step",
            "url": "/",
            "count": 0
        },
        {
            "name": "Second step",
            "url": "/second",
            "count": 0
        }
    ]
}

POST /websites/{website-id}/funnels

Properties

Property Datatype Description
name String An alias or name you have given for your funnel
steps Object[] The list of steps in your funnel
steps.name String An alias or name you have given this funnel step
steps.url String The URL of the page for this funnel step
steps.count int The number of visitors on this funnel step

Edit a funnel

curl -X PUT -u my@email.com:token1234 -H 'Content-Type: application/json' -d '{"name":"My Funnel","steps":[{"name":"First step","url":"/"},{"name":"Second step","url":"/second"}]}' https://api-us.mouseflow.com/websites/{website-id}/funnels/{funnel-id}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Put.new('/websites/{website-id}/funnels/{funnel-id}')
request.basic_auth('my@email.com', 'token1234')
request.body = '{"name":"My Funnel","steps":[{"name":"First step","url":"/"},{"name":"Second step","url":"/second"}]}'
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.put("https://api-us.mouseflow.com/websites/{website-id}/funnels/{funnel-id}", '{"name":"My Funnel","steps":[{"name":"First step","url":"/"},{"name":"Second step","url":"/second"}]}',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/funnels/{funnel-id}");
    curl_setopt_array($curl, array(
            CURLOPT_CUSTOMREQUEST => "PUT",
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234",
            CURLOPT_HTTPHEADER => array("Content-Type: application/json")
        ),
        CURLOPT_POSTFIELDS => '{"name":"My Funnel","steps":[{"name":"First step","url":"/"},{"name":"Second step","url":"/second"}]}'
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/funnels/{funnel-id}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("PUT");
OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
wr.write("{\"name\":\"My Funnel\",\"steps\":[{\"name\":\"First step\",\"url\":\"/\"},{\"name\":\"Second step\",\"url\":\"/second\"}]}");
wr.flush();
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/funnels/{funnel-id}",
    dataType: "json",
    contentType: "application/json",
    type: "PUT",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    },
    data: JSON.stringify({"name":"My Funnel","steps":[{"name":"First step","url":"/"},{"name":"Second step","url":"/second"}]})
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.PutAsync("https://api-us.mouseflow.com/websites/{website-id}/funnels/{funnel-id}",
        new StringContent("{\"name\":\"My Funnel\",\"steps\":[{\"name\":\"First step\",\"url\":\"/\"},{\"name\":\"Second step\",\"url\":\"/second\"}]}"));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

Your funnel object should be structured like this. No fields are mandatory. Use only the ones you want to edit.

{
    "name": "My Funnel",
    "steps": [
        {
            "name": "First step",
            "url": "/"
        },
        {
            "name": "Second step",
            "url": "/second"
        }
    ]
}

PUT /websites/{website-id}/funnels/{funnel-id}

Properties

Property Datatype Description
name String An alias or name you have given for your funnel
steps Object[] The list of steps in your funnel
steps.name String An alias or name you have given this funnel step
steps.url String The URL of the page for this funnel step
steps.count int The number of visitors on this funnel step

Delete a funnel

curl -X DELETE -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/funnels/{funnel-id}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Delete.new('/websites/{website-id}/funnels/{funnel-id}')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.delete("https://api-us.mouseflow.com/websites/{website-id}/funnels/{funnel-id}", '',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/funnels/{funnel-id}");
    curl_setopt_array($curl, array(
            CURLOPT_CUSTOMREQUEST => "DELETE",
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234"
        )
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/funnels/{funnel-id}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("DELETE");
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/funnels/{funnel-id}",
    dataType: "json",
    type: "DELETE",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.DeleteAsync("https://api-us.mouseflow.com/websites/{website-id}/funnels/{funnel-id}",
        new StringContent(""));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

DELETE /websites/{website-id}/funnels/{funnel-id}

Forms

Form list

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/forms
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}/forms')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}/forms",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/forms");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/forms");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/forms",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}/forms");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The above command returns JSON structured like this:

[
    {
        "formId": "Ndecf26mBkW_ygVu1xyTFw",
        "url": "/register",
        "target": "#register-new-user",
        "alias": "User Registration Form",
        "fields": [
            {
                "target": "first-name",
                "alias": "First Name Input",
                "type": "text",
                "interactions": 14792
            },
            {
                "target": "last-name",
                "alias": "Last Name Input",
                "type": "text",
                "interactions": 14629
            },
            {
                "target": "gender",
                "alias": "Gender Radiobuttons",
                "type": "radio",
                "interactions": 8310
            },
            {
                "target": "terms",
                "alias": "Terms Checkbox",
                "type": "checkbox",
                "interactions": 13754
            }
        ],
        "visits": 17887,
        "interactions": 15544,
        "submits": 12895,
        "success": 6722
    },
    {
        "formId": "W49KLFt2S0SbSyzk9ch4WA",
        "url": "/demo",
        "target": "#test-form",
        "alias": "Test Form",
        "fields": [
            {
                "target": "email",
                "alias": "E-mail Input",
                "type": "email",
                "interactions": 2533
            },
            {
                "target": "question",
                "alias": "Question Select Box",
                "type": "select",
                "interactions": 2186
            }
        ],
        "visits": 7651,
        "interactions": 4481,
        "submits": 2508,
        "success": 27
    }
]

Get the list of forms

GET /websites/{website-id}/forms

Optional arguments (appended to the querystring)

For a full list of filtering options, please see the Filters section.

Properties - Response

Property Datatype Description
formId String This the unique ID associated with the form
url String The URL where the form is located
target String An ID or selector for the form
alias String A recognizable name you have given your form
fields Object[] The list of fields in your form report
fields.target String A name, ID or selector for the field
fields.alias String A recognizable name you have given this field
fields.type String The HTML or input type of this field
fields.interactions int The number of interactions with this field
visits int The number of visitors to the page of the form
interactions int The number of visitors who interacted with the form
submits int The number of submit attempts of the form
success int The number of successful submits of the form

Form report

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/forms/{form-id}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}/forms/{form-id}')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}/forms/{form-id}",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/forms/{form-id}");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/forms/{form-id}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/forms/{form-id}",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}/forms/{form-id}");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The above command returns JSON structured like this:

{
    "formId": "Ndecf26mBkW_ygVu1xyTFw",
    "url": "/register",
    "target": "#register-new-user",
    "alias": "User Registration Form",
    "fields": [
        {
            "target": "first-name",
            "alias": "First Name Input",
            "type": "text",
            "interactions": 14792,
            "startTime": 35,
            "duration": 18739,
            "refills": 577,
            "blanks": 1,
            "dropped": 15
        },
        {
            "target": "last-name",
            "alias": "Last Name Input",
            "type": "text",
            "interactions": 14629,
            "startTime": 21960,
            "duration": 10227,
            "refills": 1310,
            "blanks": 1,
            "dropped": 2279
        },
        {
            "target": "gender",
            "alias": "Gender Radiobuttons",
            "type": "radio",
            "interactions": 8310,
            "startTime": 28217,
            "duration": 2435,
            "refills": 64,
            "blanks": 3216,
            "dropped": 355
        },
        {
            "target": "terms",
            "alias": "Terms Checkbox",
            "type": "checkbox",
            "interactions": 13754,
            "startTime": 30482,
            "duration": 3510,
            "refills": 24,
            "blanks": 107,
            "dropped": 406
        }
    ],
    "visits": 17887,
    "interactions": 15544,
    "submits": 12895,
    "success": 6722
}

Get the full form report

GET /websites/{website-id}/forms/{form-id}

Optional arguments (appended to the querystring)

For a full list of filtering options, please see the Filters section.

Properties - Response

Property Datatype Description
formId String This the unique ID associated with the form
url String The URL where the form is located
target String An ID or selector for the form
alias String A recognizable name you have given your form
fields Object[] The list of fields in your form report
fields.target String A name, ID or selector for the field
fields.alias String A recognizable name you have given this field
fields.type String The HTML or input type of this field
fields.interactions int The number of interactions with this field
fields.startTime int Average interaction start time in milliseconds relative to pageview start time
fields.duration int Average time spent on this field
fields.refills int The number of times this field has been refilled
fields.blanks int The number of times this field has been submitted with no contents
fields.dropped int The number of visitors who dropped off just before this field
visits int The number of visitors to the page of the form
interactions int The number of visitors who interacted with the form
submits int The number of submit attempts of the form
success int The number of successful submits of the form

Available forms

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/forms/available?url={url}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}/forms/available?url={url}')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}/forms/available?url={url}",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/forms/available?url={url}");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/forms/available?url={url}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/forms/available?url={url}",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}/forms/available?url={url}");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The above command returns JSON structured like this:

[
    {
        "target": "#settings-form",
        "fields": [
            {
                "target": "language",
                "type": "select"
            },
            {
                "target": "newsletter",
                "type": "checkbox"
            }
        ]
    },
    {
        "target": "#user-form",
        "fields": [
            {
                "target": "email",
                "type": "text"
            },
            {
                "target": "name",
                "type": "text"
            }
        ]
    }
]

Get available forms on a page

GET /websites/{website-id}/forms/available?url={url}

Required arguments (appended to the querystring)

Argument Datatype Description
url string The display url for the wanted page

Properties - Response

Property Datatype Description
target String An ID or selector for the form
fields Object[] The list of fields in the form
fields.target String A name, ID or selector for the field
fields.type String The HTML or input type of this field

Create a form

Your form object should be structured like this. URL and target fields are mandatory.

{
    "url": "/checkout",
    "target": "checkout-form",
    "alias": "Checkout Form",
    "fields": [
        {
            "target": "coupon",
            "alias": "Coupon Code Input"
        },
        {
            "target": "user",
            "alias": "User Name Input"
        },
        {
            "target": "terms",
            "alias": "Terms Checkbox"
        }
    ]
}
curl -X POST -u my@email.com:token1234 -d '{"url":"/checkout","target":"checkout-form","alias":"Checkout Form","fields":[{"target":"coupon","alias":"Coupon Code Input"},{"target":"user","alias":"User Name Input"},{"target":"terms","alias":"Terms Checkbox"}]}' https://api-us.mouseflow.com/websites/{website-id}/forms
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new('/websites/{website-id}/forms')
request.basic_auth('my@email.com', 'token1234')
request.body = '{"url":"/checkout","target":"checkout-form","alias":"Checkout Form","fields":[{"target":"coupon","alias":"Coupon Code Input"},{"target":"user","alias":"User Name Input"},{"target":"terms","alias":"Terms Checkbox"}]}'
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.post("https://api-us.mouseflow.com/websites/{website-id}/forms", '{"url":"/checkout","target":"checkout-form","alias":"Checkout Form","fields":[{"target":"coupon","alias":"Coupon Code Input"},{"target":"user","alias":"User Name Input"},{"target":"terms","alias":"Terms Checkbox"}]}',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/forms");
    curl_setopt_array($curl, array(
            CURLOPT_POST => TRUE,
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234",
            CURLOPT_HTTPHEADER => array("Content-Type: application/json")
        ),
        CURLOPT_POSTFIELDS => '{"url":"/checkout","target":"checkout-form","alias":"Checkout Form","fields":[{"target":"coupon","alias":"Coupon Code Input"},{"target":"user","alias":"User Name Input"},{"target":"terms","alias":"Terms Checkbox"}]}'
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/forms");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("POST");
OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
wr.write("{\"url\":\"/checkout\",\"target\":\"checkout-form\",\"alias\":\"Checkout Form\",\"fields\":[{\"target\":\"coupon\",\"alias\":\"Coupon Code Input\"},{\"target\":\"user\",\"alias\":\"User Name Input\"},{\"target\":\"terms\",\"alias\":\"Terms Checkbox\"}]}");
wr.flush();
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/forms",
    dataType: "json",
    contentType: "application/json",
    type: "POST",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    },
    data: JSON.stringify({"url":"/checkout","target":"checkout-form","alias":"Checkout Form","fields":[{"target":"coupon","alias":"Coupon Code Input"},{"target":"user","alias":"User Name Input"},{"target":"terms","alias":"Terms Checkbox"}]})
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.PostAsync("https://api-us.mouseflow.com/websites/{website-id}/forms",
        new StringContent("{\"url\":\"/checkout\",\"target\":\"checkout-form\",\"alias\":\"Checkout Form\",\"fields\":[{\"target\":\"coupon\",\"alias\":\"Coupon Code Input\"},{\"target\":\"user\",\"alias\":\"User Name Input\"},{\"target\":\"terms\",\"alias\":\"Terms Checkbox\"}]}"));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The above command returns JSON structured like this:

{
    "formId": "sWnRgWMF9UqfR3VVgNAN0A",
    "url": "/checkout",
    "target": "checkout-form",
    "alias": "Checkout Form",
    "fields": [
        {
            "target": "coupon",
            "alias": "Coupon Code Input"
        },
        {
            "target": "user",
            "alias": "User Name Input"
        },
        {
            "target": "terms",
            "alias": "Terms Checkbox"
        }
    ]
}

POST /websites/{website-id}/forms

Properties - Request

Property Datatype Description
url String The URL where the form is located
target String An ID or selector for the form
alias String A recognizable name you have given your form
fields Object[] The list of fields in your form report
fields.target String A name, ID or selector for the field
fields.alias String A recognizable name you have given this field

Properties - Response

Property Datatype Description
formId String This the unique ID associated with the form
url String The URL where the form is located
target String An ID or selector for the form
alias String A recognizable name you have given your form
fields Object[] The list of fields in your form report
fields.target String A name, ID or selector for the field
fields.alias String A recognizable name you have given this field

Edit a form

Your form object should be structured like this. No fields are mandatory. Use only the ones you want to edit. Note though that the "fields" field is a total list that cannot be partially updated. If specified it overwrites the previously saved list.

{
    "url": "/checkout",
    "target": "checkout-form",
    "alias": "Checkout Form",
    "fields": [
        {
            "target": "coupon",
            "alias": "Coupon Code Input"
        },
        {
            "target": "user",
            "alias": "User Name Input"
        },
        {
            "target": "terms",
            "alias": "Terms Checkbox"
        }
    ]
}
curl -X PUT -u my@email.com:token1234 -H 'Content-Type: application/json' -d '{"url":"/checkout","target":"checkout-form","alias":"Checkout Form","fields":[{"target":"coupon","alias":"Coupon Code Input"},{"target":"user","alias":"User Name Input"},{"target":"terms","alias":"Terms Checkbox"}]}' https://api-us.mouseflow.com/websites/{website-id}/forms/{form-id}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Put.new('/websites/{website-id}/forms/{form-id}')
request.basic_auth('my@email.com', 'token1234')
request.body = '{"url":"/checkout","target":"checkout-form","alias":"Checkout Form","fields":[{"target":"coupon","alias":"Coupon Code Input"},{"target":"user","alias":"User Name Input"},{"target":"terms","alias":"Terms Checkbox"}]}'
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.put("https://api-us.mouseflow.com/websites/{website-id}/forms/{form-id}", '{"url":"/checkout","target":"checkout-form","alias":"Checkout Form","fields":[{"target":"coupon","alias":"Coupon Code Input"},{"target":"user","alias":"User Name Input"},{"target":"terms","alias":"Terms Checkbox"}]}',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/forms/{form-id}");
    curl_setopt_array($curl, array(
            CURLOPT_CUSTOMREQUEST => "PUT",
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234",
            CURLOPT_HTTPHEADER => array("Content-Type: application/json")
        ),
        CURLOPT_POSTFIELDS => '{"url":"/checkout","target":"checkout-form","alias":"Checkout Form","fields":[{"target":"coupon","alias":"Coupon Code Input"},{"target":"user","alias":"User Name Input"},{"target":"terms","alias":"Terms Checkbox"}]}'
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/forms/{form-id}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("PUT");
OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
wr.write("{\"url\":\"/checkout\",\"target\":\"checkout-form\",\"alias\":\"Checkout Form\",\"fields\":[{\"target\":\"coupon\",\"alias\":\"Coupon Code Input\"},{\"target\":\"user\",\"alias\":\"User Name Input\"},{\"target\":\"terms\",\"alias\":\"Terms Checkbox\"}]}");
wr.flush();
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/forms/{form-id}",
    dataType: "json",
    contentType: "application/json",
    type: "PUT",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    },
    data: JSON.stringify({"url":"/checkout","target":"checkout-form","alias":"Checkout Form","fields":[{"target":"coupon","alias":"Coupon Code Input"},{"target":"user","alias":"User Name Input"},{"target":"terms","alias":"Terms Checkbox"}]})
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.PutAsync("https://api-us.mouseflow.com/websites/{website-id}/forms/{form-id}",
        new StringContent("{\"url\":\"/checkout\",\"target\":\"checkout-form\",\"alias\":\"Checkout Form\",\"fields\":[{\"target\":\"coupon\",\"alias\":\"Coupon Code Input\"},{\"target\":\"user\",\"alias\":\"User Name Input\"},{\"target\":\"terms\",\"alias\":\"Terms Checkbox\"}]}"));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

PUT /websites/{website-id}/forms/{form-id}

Properties - Request

Property Datatype Description
url String The URL where the form is located
target String An ID or selector for the form
alias String A recognizable name you have given your form
fields Object[] The list of fields in your form report
fields.target String A name, ID or selector for the field
fields.alias String A recognizable name you have given this field

Delete a form

curl -X DELETE -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/forms/{form-id}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Delete.new('/websites/{website-id}/forms/{form-id}')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.delete("https://api-us.mouseflow.com/websites/{website-id}/forms/{form-id}", '',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/forms/{form-id}");
    curl_setopt_array($curl, array(
            CURLOPT_CUSTOMREQUEST => "DELETE",
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234"
        )
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/forms/{form-id}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("DELETE");
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/forms/{form-id}",
    dataType: "json",
    type: "DELETE",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.DeleteAsync("https://api-us.mouseflow.com/websites/{website-id}/forms/{form-id}",
        new StringContent(""));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

DELETE /websites/{website-id}/forms/{form-id}

Feedback Campaigns

Feedback list

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/feedback
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}/feedback')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}/feedback",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/feedback");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/feedback");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/feedback",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}/feedback");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The above command returns JSON structured like this:

[
    {
        "campaignId": "kvnbQCMbpUyDwLArFDOuXw",
        "name": "#1: Title of the feedback text",
        "enabled": true,
        "showBranding": true,
        "triggerType": "delay",
        "triggerValue": 10000,
        "screenPosition": "bottomRight",
        "backgroundColor": "#4CB377",
        "foregroundColor": "#FFFFFF",
        "scope": "session",
        "startMinimized": false,
        "canBeDiscarded": true,
        "pageRules": [
            {
                "type": "startsWith",
                "value": "/onepage"
            },
            {
                "type": "startsWith",
                "value": "/anotherpage"
            }
        ],
        "segments": [
            {
                "type": "device",
                "value": "desktop"
            },
            {
                "type": "device",
                "value": "tablet"
            }
        ],
        "steps": [
            {
                "stepId": "6gld",
                "type": "radio",
                "text": "What do you think about our site?",
                "randomize": false,
                "answers": [
                    {
                        "answerId": "ute7",
                        "value": "It is awsome!",
                        "skipTo": "4wnc"
                    },
                    {
                        "answerId": "wgt3",
                        "value": "I don't like it..."
                    }
                ]
            },
            {
                "stepId": "buev",
                "type": "textarea",
                "text": "Please explain",
                "buttonText": "Next",
                "randomize": false,
                "answers": []
            }
        ],
        "report": {
            "impressions": 3434,
            "responses": 12,
            "responseChart": {
                "2018-12-25T00:00:00": 0,
                "2018-12-26T00:00:00": 0,
                "2018-12-27T00:00:00": 0
            }
        },
        "isLocked": false
    },
    {
        "campaignId": "CDT6DWNrhESsIfFiDTa5cA",
        "name": "Another Feedback Campaign",
        "enabled": false,
        "showBranding": true,
        "triggerType": "delay",
        "triggerValue": 8000,
        "screenPosition": "bottomRight",
        "backgroundColor": "#4CB377",
        "foregroundColor": "#FFFFFF",
        "scope": "session",
        "startMinimized": true,
        "canBeDiscarded": false,
        "pageRules": [
            {
                "type": "equals",
                "value": "/yetanotherpage"
            }
        ],
        "segments": [
            {
                "type": "device",
                "value": "tablet"
            }
        ],
        "steps": [
            {
                "stepId": "xhsh",
                "type": "textarea",
                "text": "Do you still like our site?",
                "buttonText": "Send Question",
                "randomize": false,
                "answers": []
            }
        ],
        "report": {
            "impressions": 0,
            "responses": 0,
            "responseChart": {}
        },
        "isLocked": false
    }
]

Get the list of Feedback Campaigns

GET /websites/{website-id}/feedback

Optional arguments (appended to the querystring)

For a full list of filtering options, please see the Filters section.

Properties

Property Datatype Description
campaignId String This the unique ID associated with the feedback campaign
name String An alias or name you have given for your feedback campaign
enabled bool Is the Feedback campaign enabled?
showBranding bool Can the user show her own brand in the feedback?
triggerType String Denotes what triggers the campaign. Can hold the following values: "Page Load", "Delay", "Scroll", "Inactivity", "Mouse Leaves Page", "Manual"
triggerValue String Used for trigger type "Delay" (delay in seconds), "Scroll" (percentage of page scrolled) and "Inactivity" (time of inactivity in seconds).
screenPosition String Position of Feedback widget. Can hold the following values "Bottom right", "Bottom left", "Top right", "Top left"
backgroundColor String RGB for Background Color of feedback widget
foregroundColor String RGB for Foreground Color of feedback widget
scope String Scope of feedback. Can hold the values "User" and "Session".
startMinimized bool Should the feedback widget start minimized?
canBeDiscarded bool Can the feedback widget be discarded?
pageRules Object[] Rules describing which pages the feedback widget should be triggered. See description further down.
segments Object[] Rules describing which segments the feedback widget should be triggered. See description further down.
steps Object[] The list of steps in your feedback widget. See description further down.
report Object[] The feedback report. See description further down.
isLocked bool Is the feedback locked

PageRules

A Pagerule denotes a rule that a page should comply with before triggering the feedback widget.

Valid types are: Equals, StartsWith, EndsWith, Regex, NotEquals, NotStartsWith and NotEndsWith.

Segments

A Segment denotes to which segments the campaign should be visible for.

Valid types are Language, VisitorType and Device. A language is represented by the repective country's ISO Alpha-2 country code.

Device Can be either "Desktop", "Tablet" or "Phone". VisitorType can be either "First-time visitor" or "Returning visitor".

Steps

A feedback widgets steps describe the individual steps in the feedback campaign.

Property Datatype Description
stepId String The Id of the step
type String Every step has a type of either: Radio (radio button), Text (input field), textArea, Success (success step), nps (net promoter score)
text String Text for the label associated with the
buttonText String Text on the button leading to the next step.
randomize bool If set to true the order of the possible answers will be randomized. Only applicable to multiple choice answers (radio buttons)
answers Object[] Only applicable to multiple choice answers (radio buttons). A list of possible answers consisting of an Id, a value (a text with the answer) and an id of a step to skip to in case of this option being chosen.

Feedback Report

A report is an aggregation of impressions, responses and a distribution of responses per day.

Feedback Details

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/feedback/{feedback-id}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}/feedback/{feedback-id}')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}/feedback/{feedback-id}",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/feedback/{feedback-id}");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/feedback/{feedback-id}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/feedback/{feedback-id}",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}/feedback/{feedback-id}");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

GET /websites/{website-id}/feedback/{feedback-id}

The above commands return JSON structured like this:

{
    "campaignId": "kvnbQCMbpUyDwLArFDOuXw",
    "name": "#1: Title of the feedback text",
    "enabled": true,
    "showBranding": true,
    "triggerType": "delay",
    "triggerValue": 10000,
    "screenPosition": "bottomRight",
    "backgroundColor": "#4CB377",
    "foregroundColor": "#FFFFFF",
    "scope": "session",
    "startMinimized": false,
    "canBeDiscarded": true,
    "pageRules": [
        {
            "type": "startsWith",
            "value": "/onepage"
        },
        {
            "type": "startsWith",
            "value": "/anotherpage"
        }
    ],
    "segments": [
        {
            "type": "device",
            "value": "desktop"
        },
        {
            "type": "device",
            "value": "tablet"
        }
    ],
    "steps": [
        {
            "stepId": "6gld",
            "type": "radio",
            "text": "What do you think about our site?",
            "randomize": false,
            "answers": [
                {
                    "answerId": "ute7",
                    "value": "It is awsome!",
                    "skipTo": "4wnc"
                },
                {
                    "answerId": "wgt3",
                    "value": "I don't like it..."
                }
            ]
        },
        {
            "stepId": "buev",
            "type": "textarea",
            "text": "Please explain",
            "buttonText": "Next",
            "randomize": false,
            "answers": []
        }
    ],
    "report": {
        "impressions": 3434,
        "responses": 12,
        "responseChart": {
            "2018-12-25T00:00:00": 0,
            "2018-12-26T00:00:00": 0,
            "2018-12-27T00:00:00": 0
        }
    },
    "isLocked": false
}

POST /websites/{website-id}/feedback

Properties

Property Datatype Description
campaignId String This the unique ID associated with the feedback campaign
name String An alias or name you have given for your feedback campaign
enabled bool Is the Feedback campaign enabled?
showBranding bool Can the user show her own brand in the feedback?
triggerType String Denotes what triggers the campaign. Can hold the following values: "Page Load", "Delay", "Scroll", "Inactivity", "Mouse Leaves Page", "Manual"
triggerValue String Used for trigger type "Delay" (delay in seconds), "Scroll" (percentage of page scrolled) and "Inactivity" (time of inactivity in seconds).
screenPosition String Position of Feedback widget. Can hold the following values "Bottom right", "Bottom left", "Top right", "Top left"
backgroundColor String RGB for Background Color of feedback widget
foregroundColor String RGB for Foreground Color of feedback widget
scope String Scope of feedback. Can hold the values "User" and "Session".
startMinimized bool Should the feedback widget start minimized?
canBeDiscarded bool Can the feedback widget be discarded?
pageRules Object[] Rules describing which pages the feedback widget should be triggered. See description further down.
segments Object[] Rules describing which segments the feedback widget should be triggered. See description further down.
steps Object[] The list of steps in your feedback widget. See description further down.
report Object[] The feedback report. See description further down.
isLocked bool Is the feedback locked
notification String Can be either email of url or empty.

PageRules

A Pagerule denotes a rule that a page should comply with before triggering the feedback widget. Your PageRules should be structured like this:

Valid types are: Equals, StartsWith, EndsWith, Regex, NotEquals, NotStartsWith and NotEndsWith.

Segments

A Segment denotes to which segments the campaign should be visible for. This should be structured in the following manner:

Valid types are Language, VisitorType and Device. A language is represented by the repective country's ISO Alpha-2 country code.

Device Can be either "Desktop", "Tablet" or "Phone". VisitorType can be either "First-time visitor" or "Returning visitor".

Steps

A feedback widgets steps describe the individual steps in the feedback campaign. This should be structured in the following manner:

Property Datatype Description
stepId String The Id of the step
type String Every step has a type of either: Radio (radio button), Text (input field), textArea, Success (success step), nps (net promoter score)
text String Text for the label associated with the
buttonText String Text on the button leading to the next step.
randomize bool If set to true the order of the possible answers will be randomized. Only applicable to multiple choice answers (radio buttons)
answers Object[] Only applicable to multiple choice answers (radio buttons). A list of possible answers consisting of an Id, a value (a text with the answer) and an id of a step to skip to in case of this option being chosen.

Create a Feedback Campaign

curl -X POST -u my@email.com:token1234 -H 'Content-Type: application/json' -d '{"steps":[{"stepId":"p3p0","text":"A Question","type":"text","buttonText":"Next"},{"type":"success","stepId":"w6d6","text":"Thank you for answering our questions!","buttonText":"Close"}],"name":"A Campaign","backgroundColor":"#4CB377","foregroundColor":"#FFFFFF","screenPosition":"bottomRight","startMinimized":false,"canBeDiscarded":false,"showBranding":true,"triggerType":"pageLoad","scope":"user","pageRules":[],"segments":[],"enabled":false}' https://api-us.mouseflow.com/websites/{website-id}/feedback
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP:Post.new('/websites/{website-id}/feedback')
request.basic_auth('my@email.com', 'token1234')
request.body = '{"steps":[{"stepId":"p3p0","text":"A Question","type":"text","buttonText":"Next"},{"type":"success","stepId":"w6d6","text":"Thank you for answering our questions!","buttonText":"Close"}],"name":"A Campaign","backgroundColor":"#4CB377","foregroundColor":"#FFFFFF","screenPosition":"bottomRight","startMinimized":false,"canBeDiscarded":false,"showBranding":true,"triggerType":"pageLoad","scope":"user","pageRules":[],"segments":[],"enabled":false}'
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.post("https://api-us.mouseflow.com/websites/{website-id}/feedback", '{"steps":[{"stepId":"p3p0","text":"A Question","type":"text","buttonText":"Next"},{"type":"success","stepId":"w6d6","text":"Thank you for answering our questions!","buttonText":"Close"}],"name":"A Campaign","backgroundColor":"#4CB377","foregroundColor":"#FFFFFF","screenPosition":"bottomRight","startMinimized":false,"canBeDiscarded":false,"showBranding":true,"triggerType":"pageLoad","scope":"user","pageRules":[],"segments":[],"enabled":false}',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/feedback");
    curl_setopt_array($curl, array(
            CURLOPT_CUSTOMREQUEST => "POST",
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234",
            CURLOPT_HTTPHEADER => array("Content-Type: application/json")
        ),
        CURLOPT_POSTFIELDS => '{"steps":[{"stepId":"p3p0","text":"A Question","type":"text","buttonText":"Next"},{"type":"success","stepId":"w6d6","text":"Thank you for answering our questions!","buttonText":"Close"}],"name":"A Campaign","backgroundColor":"#4CB377","foregroundColor":"#FFFFFF","screenPosition":"bottomRight","startMinimized":false,"canBeDiscarded":false,"showBranding":true,"triggerType":"pageLoad","scope":"user","pageRules":[],"segments":[],"enabled":false}'
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);     
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/feedback");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("POST");
OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
wr.write("{\"steps\":[{\"stepId\":\"p3p0\",\"text\":\"A Question\",\"type\":\"text\",\"buttonText\":\"Next\"},{\"type\":\"success\",\"stepId\":\"w6d6\",\"text\":\"Thank you for answering our questions!\",\"buttonText\":\"Close\"}],\"name\":\"A Campaign\",\"backgroundColor\":\"#4CB377\",\"foregroundColor\":\"#FFFFFF\",\"screenPosition\":\"bottomRight\",\"startMinimized\":false,\"canBeDiscarded\":false,\"showBranding\":true,\"triggerType\":\"pageLoad\",\"scope\":\"user\",\"pageRules\":[],\"segments\":[],\"enabled\":false}");

wr.flush();
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/feedback",
    dataType: "json",
    contentType: "application/json",
    type: "POST",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    },
    data: JSON.stringify({"steps":[{"stepId":"p3p0","text":"A Question","type":"text","buttonText":"Next"},{"type":"success","stepId":"w6d6","text":"Thank you for answering our questions!","buttonText":"Close"}],"name":"A Campaign","backgroundColor":"#4CB377","foregroundColor":"#FFFFFF","screenPosition":"bottomRight","startMinimized":false,"canBeDiscarded":false,"showBranding":true,"triggerType":"pageLoad","scope":"user","pageRules":[],"segments":[],"enabled":false})
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.PostAsync("https://api-us.mouseflow.com/websites/{website-id}/feedback",
        new StringContent("{\"steps\":[{\"stepId\":\"p3p0\",\"text\":\"A Question\",\"type\":\"text\",\"buttonText\":\"Next\"},{\"type\":\"success\",\"stepId\":\"w6d6\",\"text\":\"Thank you for answering our questions!\",\"buttonText\":\"Close\"}],\"name\":\"A Campaign\",\"backgroundColor\":\"#4CB377\",\"foregroundColor\":\"#FFFFFF\",\"screenPosition\":\"bottomRight\",\"startMinimized\":false,\"canBeDiscarded\":false,\"showBranding\":true,\"triggerType\":\"pageLoad\",\"scope\":\"user\",\"pageRules\":[],\"segments\":[],\"enabled\":false}"));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

Your feedback campaign object should be structured like this:

{
    "campaignId": "kvnbQCMbpUyDwLArFDOuXw",
    "name": "#1: Title of the feedback text",
    "enabled": true,
    "showBranding": true,
    "triggerType": "delay",
    "triggerValue": 10000,
    "screenPosition": "bottomRight",
    "backgroundColor": "#4CB377",
    "foregroundColor": "#FFFFFF",
    "scope": "session",
    "startMinimized": false,
    "canBeDiscarded": true,
    "pageRules": [
        {
            "type": "startsWith",
            "value": "/onepage"
        },
        {
            "type": "startsWith",
            "value": "/anotherpage"
        }
    ],
    "segments": [
        {
            "type": "device",
            "value": "desktop"
        },
        {
            "type": "device",
            "value": "tablet"
        }
    ],
    "steps": [
        {
            "stepId": "6gld",
            "type": "radio",
            "text": "What do you think about our site?",
            "randomize": false,
            "answers": [
                {
                    "answerId": "ute7",
                    "value": "It is awsome!",
                    "skipTo": "4wnc"
                },
                {
                    "answerId": "wgt3",
                    "value": "I don't like it..."
                }
            ]
        },
        {
            "stepId": "buev",
            "type": "textarea",
            "text": "Please explain",
            "buttonText": "Next",
            "randomize": false,
            "answers": []
        }
    ],
    "isLocked": false
}

POST /websites/{website-id}/feedback

Properties

Property Datatype Description
campaignId String This the unique ID associated with the feedback campaign
name String An alias or name you have given for your feedback campaign
enabled bool Is the Feedback campaign enabled?
showBranding bool Can the user show her own brand in the feedback?
triggerType String Denotes what triggers the campaign. Can hold the following values: "Page Load", "Delay", "Scroll", "Inactivity", "Mouse Leaves Page", "Manual"
triggerValue String Used for trigger type "Delay" (delay in seconds), "Scroll" (percentage of page scrolled) and "Inactivity" (time of inactivity in seconds).
screenPosition String Position of Feedback widget. Can hold the following values "Bottom right", "Bottom left", "Top right", "Top left"
backgroundColor String RGB for Background Color of feedback widget
foregroundColor String RGB for Foreground Color of feedback widget
scope String Scope of feedback. Can hold the values "User" and "Session".
startMinimized bool Should the feedback widget start minimized?
canBeDiscarded bool Can the feedback widget be discarded?
pageRules Object[] Rules describing which pages the feedback widget should be triggered. See description further down.
segments Object[] Rules describing which segments the feedback widget should be triggered. See description further down.
steps Object[] The list of steps in your feedback widget. See description further down.
report Object[] The feedback report. See description further down.
isLocked bool Is the feedback locked
notification String Can be either email of url or empty.

PageRules

A Pagerule denotes a rule that a page should comply with before triggering the feedback widget. Your PageRules should be structured like this:

Valid types are: Equals, StartsWith, EndsWith, Regex, NotEquals, NotStartsWith and NotEndsWith.

Segments

A Segment denotes to which segments the campaign should be visible for. This should be structured in the following manner:

Valid types are Language, VisitorType and Device. A language is represented by the repective country's ISO Alpha-2 country code.

Device Can be either "Desktop", "Tablet" or "Phone". VisitorType can be either "First-time visitor" or "Returning visitor".

Steps

A feedback widgets steps describe the individual steps in the feedback campaign. This should be structured in the following manner:

Property Datatype Description
stepId String The Id of the step
type String Every step has a type of either: Radio (radio button), Text (input field), textArea, Success (success step), nps (net promoter score)
text String Text for the label associated with the
buttonText String Text on the button leading to the next step.
randomize bool If set to true the order of the possible answers will be randomized. Only applicable to multiple choice answers (radio buttons)
answers Object[] Only applicable to multiple choice answers (radio buttons). A list of possible answers consisting of an Id, a value (a text with the answer) and an id of a step to skip to in case of this option being chosen.

Update a Feedback Campaign

curl -X PUT -u my@email.com:token1234 -H 'Content-Type: application/json' -d '{"steps":[{"stepId":"p3p0","text":"A Question","type":"text","buttonText":"Next"},{"type":"success","stepId":"w6d6","text":"Thank you for answering our questions!","buttonText":"Close"}],"name":"A Campaign","backgroundColor":"#4CB377","foregroundColor":"#FFFFFF","screenPosition":"bottomRight","startMinimized":false,"canBeDiscarded":false,"showBranding":true,"triggerType":"pageLoad","scope":"user","pageRules":[],"segments":[],"enabled":false}' https://api-us.mouseflow.com/websites/{website-id}/feedback/{feedback-id}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Put.new('/websites/{website-id}/feedback/{feedback-id}')
request.basic_auth('my@email.com', 'token1234')
request.body = '{"steps":[{"stepId":"p3p0","text":"A Question","type":"text","buttonText":"Next"},{"type":"success","stepId":"w6d6","text":"Thank you for answering our questions!","buttonText":"Close"}],"name":"A Campaign","backgroundColor":"#4CB377","foregroundColor":"#FFFFFF","screenPosition":"bottomRight","startMinimized":false,"canBeDiscarded":false,"showBranding":true,"triggerType":"pageLoad","scope":"user","pageRules":[],"segments":[],"enabled":false}'
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.put("https://api-us.mouseflow.com/websites/{website-id}/feedback/{feedback-id}", '{"steps":[{"stepId":"p3p0","text":"A Question","type":"text","buttonText":"Next"},{"type":"success","stepId":"w6d6","text":"Thank you for answering our questions!","buttonText":"Close"}],"name":"A Campaign","backgroundColor":"#4CB377","foregroundColor":"#FFFFFF","screenPosition":"bottomRight","startMinimized":false,"canBeDiscarded":false,"showBranding":true,"triggerType":"pageLoad","scope":"user","pageRules":[],"segments":[],"enabled":false}',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/feedback/{feedback-id}");
    curl_setopt_array($curl, array(
            CURLOPT_CUSTOMREQUEST => "PUT",
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234",
            CURLOPT_HTTPHEADER => array("Content-Type: application/json")
        ),
        CURLOPT_POSTFIELDS => '{"steps":[{"stepId":"p3p0","text":"A Question","type":"text","buttonText":"Next"},{"type":"success","stepId":"w6d6","text":"Thank you for answering our questions!","buttonText":"Close"}],"name":"A Campaign","backgroundColor":"#4CB377","foregroundColor":"#FFFFFF","screenPosition":"bottomRight","startMinimized":false,"canBeDiscarded":false,"showBranding":true,"triggerType":"pageLoad","scope":"user","pageRules":[],"segments":[],"enabled":false}'
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);     
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/feedback/{feedback-id}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("PUT");
OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
wr.write("{\"steps\":[{\"stepId\":\"p3p0\",\"text\":\"A Question\",\"type\":\"text\",\"buttonText\":\"Next\"},{\"type\":\"success\",\"stepId\":\"w6d6\",\"text\":\"Thank you for answering our questions!\",\"buttonText\":\"Close\"}],\"name\":\"A Campaign\",\"backgroundColor\":\"#4CB377\",\"foregroundColor\":\"#FFFFFF\",\"screenPosition\":\"bottomRight\",\"startMinimized\":false,\"canBeDiscarded\":false,\"showBranding\":true,\"triggerType\":\"pageLoad\",\"scope\":\"user\",\"pageRules\":[],\"segments\":[],\"enabled\":false}");

wr.flush();
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/feedback/{feedback-id}",
    dataType: "json",
    contentType: "application/json",
    type: "PUT",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    },
    data: JSON.stringify({"steps":[{"stepId":"p3p0","text":"A Question","type":"text","buttonText":"Next"},{"type":"success","stepId":"w6d6","text":"Thank you for answering our questions!","buttonText":"Close"}],"name":"A Campaign","backgroundColor":"#4CB377","foregroundColor":"#FFFFFF","screenPosition":"bottomRight","startMinimized":false,"canBeDiscarded":false,"showBranding":true,"triggerType":"pageLoad","scope":"user","pageRules":[],"segments":[],"enabled":false})
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.PutAsync("https://api-us.mouseflow.com/websites/{website-id}/feedback/{feedback-id}",
        new StringContent("{\"steps\":[{\"stepId\":\"p3p0\",\"text\":\"A Question\",\"type\":\"text\",\"buttonText\":\"Next\"},{\"type\":\"success\",\"stepId\":\"w6d6\",\"text\":\"Thank you for answering our questions!\",\"buttonText\":\"Close\"}],\"name\":\"A Campaign\",\"backgroundColor\":\"#4CB377\",\"foregroundColor\":\"#FFFFFF\",\"screenPosition\":\"bottomRight\",\"startMinimized\":false,\"canBeDiscarded\":false,\"showBranding\":true,\"triggerType\":\"pageLoad\",\"scope\":\"user\",\"pageRules\":[],\"segments\":[],\"enabled\":false}"));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

Your feedback campaign object should be structured like this:

{
    "campaignId": "kvnbQCMbpUyDwLArFDOuXw",
    "name": "#1: Title of the feedback text",
    "enabled": true,
    "showBranding": true,
    "triggerType": "delay",
    "triggerValue": 10000,
    "screenPosition": "bottomRight",
    "backgroundColor": "#4CB377",
    "foregroundColor": "#FFFFFF",
    "scope": "session",
    "startMinimized": false,
    "canBeDiscarded": true,
    "pageRules": [
        {
            "type": "startsWith",
            "value": "/onepage"
        },
        {
            "type": "startsWith",
            "value": "/anotherpage"
        }
    ],
    "segments": [
        {
            "type": "device",
            "value": "desktop"
        },
        {
            "type": "device",
            "value": "tablet"
        }
    ],
    "steps": [
        {
            "stepId": "6gld",
            "type": "radio",
            "text": "What do you think about our site?",
            "randomize": false,
            "answers": [
                {
                    "answerId": "ute7",
                    "value": "It is awsome!",
                    "skipTo": "4wnc"
                },
                {
                    "answerId": "wgt3",
                    "value": "I don't like it..."
                }
            ]
        },
        {
            "stepId": "buev",
            "type": "textarea",
            "text": "Please explain",
            "buttonText": "Next",
            "randomize": false,
            "answers": []
        }
    ],
    "isLocked": false
}

PUT /websites/{website-id}/feedback/{feedback-id}

Properties

Property Datatype Description
campaignId String This the unique ID associated with the feedback campaign
name String An alias or name you have given for your feedback campaign
enabled bool Is the Feedback campaign enabled?
showBranding bool Can the user show her own brand in the feedback?
triggerType String Denotes what triggers the campaign. Can hold the following values: "Page Load", "Delay", "Scroll", "Inactivity", "Mouse Leaves Page", "Manual"
triggerValue String Used for trigger type "Delay" (delay in seconds), "Scroll" (percentage of page scrolled) and "Inactivity" (time of inactivity in seconds).
screenPosition String Position of Feedback widget. Can hold the following values "Bottom right", "Bottom left", "Top right", "Top left"
backgroundColor String RGB for Background Color of feedback widget
foregroundColor String RGB for Foreground Color of feedback widget
scope String Scope of feedback. Can hold the values "User" and "Session".
startMinimized bool Should the feedback widget start minimized?
canBeDiscarded bool Can the feedback widget be discarded?
pageRules Object[] Rules describing which pages the feedback widget should be triggered. See description further down.
segments Object[] Rules describing which segments the feedback widget should be triggered. See description further down.
steps Object[] The list of steps in your feedback widget. See description further down.
report Object[] The feedback report. See description further down.
isLocked bool Is the feedback locked
notification String Can be either email of url or empty.

PageRules

A Pagerule denotes a rule that a page should comply with before triggering the feedback widget. Your PageRules should be structured like this:

Valid types are: Equals, StartsWith, EndsWith, Regex, NotEquals, NotStartsWith and NotEndsWith.

Segments

A Segment denotes to which segments the campaign should be visible for. This should be structured in the following manner:

Valid types are Language, VisitorType and Device. A language is represented by the repective country's ISO Alpha-2 country code.

Device Can be either "Desktop", "Tablet" or "Phone". VisitorType can be either "First-time visitor" or "Returning visitor".

Steps

A feedback widgets steps describe the individual steps in the feedback campaign. This should be structured in the following manner:

Property Datatype Description
stepId String The Id of the step
type String Every step has a type of either: Radio (radio button), Text (input field), textArea, Success (success step), nps (net promoter score)
text String Text for the label associated with the
buttonText String Text on the button leading to the next step.
randomize bool If set to true the order of the possible answers will be randomized. Only applicable to multiple choice answers (radio buttons)
answers Object[] Only applicable to multiple choice answers (radio buttons). A list of possible answers consisting of an Id, a value (a text with the answer) and an id of a step to skip to in case of this option being chosen.

Delete a Feedback Campaign

curl -X DELETE -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/feedback/{feedback-id}
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Delete.new('/websites/{website-id}/feedback/{feedback-id}')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.delete("https://api-us.mouseflow.com/websites/{website-id}/feedback/{feedback-id}", '',
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/feedback/{feedback-id}");
    curl_setopt_array($curl, array(
            CURLOPT_CUSTOMREQUEST => "DELETE",
            CURLOPT_RETURNTRANSFER => TRUE,
            CURLOPT_USERPWD => "my@email.com:token1234"
        )
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);     
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/feedback/{feedback-id}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("DELETE");
int HttpResult = conn.getResponseCode();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/feedback/{feedback-id}",
    dataType: "json",
    type: "DELETE",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.DeleteAsync("https://api-us.mouseflow.com/websites/{website-id}/feedback/{feedback-id}",
        new StringContent(""));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

DELETE /websites/feedback/{feedback-id}

Filters

You can use many different filters to segment the recording list, the heatmap page lists and the funnels. This section gives an overview of which filters are available. All filter properties must be added as querystring parameters to the API calls.

Some filters are applicable to both session-based and pageview-based queries, where some are only applicable to one type. Session-based searches are: the recording list and funnels. Pageview-based searches are the heatmap page lists.

Date range filters

Recording list example with filters

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/recordings?fromdate=2015-10-04&todate=2015-10-15
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}/recordings?fromdate=2015-10-04&todate=2015-10-15')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}/recordings?fromdate=2015-10-04&todate=2015-10-15",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/recordings?fromdate=2015-10-04&todate=2015-10-15");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/recordings?fromdate=2015-10-04&todate=2015-10-15");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/recordings?fromdate=2015-10-04&todate=2015-10-15",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}/recordings?fromdate=2015-10-04&todate=2015-10-15");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}
Property Datatype Description
fromdate Date The start date of the query. The actual start time is midnight on the selected date, according to the user's selected time zone.
todate Date The end date of the query. This date is not included in the query.

Recording list example with filters

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/recordings?search=products
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}/recordings?search=products')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}/recordings?search=products",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/recordings?search=products");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/recordings?search=products");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/recordings?search=products",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}/recordings?search=products");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}
Property Datatype Description
search String Use any free-text search here. The system searches in all filterable fields, and includes the user agent string, the IP address, the city and region of the visitor. However, when used in heatmap page lists, it only searches in the page URLs

Visitor data filters

Heatmap page list example with filters

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/pagelist?browser=chrome&country=de&device=desktop&visitortype=returning&referrer=searchengines
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}/pagelist?browser=chrome&country=de&device=desktop&visitortype=returning&referrer=searchengines')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}/pagelist?browser=chrome&country=de&device=desktop&visitortype=returning&referrer=searchengines",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/pagelist?browser=chrome&country=de&device=desktop&visitortype=returning&referrer=searchengines");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/pagelist?browser=chrome&country=de&device=desktop&visitortype=returning&referrer=searchengines");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/pagelist?browser=chrome&country=de&device=desktop&visitortype=returning&referrer=searchengines",
    dataType: "json",
    type: "GET",
    headers: {"Authorization": "Basic " + btoa("my@email.com:token1234")}
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}/pagelist?browser=chrome&country=de&device=desktop&visitortype=returning&referrer=searchengines");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}
Property Datatype Description
country String Only visitors from a specific country. Countries are represented by their two-character country codes, defined by the ISO 3166-1 alpha-2 standard.
device String Only visitors using a specific device type. Options are desktop, tablet and phone.
browser String Only visitors using a specific browser. Options are chrome, firefox, safari, ie, edge, opera and android (Android Browser)
os String Only visitors using a specific operating system. Options are windows, mac os, linux, ios, android, blackberry os, windows phone
visitortype String First-time ("first") or returning users ("returning")
referrer String The referral type. Options: searchengines, links, direct, social, email
screenres String Only visitors using a specified screen resolution in the format "1280x800" (width x height)

Recording list example with filters

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/recordings?entry=%2Flanding-page&funnel=%2Fproducts&exit=%2Fthank-you&visitmin=18000
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}/recordings?entry=%2Flanding-page&funnel=%2Fproducts&exit=%2Fthank-you&visitmin=18000')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}/recordings?entry=%2Flanding-page&funnel=%2Fproducts&exit=%2Fthank-you&visitmin=18000",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/recordings?entry=%2Flanding-page&funnel=%2Fproducts&exit=%2Fthank-you&visitmin=18000");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/recordings?entry=%2Flanding-page&funnel=%2Fproducts&exit=%2Fthank-you&visitmin=18000");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/recordings?entry=%2Flanding-page&funnel=%2Fproducts&exit=%2Fthank-you&visitmin=18000",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}/recordings?entry=%2Flanding-page&funnel=%2Fproducts&exit=%2Fthank-you&visitmin=18000");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

The navigational filters are only applicable to session-based queries (recording lists and funnels). They will have no effect if used in heatmap page list queries.

Property Datatype Description
entry String Only visitors that landed on this page.
exit String Only visitors that ended their session on this page.
funnel String Only visitors that saw this page as a part of the session.
notfunnel String Only visitors that did not see this page in the session
pagesmin int The minimum number of pageviews in the session
pagesmax int The maximum number of pageviews in the session
visitmin int The minimum session duration, in milliseconds
visitmax int The maximum session duration, in milliseconds

Meta data filters

Tags and Variables

Recording list example with filters

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/recordings?watched=1&tags=form-interact%2Csubmit&vars=plan%3Dsmall&star=0
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}/recordings?watched=1&tags=form-interact%2Csubmit&vars=plan%3Dsmall&star=0')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}/recordings?watched=1&tags=form-interact%2Csubmit&vars=plan%3Dsmall&star=0",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/recordings?watched=1&tags=form-interact%2Csubmit&vars=plan%3Dsmall&star=0");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/recordings?watched=1&tags=form-interact%2Csubmit&vars=plan%3Dsmall&star=0");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/recordings?watched=1&tags=form-interact%2Csubmit&vars=plan%3Dsmall&star=0",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}/recordings?watched=1&tags=form-interact%2Csubmit&vars=plan%3Dsmall&star=0");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

Meta data filters can filter across any custom or system tags, any custom variables and whether or not the session has been watched by your user account.

Property Datatype Description
tags String A comma-separated list of tags that must be present in the session/pageview (depending on query type - session or pageview based). See below table for system tags.
vars String A comma-separated list of variables that must be present in the session/pageview. Each variable should be represented like this "key=value". You can use * for Any Value, and ^ for Not Set.
watched int The value 0 means that you filter by sessions that have not been watched, and the value 1 means you filter by watched sessions (session-based queries only)
star int The value 0 means that you filter by sessions that have not been starred, and the value 1 means you filter by starred sessions (session-based queries only)

System tags (pageview-based)

System tags are tags that are automatically added to your visitor data. Tags can have either session or pageview scope.

Tag Description
form-interact String
submit The user submitted (or tried submitting) a form (pageview scope)
shared This session has been shared - or this pageview is a part of a shared session (session scope)

Friction Filters

Friction is represented as a number denoting the amount of friction the user has experienced in her session. The higher friction the more unhappy the user is. You can filter using two querystring paramaters: frictionmin and frictionmax, both of which are optional.

Recording list example with filters.

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/recordings?frictionmin=2.5
require 'net/https'

http = Net::HTTP.new('https://api-us.mouseflow.com')
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new('/websites/{website-id}/recordings?frictionmin=2.5')
request.basic_auth('my@email.com', 'token1234')
response = http.request(request)
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://api-us.mouseflow.com/websites/{website-id}/recordings?frictionmin=2.5",
    auth=HTTPBasicAuth("my@email.com", "token1234"))
<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/recordings?frictionmin=2.5");
    curl_setopt($curl, CURLOPT_USERPWD, "my@email.com:token1234");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    $return = curl_exec ($curl);
    curl_close ($curl);
?>
URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/recordings?frictionmin=2.5");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
String encoded = Base64.encodeToString(("my@email.com:token1234").getBytes("UTF-8"), Base64.NO_WRAP);
conn.setRequestProperty("Authorization", "Basic " + encoded);
conn.setRequestMethod("GET");
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null)
    System.out.println(inputLine);
in.close();
$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/recordings?frictionmin=2.5",
    dataType: "json",
    type: "GET",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    }
}).always(function (data) {
    console.log(JSON.stringify(data));
});
using (var handler = new HttpClientHandler { Credentials = new NetworkCredential("my@email.com", "token1234") })
using (var client = new HttpClient(handler))
{
    var response = await client.GetAsync("https://api-us.mouseflow.com/websites/{website-id}/recordings?frictionmin=2.5");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

Errors

The Mouseflow API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- You do not have permission to access.
404 Not Found -- The requested URL could not be found.
405 Method Not Allowed -- You tried to access an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The URL requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You are making too many requests within a short timeframe.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.