The white label API allows you to manage your users, websites, and goals programmatically, without having to login to your account. You can use this to fully automate the management of your white label service from within your own web application, which will save your all sorts of time.

"hotstatz.com" is used as an example white label domain throughout this documentation. It is not a real website, and is only used for the sake of a realistic example.

White label API requests should be sent to the path /api/whitelabel/ on your white label domain, for example, http://hotstatz.com/api/whitelabel/ ... Of course, you need to send some parameters with any request, which are documented below.

Responses to API requests
Managing user accounts
Managing websites
Moving sites between users
Find existing username or user ID
Monitoring traffic usage
Managing goals
Error codes and descriptions
Example code & implemenation
Other notes

Responses to API requests

Before we get into making requests to the API, you need to know that you will always receive a response to all requests, and this response needs to be processed by your code. Responses are plain text - for such a simple exchange of data, there's just no need to use something like XML and make things ten times as complicated. As the example code demonstrates, plain text makes things easy.

The first line of any response will either be OK or NOK. OK means the request was successfully processed, NOK means there was an error. NOK responses are always multi-line as they include the error code and description. OK responses have additional lines when you are creating something, as we need to pass back information to you (user_id, site_id, etc). When you update or delete an existing item, you'll just get OK and nothing else. Example responses for each type of request to the API are included within the section detailing that type of request.

Each line has a "new line" character at the end of it. You need to strip off the new line character from the end of each line before processing it! Otherwise you may encounter errors on your end. If you are using PHP, you can run each line through trim, which will strip off new lines as well as other undesirables like leading and trailing spaces. The example code section shows how to do this.

Managing user accounts

Red parameters are required for all requests, all others are optional except as noted.

auth

Similar to the stats API, every request to the white label API must be authenticated by a key that is unique to your white label account. Your API key is available on the front page of your white label administration area. Send it to the API as "auth", e.g. auth=123.

type

Type tells the API what type of request you are making, which you'll want to declare as type=user here.

username

Required when creating a new user, otherwise optional. Every account must have a username, and it must be unique. The white label database is shared among all accounts, so there may be conflicts. If the username is already registered, an error will be returned. We recommend adding a prefix to all of your usernames to avoid any potential problems. For example, a username of "billy" could become "hotstatz-billy".

password

A password is not required, but anyone can log into an account just by typing in the username, if that account does not have a password. Of course, they would still have to know the username by some means, which is unlikely.

email

An email address is optional. The only reason an email address is handy is for the automated password reset feature. However, if you don't plan to have your users logging in to your white label directly, this is not necessary.

name

The user's real name. This is only used to greet them in any emails that may be sent to them. The only email that would ever be sent to your users from our system would be for a password reset.

logo

URL for a custom logo for this user, e.g. http://your-server.com/this-users-logo.gif. The file must be stored on your own server, or one you have direct access to. The user will see this logo on all pages of your white label when they are logged in.

css

URL for a custom CSS file for this user, e.g. http://your-server.com/this-users-css.css. The file must be stored on your own server, or one you have direct access to. This custom CSS will override your global custom CSS.

user_id

Include the user_id with your request to update an existing user with the information you are sending, or to delete a user. If no user_id is provided, a new user account is created with the supplied information.

delete

When you want to delete a user, include "delete=1" with your request. user_id will also be needed. Deleting a user also deletes all websites that belong to that user.

onsitestats

Enable on-site analytics for this user account by including "onsitestats=1" with your request. By default it is disabled for all accounts, although it is a great feature, so you should use it!

Example requests

Create a new user:
http://hotstatz.com/api/whitelabel/[email protected]
Update email address of existing user:
http://hotstatz.com/api/whitelabel/[email protected]&user_id=424
Delete a user:
http://hotstatz.com/api/whitelabel/?auth=123&type=user&user_id=424&delete=1

Example OK responses

When you create a new user, we'll pass back their user_id from our database. You'll need to store this value on your end in order to register new sites for this user or to update/delete this user later on.

Successful creation:
OK
424
Successful update or deletion:
OK

Example NOK responses

All error codes and descriptions are listed here, but an example NOK response for a new user might be...

NOK
5
This username is already registered.

Managing websites

Red parameters are required for all requests, all others are optional except as noted.

auth

Similar to the stats API, every request to the white label API must be authenticated by a key that is unique to your white label account. Your API key is available on the front page of your white label administration area. Send it to the API as "auth", e.g. auth=123.

type

Type tells the API what type of request you are making, which you'll want to declare as type=site here.

user_id

Required when registering a new website, otherwise not. All sites must be attached to a user_id within your white label account. If you do not plan to offer accounts to your users, but instead simply use our stats API or iframes to display stats to a user, we recommend creating a single dummy account from the white label administration page and hard coding the user_id into your application. Then you will simply attach all new sites to this user.

domain

Required when registering a new website, otherwise optional. We need to know what domain this traffic will be for. All incoming traffic is validated against what you have registered so it's important this is accurate. We don't need the http:// or any path information, just the domain name, e.g. "google.com".

nickname

If you want this site to show up in this user's account as something other than just the domain name, send in a name here, such as "Your website". Be sure to URL encode.

mirrors

If there is more than one domain name that will be tracked for this entry, include the extra domains in this parameter as a comma-seperated string. For example "yahoo.com,msn.com".

domain_validate

Domain validation is on by default, which will restrict tracking to just the domain and any mirrors registered in our database (sub-domains are automatically supported). If you wish to turn this off, pass in a value of "0".

timezone

Time zone will default to USA Pacific Standard Time (GMT -0800) unless specified here. You can send in a float value anywhere between -12.0 and 12.0, representing the timezone relative to GMT. USA time ranges from -8 (pacific) to -5 (eastern). You probably don't have this information about your users, in which case we'd recommend sending in your timezone information instead, as a safe default. Chances are better that your users are in your timezone rather than any other time zone.

dst

Daylight savings time. Possible values are "usa", "eu", "1", or "0". (eu refers to all countries in the European Union). If you specifiy usa or eu, we automatically turn DST on and off at the appropriate times for these countries. For all other countries, this feature must be manually turned on and off, which is specified as 1 and 0, respectively. Again, we recommend sending in your own DST settings if you don't know the right one for this user/site.

osa

On-site Analytics widget. Possible values are "0" (off), "1" (on, bottom right (default)), or "2" (on, bottom left). Invalid options will be ignored and discarded.

heatmap_layout / heatmap_width

Heatmap configuration. If you know the layout of this site, you can specify it here so it doesn't need to be done manually later, and heatmap data should start logging immediately. Possible values (invalid options will be ignored and discarded):

heatmap_layout - center, left, right, liquid, or "blank" (no value)
heatmap_width - 800, 1024, 1200, 1600, 2000, liquid -- take the "max width" pixel value of your site and round it up to the closest value here, or use "liquid" if there is no max.

site_id

Include the site_id with your request to update an existing site with the information you are sending, or to delete a site. If no site_id is provided, a new website is created with the supplied information.

delete

If you want to delete this site, include "delete=1" with your request. user_id and site_id will also be needed.

Example requests

Create a new site:
http://hotstatz.com/api/whitelabel/?auth=123&type=site&user_id=424&domain=awesome.com&timezone=-8&dst=usa
Update a site's timezone:
http://hotstatz.com/api/whitelabel/?auth=123&type=site&site_id=500&timezone=-5
Delete a site:
http://hotstatz.com/api/whitelabel/?auth=123&type=site&site_id=500&delete=1

Example OK responses

When you create a new site, we pass back to you the site_id, sitekey, database server, and admin sitekey on lines 2, 3, 4, and 5, respectively. The site_id and database server are needed to construct the tracking code you'll be putting on this site's pages. The sitekey will be needed to use the stats API or iframe functionality with this site. The admin sitekey is for manual data logging - if you don't plan to use that feature, you don't need to worry about logging it.

Successful creation:
OK
500
ad9123kjbb3fd
db3
ad9123kjbb3fdad9123kjbb3fdad9123kjbb3fd

Successful update or deletion:
OK

Example NOK responses

All error codes and descriptions are listed here, but an example NOK response for a new site might be...

NOK
13
Invalid domain.

Moving sites between users

Red parameters are required for all requests, all others are optional except as noted.

auth

Similar to the stats API, every request to the white label API must be authenticated by a key that is unique to your white label account. Your API key is available on the front page of your white label administration area. Send it to the API as "auth", e.g. auth=123.

type

There are three options here:

• type=add_user_to_site - Assign a new user to an existing site as either an admin or as read-only access. To assign the user as an admin, add an additional parameter, &admin=1, to your request. Otherwise, they will default to read-only access.
• type=remove_user_from_site - Remove a user's access to a site
• type=move_site_to_user - Move a site from one user account to another. Any existing user(s) assigned to this site will have their access removed, and this user will become the administrator of the site. This is useful as a shortcut when an existing site has one user, and you want to have another user own the site. Instead of sending an add_user_to_site request for the new user, and a remove_user_from_site request for the old user, you can just us this to make one single request.

user_id

The user ID that you are applying this action to.

site_id

The site ID that you are applying this action to.

Example requests

Add a user to a site with read-only access:
http://hotstatz.com/api/whitelabel/?auth=123&type=add_user_to_site&user_id=800&site_id=500
Add a user to a site with full admin access:
http://hotstatz.com/api/whitelabel/?auth=123&type=add_user_to_site&user_id=800&site_id=500&admin=1
Remove a user's access to a site:
http://hotstatz.com/api/whitelabel/?auth=123&type=remove_user_from_site&user_id=800&site_id=500
Move a site to one user (this removes access from all other users, and makes this user the admin):
http://hotstatz.com/api/whitelabel/?auth=123&type=move_site_to_user&user_id=700&site_id=500

Example OK responses

Since you already have the user ID and site ID, no data is passed back to for a successful request, other than "OK". OK


Example NOK responses

All error codes and descriptions are listed here, but an example NOK response for a new site might be...

NOK
26
Every site must have at least one assigned administrative user. This user is currently the only admin of this site, and hence cannot be removed until another admin has been assigned.

Find existing username or user ID

Red parameters are required for all requests, all others are optional except as noted.

auth

Similar to the stats API, every request to the white label API must be authenticated by a key that is unique to your white label account. Your API key is available on the front page of your white label administration area. Send it to the API as "auth", e.g. auth=123.

type

There are two options here:

• type=get_user_id - If you have the username (string) and want to find the numeric user ID.
• type=get_username - If you have the numeric user ID but want to find the username (string) of the account.

user_id / username

For type=get_user_id requests, you must pass in the 'username' parameter. Note: You can use either their email address or their username here.

For type=get_username requests, you must pass in the 'user_id' parameter.

Example requests

Get the numeric user ID for a username:
http://hotstatz.com/api/whitelabel/?auth=123&type=get_user_id&username=billy
Get the username for a numeric user ID:
http://hotstatz.com/api/whitelabel/?auth=123&type=get_username&user_id=800

Example OK responses

Get user ID: OK
800
Get username: OK
billy

Example NOK responses

All error codes and descriptions are listed here, but an example NOK response for a finding a user_id might be... NOK
2
Invalid username.

Monitoring traffic usage

Red parameters are required for all requests, all others are optional except as noted.

auth

Similar to the stats API, every request to the white label API must be authenticated by a key that is unique to your white label account. Your API key is available on the front page of your white label administration area. Send it to the API as "auth", e.g. auth=123.

type

There are two options here:

• type=traffic - Outputs the total daily average page views for all sites in your white label.
  
• type=traffic_per_user - Outputs the total daily average page views for each user account. Note that the sum of values here may exceed the output of type=traffic because sites may be owned by more than one user account.

date

Use this to specify what date / range you want the traffic to be based on. If not specificed, we'll return the traffic from 7 days ago (e.g. same day last week) rather than 'today', since 'today' won't represent a full day's traffic. '7-days-ago' however should accurately reflect the traffic you should expect for 'today', barring any high traffic sites added or deleted in the last week.

Date ranges are only supported up to a maximum of 7 days, for performance reasons. Relative and specific date ranges are supported, as documented in the analytics API docs. Examples: 'yesterday', '3-days-ago', 'last-week', '3-weeks-ago', etc.

Example requests

Total daily average page views for (default) the same day last week: http://hotstatz.com/api/whitelabel/?auth=123&type=traffic
Total daily average page views for yesterday: http://hotstatz.com/api/whitelabel/?auth=123&type=traffic&date=yesterday
Total daily average page views for each user for (default) the same day last week: http://hotstatz.com/api/whitelabel/?auth=123&type=traffic_per_user
Total daily average page views for each user for yesterday: http://hotstatz.com/api/whitelabel/?auth=123&type=traffic_per_user&date=yesterday

Example OK responses

Beyond the first line 'OK' or 'NOK', the second line will contain the date range that the data is from. We output the date in case you specify an invalid date range, e.g. something longer than 7 days, so that you know the actual date(s) that the data is from.

For type=traffic, the third line will be a number representing your total daily average page views for all sites combined.

For type=traffic_per_user, the third line will be a comma-separated string in this format:
user_id:pageviews,user_id:pageviews, ...

You'll want to explode this string by the commas, then loop through and explode each remaining value by the colons, which will give you the user_id and daily average page view volume.


type=traffic&date=last-7-days OK
2024-11-15,2024-11-21
55
type=traffic_per_user&date=last-7-days OK
2024-11-15,2024-11-21
1:66,10:3,35:7

Example NOK responses

No errors are returned from these requests. The only possible 'error' would be an invalid date range but we'll fix that automatically and report the date represented back to you, as documented above.

Managing goals

If you are not familiar with our goal system, please go to the goal setup page for any site you have access to. The setup page explains the goal system and parameters in much greater detail than here.

Goal parameters are declared via a goal array in the URL, e.g. goal[name]=Hello&goal[url]=/hello
Red parameters are required for all requests, all others are optional except as noted.

auth

Similar to the stats API, every request to the white label API must be authenticated by a key that is unique to your white label account. Your API key is available on the front page of your white label administration area. Send it to the API as "auth", e.g. auth=123.

type

Type tells the API what type of request you are making, which you'll want to declare as type=goal here.

site_id

The site ID that this goal belongs to.

goal[name]

Required when creating a new goal, otherwise optional. The name of the goal. This will show up in the stats reports. Every goal for each site must have a unique name.

goal[url]

Required when creating a new goal, otherwise optional. The URL of the goal page. If it's for the registered domain, you should only include the path, e.g. goal[url]=/goal/page?goal=1. For goals on outbound links, downloads, or sub-domain pages, include the domain, e.g. goal[url]=http://outbound-link.com/some/page

goal[funnel_type]

Goals support four types of funnels: URLs, seaches, referring domains, and campaigns. Through the API, the campaigns option is not available. For the other types, specifiy as 'path', 'search', or 'domain'.

goal[funnel]

Set the funnel string here, e.g. "/funnel/page" for a path, or "google.com" for a domain.

goal[revenue]

If this goal has a specific revenue value, you can include it here. No commas or symbols, just the numbers, e.g. 2.50.

goal[cost]

If this goal has a specific cost value, you can include it here. No commas or symbols, just the numbers, e.g. 2.50.

goal[manual]

If this is a "manual" goal. 1 (yes), 0 (no).

goal[more_than_once]

If this goal should support the "more than once" option. 1 (yes), 0 (no).

goal[id]

If you are updating an existing goal, specify the goal ID here. Otherwise, it is assumed you are creating a new goal.

delete

If you want to delete a goal, include this parameter as delete=1. goal[id] is also required.

Example requests

Remember to URL encode all values. Examples here are shown without encoding to make them easier to understand.

Create a new goal:
http://hotstatz.com/api/whitelabel/?auth=123&type=goal&site_id=500&goal[name]=Hello&goal[url]=/hello&goal[revenue]=2.50
Update a goal's name
http://hotstatz.com/api/whitelabel/?auth=123&type=goal&site_id=500&goal[id]=5&goal[name]=Goodbye
Delete a goal:
http://hotstatz.com/api/whitelabel/?auth=123&type=goal&site_id=500&goal[id]=5&delete=1

Example OK responses

When you create a new goal, we pass back to you the goal ID in our database. You will need to store this on your end if you want to be able to update or delete goals via the API at a later time.

Successful creation:
OK
5

Successful update or deletion:
OK

Example NOK responses

All error codes and descriptions are listed here, but an example NOK response for a new goal might be...

NOK
20
Invalid goal URL.

Error codes and descriptions

When you receive a NOK response, you will also receive an error code # on the second line, and an error description on the third line. All errors codes and (briefened) descriptions are listed here.

Example code and implementation

You'll need programming experience to implement the white label API into your own website, but here is a simple example to get you started. We'll also cover how to construct the tracking code to put on a site after it has been registered.

In PHP, we recommend using the file function for API requests, as it will both send the request to the API, and put the response in an array, with each key representing a line from the response. For example, here's how you could register a new user:

<?php
// make the request and assign the response to some variable
$e = file( "http://hotstatz.com/api/whitelabel/?auth=123&type=user&username=billy" );

// if $e has no value, either file() failed or our API is broken
if( !$e ) {
    mail( "[email protected]", "API error", "API_REQUEST_URL, request failed!" );
    exit;
}

// loop through and trim each line to remove the new line character at the end
foreach( $e as $key => $value ) $e[$key] = trim( $value );

// test for OK or NOK response and react accordingly
if( $e[0] == "OK" ) {
    // $e[1] is the user_id we created, which you need to store on your end for future requests
    mysql_query("update users set external_user_id = '$e[1]' where id = 'your_user_id' limit 1");
}
else {
    // $e[1] will be the error code, and $e[2] will be the error description.
    // you can program in your own logic to react the different error codes,
    //   or simply email yourself with the details of the error for debugging (or both)
    mail( "[email protected]", "API error", "API_REQUEST_URL, $e[1], $e[2]" );
}
?>

Tracking code

You'll need to put the appropriate tracking code on the website that you want to be tracked. The tracking code for each site is unique, as it contains the site's ID. A template of our tracking code is shown below:

<script async src="//YOURWHITELABEL.COM/SITEID.js"></script>
<noscript><img height=1 width=1 src="//YOURWHITELABEL.COM/SITEIDns.gif"></noscript>
Replace "YOURWHITELABEL.COM" with your actual white label domain, and "SITEID" with the site ID returned by the API.

Other notes

Always URL encode all values. It is good practice to do so, even if you think some or all values don't need to be encoded.