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:

2015-09-15 (Date only)
2015-09-15T14:34:22 (Date + time)

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:

us (United States)
de (Germany)
uk (United Kingdom)

Languages

Languages are represented by the IETF language tag definition.

Examples:

en-US (American English)
es-MX (Mexican Spanish)
pt-BR (Brazilian Portuguese)
de (German - no country specified)

Common arguments in endpoints

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

{website-id} = The unique ID of a website
{recording-id} = The unique ID of a recording

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": "0b4343ae-578a-4652-8c13-0bb4c042670c",
    "name": "A Test Site",
    "created": "2022-11-22T18:07:06.84",
    "recordingStatus": "Recording",
    "installationStatus": "Ready",
    "recordingStatusChangeAllowed": true,
    "thumb": "",
    "openGraphThumbnail": "",
    "hasWriteAccess": true,
    "hasFullAccess": true,
    "domains": [
        "myshop2.com"
    ],
    "recordingRate": 100.00000,
    "pageIdentifiers": [],
    "anonymizeIps": true,
    "blockEuTraffic": false,
    "blockCaliforniaTraffic": false,
    "disableKeystrokes": true,
    "excludedIps": [
        "192.168.1.1"
    ],
    "cdnDomainName": "cdn.mouseflow.com",
    "isDemo": false,
    "cssSelectorBlacklist": [
    ".profileName"
    ],
    "cssSelectorWhitelist": [
        ".searchBar"
    ],
    "cssSelectorTracked": [
        "#image2"
    ],
    "honorDoNotTrack": true,
    "maxRecordingsPerMonth": 25000,
    "pageRules": [],
    "mergeUrls": [],
    "pageRecordingRules": [],
    "type": "ConsumerGoods",
    "subType": "",
    "minimumRecordingRate": 50
}

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
recordingStatus	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.
installationStatus	String	A string that indicates whether or not the script has been successfully installed on the website.
thumb	String	A partial URL for a thumbnail image generated from your website
openGraphThumbnail	String	A partial URL for a thumbnail image generated from your website
hasWriteAccess	bool	A boolean value that indicates whether you have have write access to the project
hasFullAccess	bool	A boolean value that indicates whether you have full access to the project
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.
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)
blockEuTraffic	bool	(US Accounts Only) A boolean value that allows you to exclude EU visitors from your recordings. For more information on GDPR compliance, please see this page
blockCaliforniaTraffic	bool	(US Accounts Only) A boolean value that allows you to exclude California visitors from your recordings. For more information on CCPA compliance, please see this page
anonymizeIps	bool	A setting that controls whether to anonymize users' IP addresses by removing the last digits. This setting cannot be disabled.
disableKeystrokes	bool	A setting that controls whether to completely disable keystroke logging. This setting cannot be disabled.
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.
cdnDomainName	string	An internal value that specifies the cdn server being used.
isDemo	bool	An internal value that indicates whether this site is a demo project.
cssSelectorBlacklist	String[]	This is a list of elements being excluded from Mouseflow recordings.
cssSelectorWhitelist	String[]	This is a list of input elements that are whitelisted from the disableKeystrokes setting.
cssSelectorTracked	String[]	This is a list of elements that you want to assign link analytics to that weren't automatically detected by the recording script.
honorDoNotTrack	bool	A boolean value that indicates whether you want to record a user who has enabled the do not track setting in their browser.
maxRecordingsPerMonth	int	An integer value that specifies that maximum number of recordings per month that should be collected on this website
pageRules	String[]	A list of rules for which pages visitors should be recorded on
mergeUrls	String[]	Used for merging several URLs into one in the heatmap lists. Use asterisk (*) as wildcard, or use regular expressions.
pageRecordingRules	String[]	A list of rules that specifies that recording rate on a per page level. This setting is only available on select Enterprise plans.
type	String	A category for the type of website you are recording. This value is used for determining industry metrics on the dashboard.
subType	String	A category for the type of website you are recording. This value is used for determining industry metrics on the dashboard.
minimumRecordingRate	int	The minimum percentage that the recording rate can be set to for your site. There lowest rate you are able to set depends on your payment plan, please see this article for more details.

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.
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,
    "pageIdentifiers": [
        "query",
        "page_id"
    ],
    "excludedIps": [
        "56.78.45.23",
        "120.340.210.*"
    ],
    "mergeUrls": [
        "/search/*"
    ]
}

PUT /websites/{website-id}

Your website object should be structured like the example to the right. No fields are mandatory, only use only the ones you want to update. See website details for the full list of available properties.

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": "a18001205e4656ba95cbe9f7cbbc0843",
            "token": "",
            "created": "2043-12-08T05:53:06.466271-05:00",
            "lastActivity": "2043-12-08T06:23:58.2694347-05:00",
            "pages": 2,
            "duration": 1851135,
            "engagementTime": 30192,
            "friction": 1,
            "country": "dk",
            "region": "",
            "city": "Copenhagen",
            "ip": "194.62.###.###",
            "lang": "en-US,en;q=0.9",
            "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/160.0.0.0 Safari/537.36",
            "browser": "Chrome",
            "browserVersion": "642.0.0.0",
            "os": "Windows",
            "osVersion": "10",
            "device": "Desktop",
            "referrer": "",
            "referrerType": "",
            "screenRes": "3440x1440",
            "entry": "/home",
            "entryPage": "/checkout",
            "tags": [
                "mouse-out"
            ],
            "variables": [],
            "watched": true,
            "starred": false,
            "lng": 16.5892,
            "lat": 25.6802,
            "gdpr": true,
            "visitorName": null,
            "playbackUrl": "https://app.mouseflow.com/websites/0b4343ae-578a-4652-8c13-0bb4c042670c/recordings/a18001205e4656ba95cbe9f7cbbc0843/play",
            "playbackPath": "/websites/0b4343ae-578a-4652-8c13-0bb4c042670c/recordings/a18001205e4656ba95cbe9f7cbbc0843/play"
        }
    ],
    "chart": {
        "2043-08-30": 13286,
        "2043-08-31": 17184,
        "2043-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.
engagementTime	int	The total time a user spend engaging on the page, in ms.
friction	int	A score with the amount of friction a user encountered during the visit. For more information on friction see this article
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)
ip	String	The user's IP address (will be anonymized with some 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
gdpr	bool	A boolean value that determine whether GDPR privacy settings were applied to the recording
visitorName	String	A visitor name you have associated with the visitor, only available on select EP plans.
playbackUrl	String	The url of the recording
playbackPath	String	The url path of the recording
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": "a18002105e4566ba95cbe9f8cbbc0843",
    "token": "",
    "created": "2043-12-08T05:53:06.466271-05:00",
    "lastActivity": "2043-12-08T06:23:58.2694347-05:00",
    "pageViews": [
        {
            "id": "120807296d51f8fab29d77280bb056c0cbbe7ff3",
            "startTime": "2043-12-08T05:53:06.466271-05:00",
            "endTime": "2043-12-08T05:53:17.2191477-05:00",
            "title": "Home",
            "uri": "https://myshop.com/home",
            "websitePage": "/home",
            "visitTime": 10942,
            "engagementTime": 7856,
            "scroll": 100.0,
            "tags": [
                "mouse-out",
                "comment"
            ],
            "friction": 1,
            "annotations": [
                {
                    "id": "q5rfi7",
                    "time": 2650,
                    "engagementTime": 2650,
                    "email": "me@gmail.com",
                    "text": "This is a comment",
                    "mine": true
                }
            ]
        },
        {
            "id": "12081917576af32cbb5688d5335a382d295a8e52",
            "startTime": "2023-12-08T05:53:18.0764347-05:00",
            "endTime": "2023-12-08T06:23:58.2694347-05:00",
            "title": "Home",
            "uri": "https://myshop.com/home",
            "websitePage": "/home",
            "visitTime": 1840193,
            "engagementTime": 22336,
            "scroll": 73.0,
            "tags": [
                "mouse-out"
            ],
            "friction": 0,
            "annotations": []
        }
    ],
    "pages": 2,
    "duration": 1851135,
    "engagementTime": 30192,
    "friction": 1,
    "country": "dk",
    "region": "84",
    "city": "Copenhagen",
    "ip": "194.62.###.###",
    "lang": "en-US,en;q=0.9",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36",
    "browser": "Chrome",
    "browserVersion": "119.0.0.0",
    "os": "Windows",
    "osVersion": " 10",
    "device": "Desktop",
    "referrer": "",
    "referrerType": "",
    "screenRes": "3440x1440",
    "entry": "https://myshop.com/home",
    "entryPage": "/home",
    "tags": [
        "mouse-out",
        "comment"
    ],
    "variables": [],
    "watched": false,
    "starred": false,
    "lng": 18.5892,
    "lat": 22.6802,
    "playbackUrl": "https://app.mouseflow.com/websites/0b4343ae-578a-4652-8c13-0bb4c042670c/recordings/a18002105e4566ba95cbe9f8cbbc0843/play",
    "playbackPath": "/websites/0b4343ae-578a-4652-8c13-0bb4c042670c/recordings/a18002105e4566ba95cbe9f8cbbc0843/play",
    "gdpr": true
}

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.
engagementTime	int	The total time a user spend engaging on the page, in ms.
friction	int	A score with the amount of friction a user encountered during the visit. For more information on friction see this article
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)
ip	String	The user's IP address (will be anonymized with some 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
gdpr	bool	A boolean value that determine whether GDPR privacy settings were applied to the recording
visitorName	String	A visitor name you have associated with the visitor, only available on select EP plans.
playbackUrl	String	The url of the recording
playbackPath	String	The url path of the recording
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

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)
friction	int	A score with the amount of friction a user encountered during the visit. For more information on friction see this article
annotations	list	Comments left on the reocording by you or your team members. See table below.

Properties - annotations

Property	Datatype	Description
id	String	An id assigned to the comment
time	int	The timestamp at which the comment was left
engagementTime	int	The timestamp at which the comment was left
email	String	The email of the user that left the comment
text	String	The contents of the comment
mine	bool	A boolean value that specifies whether or not you were the user that left the comment

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

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

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": "" }

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);
}

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

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": "/home",
            "uri": "https://myshop.com/home",
            "starred": false,
            "title": "Home",
            "views": 100,
            "visitTime": 59081,
            "engagementTime": 10302,
            "clicks": 157,
            "friction": 1.4146341,
            "renderTime": 161,
            "scroll": 99,
            "fold": 794,
            "height": 783,
            "size": 11834,
            "totalSessions": 100,
            "entry": 0,
            "exit": 0
        },
        {
            "displayUrl": "/checkout",
            "uri": "https://myshop.com/checkout",
            "starred": true,
            "title": "Checkout",
            "views": 41,
            "visitTime": 59081,
            "engagementTime": 10302,
            "clicks": 157,
            "friction": 1.4146341,
            "renderTime": 161,
            "scroll": 99,
            "fold": 794,
            "height": 783,
            "size": 11834,
            "totalSessions": 86,
            "entry": 0,
            "exit": 0
        }
    ],
    "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
starred	bool	A boolean value that determines whether or not the heatmap has been given priority in the list.
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
totalSessions	int	The number of recorded sessions the page has received in the specified time range.
entry	int	The number of session for which this page was where a visitor entered the site
exit	int	The number of session from which visitors left the site from this page

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:

{
    "displayUrl": "/",
    "uri": "https://myshop.com/jobs",
    "token": "kDMH2ljDlkmKpzoCXuF7eA",
    "title": "Positions available at MyShop",
    "views": 23410,
    "visitTime": 70593,
    "engagementTime": 10754,
    "clicks": 21299,
    "friction": 0.5,
    "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
friction	int	The score for the average amount of friction that occurs on this 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

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);
}

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

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
            }
        ],
        "isLocked": false,
        "isStarred": false
    },
    {
        "funnelId": "CDT6DWNrhESsIfFiDTa5cA",
        "name": "My Other Funnel",
        "steps": [
            {
                "name": "First step",
                "url": "/",
                "count": 500
            },
            {
                "name": "Second step",
                "url": "/second",
                "count": 250
            }
        ],
        "isLocked": false,
        "isStarred": false
    }
]

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
isLocked	bool	Determines whether or not you can access the funnel based on the limits of your plan
isStarred	bool	Determines whether or not the funnel has been prioritize in the list

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
        }
    ], 
    "isLocked": false,
    "isStarred": false
}

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
isLocked	bool	Determines whether or not you can access the funnel based on the limits of your plan
isStarred	bool	Determines whether or not the funnel has been prioritize in the list

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 Surveys

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 awesome!",
                        "skipTo": "4wnc"
                    },
                    {
                        "answerId": "wgt3",
                        "value": "I don't like it..."
                    }
                ]
            },
            {
                "stepId": "buev",
                "type": "textarea",
                "text": "Please explain",
                "buttonText": "Next",
                "randomize": false,
                "answers": [],
                "skipLogic": [],
                "isRequired": false,
                "randomizeExceptLast": false
            }
        ],
        "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 Survey",
        "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": [],
                "skipLogic": [],
                "isRequired": false,
                "randomizeExceptLast": false
            }
        ],
        "report": {
            "impressions": 0,
            "responses": 0,
            "responseChart": {}
        },
        "isLocked": false
    }
]

Get the list of Feedback Surveys

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 survey
name	String	An alias or name you have given for your feedback survey
enabled	bool	Is the Feedback survey enabled?
showBranding	bool	Can the user show her own brand in the feedback?
triggerType	String	Denotes what triggers the survey. 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 survey should be visible for.

Valid types are Language, VisitorType and Device. A language is represented by the respective 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 survey.

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.
skipLogic	Object[]	The logic for skipping certain steps based on specific answers
isRequired	bool	A value that specifies whether or not the visitor is required to answer this question
randomizeExceptLast	bool	A value that randomizes all options in a list except for the last answer choice

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 awesome!",
                    "skipTo": "4wnc"
                },
                {
                    "answerId": "wgt3",
                    "value": "I don't like it..."
                }
            ]
        },
        {
            "stepId": "buev",
            "type": "textarea",
            "text": "Please explain",
            "buttonText": "Next",
            "randomize": false,
            "answers": [],
            "skipLogic": [],
            "isRequired": false,
            "randomizeExceptLast": false
        }
    ],
    "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 survey
name	String	An alias or name you have given for your feedback survey
enabled	bool	Is the Feedback survey enabled?
showBranding	bool	Can the user show her own brand in the feedback?
triggerType	String	Denotes what triggers the survey. 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 survey 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 survey. 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.
skipLogic	Object[]	The logic for skipping certain steps based on specific answers
isRequired	bool	A value that specifies whether or not the visitor is required to answer this question
randomizeExceptLast	bool	A value that randomizes all options in a list except for the last answer choice

Create a Feedback Survey

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 Survey","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 Survey","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 Survey","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 Survey","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 Survey\",\"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 Survey","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 Survey\",\"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 survey 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": [],
            "skipLogic": [],
            "isRequired": false,
            "randomizeExceptLast": false
        }
    ],
    "isLocked": false
}

POST /websites/{website-id}/feedback

Properties

Property	Datatype	Description
campaignId	String	This the unique ID associated with the feedback survey
name	String	An alias or name you have given for your feedback survey
enabled	bool	Is the Feedback survey enabled?
showBranding	bool	Can the user show her own brand in the feedback?
triggerType	String	Denotes what triggers the survey. 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 survey 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 survey. 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.
skipLogic	Object[]	The logic for skipping certain steps based on specific answers
isRequired	bool	A value that specifies whether or not the visitor is required to answer this question
randomizeExceptLast	bool	A value that randomizes all options in a list except for the last answer choice

Update a Feedback survey

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 survey","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 Survey","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 Survey","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 Survey","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 Survey\",\"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 Survey","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 Survey\",\"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 survey 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": [],
            "skipLogic": [],
            "isRequired": false,
            "randomizeExceptLast": false
        }
    ],
    "isLocked": false
}

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

Properties

Property	Datatype	Description
campaignId	String	This the unique ID associated with the feedback survey
name	String	An alias or name you have given for your feedback survey
enabled	bool	Is the Feedback survey enabled?
showBranding	bool	Can the user show her own brand in the feedback?
triggerType	String	Denotes what triggers the survey. 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 survey 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 survey. 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.
skipLogic	Object[]	The logic for skipping certain steps based on specific answers
isRequired	bool	A value that specifies whether or not the visitor is required to answer this question
randomizeExceptLast	bool	A value that randomizes all options in a list except for the last answer choice

Delete a Feedback Survey

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.

Free-text search

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)

Navigational filters

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.

Property	Datatype	Description
frictionmin	int	The minimum friction value to filter by (optional)
frictionmax	int	The maximum friction value to filter by (optional)

Recording list example with a friction filter

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);
}

Saved Filters

Get the list of saved filtered views

GET /websites/{website-id}/views

Property	Datatype	Description
viewId	String	An id assigned to the saved filter
name	String	The name of the saved filter
shared	bool	A boolean for determining whether the saved filter is shared across users on the account
canSave	bool	A boolean for whether or not this filter can be saved by your account, this is dependent on a users permission level
query	string	The filter being applied

Example of getting a list of saved filters

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

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}/views')
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}/views",
    auth=HTTPBasicAuth("my@email.com", "token1234"))

<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/views");
    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}/views");
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}/views",
    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}/views");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

Your saved views will appear like this:

[
    {
        "viewId": "gttQHcSE1EWRtAXQZZ-B4g",
        "name": "Logged-In Visitors",
        "shared": false,
        "canSave": true,
        "query": "tags=logged-in"
    },
    {
        "viewId": "XdsvfrcjOkS6O6Okne6tQA",
        "name": "Low Friction",
        "shared": false,
        "canSave": true,
        "query": "frictionmin=1"
    }
]

Get the details of one saved view

GET /websites/{website-id}/views/{view-id}/{view-id}

Example of getting a list of saved filters

curl -u my@email.com:token1234 https://api-us.mouseflow.com/websites/{website-id}/views/{view-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}/views/{view-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}/views/{view-id}",
    auth=HTTPBasicAuth("my@email.com", "token1234"))

<?php
    $curl = curl_init();
    curl_setopt ($curl, CURLOPT_URL, "https://api-us.mouseflow.com/websites/{website-id}/views/{view-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}/views/{view-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}/views/{view-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}/views/{view-id}");
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

Your saved view will appear with the following stucture:

    {
        "viewId": "gttQHcSE1EWRtAXQZZ-B4g",
        "name": "Logged-In Visitors",
        "shared": false,
        "canSave": true,
        "query": "tags=logged-in"
    }

Create a filtered view

POST /websites/{website-id}/views

Creating a new saved view.

Property	Datatype	Description
name	String	The name of the saved filter (required)
query	string	The filter being applied (required)
shared	bool	A boolean for determining whether the saved filter is shared across users on the account (optional)

curl -X POST -u my@email.com:token1234 -H 'Content-Type: application/json' -d '{"name": "New View", "query": "frictionmin=1"}' https://api-us.mouseflow.com/websites/{website-id}/views

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}/views')
request.basic_auth('my@email.com', 'token1234')
request.body = '{"name": "New View", "query": "frictionmin=1"}'
response = http.request(request)

import requests
from requests.auth import HTTPBasicAuth
r = requests.post("https://api-us.mouseflow.com/websites/{website-id}/views", '{"name": "New View", "query": "frictionmin=1"}',
    auth=HTTPBasicAuth("my@email.com", "token1234"))

<?php
    $curl = curl_init("https://api-us.mouseflow.com/websites/{website-id}/views");
    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 => '{"name": "New View", "query": "frictionmin=1"}'
    ));
    $return = curl_exec ($curl);
    curl_close ($curl);     
?>

URL url = new URL("https://api-us.mouseflow.com/websites/{website-id}/views");
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\": \"New View\", \"query\": \"frictionmin=1\"}");
wr.flush();
int HttpResult = conn.getResponseCode();

$.ajax({
    url: "https://api-us.mouseflow.com/websites/{website-id}/views",
    dataType: "json",
    contentType: "application/json",
    type: "POST",
    headers: {
        "Authorization": "Basic " + btoa("my@email.com:token1234")
    },
    data: JSON.stringify({"name": "New View", "query": "frictionmin=1"})
}).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}/views",
        new StringContent("{\"name\": \"New View\", \"query\": \"frictionmin=1\"}"));
    var jsonString = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(jsonString);
}

Edit a filtered view

Existing filtered views can be edited by modfiying the properties above.

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

Delete a filtered view

Filtered views can also be deleted

DELETE /websites/{website-id}/views/{view-id}

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.

Introduction

Authentication

Data formats

Date time format

Time spans

Country codes and languages

Country codes

Languages

Common arguments in endpoints

Websites

Website list

Get all available websites in the account.

Properties

Re-ordering the list

Website detail

Get details about one website

Properties

Create new website

Properties - Request

Change recording status

Stop recording visitors on a website

Start recording visitors on a website

Update website details

Recordings

Recording list

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

Properties

Optional arguments (appended to the querystring)

Recording detail

Get details of a recording, including each recorded pageviews

Properties

Properties - pageViews

Properties - annotations

Star

Star a recording

Unstar a recording

Tags

Get the list of tags used on a website

Properties

Arguments

Add a tag to a recording

Remove a tag from a recording

Variables

Get the list of variable keys used on a website

Edit the list of custom variables on one recording

Remove custom variables

Sharing

Start sharing a recording

Stop sharing a recording

Watched

Mark a recording as watched

Mark a recording as unwatched

Delete

Delete a recording

Heatmaps

Heatmap page list

Get the list of pages, including visitor statistics

Arguments

Properties

Heatmap page details

Required arguments (appended to the querystring)

Properties

Page url list

Get the list of page urls

Arguments

Properties

Sharing

Start sharing a heatmap

Stop sharing a heatmap

Funnels

Funnel list

Get the list of funnels

Properties

Funnel report

Get the full funnel report

Properties

Create a funnel

Properties

Edit a funnel

Properties