Client API reference


To install Volument, paste the following code snippet anywhere before your website's closing </body> tag:

<script src="https://volument.com/v1/volument.js"></script>

Please replace your-token with your token that you'll get after signing up for the service.

After the snippet is in place, Volument automatically tracks your visitors and how they consume your content.

Check that it works

After you have all in place, we recommend you to run volument.debug(message) on your browser's console. If everything works, you'll see a response to the optional message you provided.

Tracking conversions

In order to optimize traction you must tell Volument about the different ways your visitors can convert to a higher level on the customer relationship. For example:

// visitor posted their contact information

// visitor subscribed to a paid plan


Call this method when the visitor converts to a customer without handing any money, for example, when subscribing to a recurring plan. This method is an alias to volument.pay(0) when the visitor hands the credit card information without being charged.


Call this method when the visitor becomes a “lead.“ That is: they hand their contact information by joining the mailing list or via “contact us” form. Essentially you'll have a way to get them back to the site by email or by phone improving the retention and conversion metrics further down the customer journey.


Call this method when the visitor sign-up for a free trial or becomes a user of your product, typically through an invitation.


Call this method when you can uniquely identify the visitor with some ID. Uniqueness is strict: no two users in your environment may share the same ID. We use this identity for two important reasons with regards to conversion optimization:

  1. When the visitor uses different devices to browse your website, Volument uses this identity to merge those devices into a single account.
  2. We also use this identity to measure virality by knowing when the invited visitors become members. Viral metrics include the acceptance rate, viral cycle time, and the viral coefficient or “k-factor.“

The required userId parameter is a case-sensitive string and must be fewer than 48 characters.

Do not identify users based on an anonymous ID, random ID, session ID, or any value that might change. Volument explicitly denies all attempts to use an email address as an identifier since we don't store such sensitive information on our system. Another reason is that the email address is something that can change in the future.


Call this method when the visitor invites her friends or other associates to your product contributing to the viral growth of your product. The more visitors invite, and the sooner they invite means stronger viral metrics and higher traction. The viral coefficient is the biggest single contributor to traction.

The required userId parameter is the ID of the invited person. We use this ID to calculate virality when the peers identify themselves with the same ID.


Call this method when the visitor hands their credit card and becomes a paying customer. The amount is stored on our databases, but not yet shown in the reports.

Single-page applications

If your site is a single-page application (SPA), or is built around pushState (PJAX or Turbolinks) you can setup Volument as follows:

<script src="https://volument.com/v1/volument.js"></script>
<script>volument({ token: 'your_token', spa: true })</script>

And every new page view needs to be monitored as follows:

document.addEventListener('turbolinks:load', function() {


Starts monitoring a newly loaded page. Volument checks for every mouse movement and keyboard event to know whether the visitor is focusing on the content and not doing anything else.

The optional path argument identifies the page, and it is displayed on all the analytical views. If no path is given Volument uses location.pathname as the path name.

The previously monitored page, if any, is being tracked to our servers. The page view information is automatically tracked when the visitor closes the browser.

Custom paths

Sometimes your paths look like this: /products/d0819be03b83ec1e5, where the last part is a unique id and all these pages use a similar layout and design.

On this case it makes sense to group these pages togeter in order to get enough data for analysis. You can do it as follows:

<script src="https://volument.com/v1/volument.js"></script>

// enabling "manual" means that we construct paths ourselves
volument({ token: 'your_token', manual: true })

// modify: /product/333993 --> /product
volument.route(location.pathname.slice(0, 2).join('/'))

If you only want to do the above one some specific area of the site, such as /products/*, you must add some JavaScript logic. For example:

<script src="https://volument.com/v1/volument.js"></script>
volument({ token: 'your_token', manual: true })

// truncate paths only under "products"
var path = location.pathname,
  items = path.split('/')

if (items[1] == 'products') path = items.slice(0, 2).join('/')

// track the altered path