Bonusly

Analytics

Analytics Overview

{
  "count": 42,
Integer
  "user": {
  "user": { ... }
Object
    "id": "24abcdef1234567890abcdef",
String
    "short_name": "Bill",
String
    "display_name": "Bill",
String
    "username": "blumbergh",
String
    "email": "blumbergh@initech56313d8f1ba2397878000004.com",
String (Email)
    "path": "/company/users/56313d971ba23978780000c6",
String
    "full_pic_url": "http://bonus.ly/avatar/blumbergh.png",
String (Url)
    "profile_pic_url": "http://bonus.ly/avatar/blumbergh.png",
String (Url)
    "first_name": "Bill",
String
    "last_name": "Lumbergh",
String
    "last_active_at": null,
String (Date-time)
    "external_unique_id": "foo",
String

Unique identifier from external service

    "budget_boost": 0,
Integer
    "user_mode": "normal",
String
    "country": "US",
String
    "time_zone": "America/New_York",
String
    "*custom_property_name*": "*custom_property_value*",
String

Use the form property_name=property_value

    "can_give": true,
Boolean
    "earning_balance": 80,
Integer

only returned to self or admins

    "earning_balance_with_currency": "80 points",
String

only returned to self or admins

    "lifetime_earnings": 80,
Integer

only returned to self or admins

    "lifetime_earnings_with_currency": "80 points",
String

only returned to self or admins

    "can_receive": true,
Boolean
    "giving_balance": 42,
Integer

only returned to self or admins

    "giving_balance_with_currency": "42 points",
String

only returned to self or admins

    "time_zone": "America/Los_Angeles",
String

only returned to self or admins

    "status": "archived"
String

Will return either 'archived' or 'active'.

  }
}

Trends | Index

Open in API Explorer
GET /analytics/trends

Example Request

Format:
curl --request GET \
  --url 'https://bonus.ly/api/v1/analytics/trends?access_token=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json'
require 'uri'
require 'net/http'

url = URI("https://bonus.ly/api/v1/analytics/trends?access_token=YOUR%20API%20KEY%20HERE")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'

response = http.request(request)
puts response.read_body
var http = require("https");

var options = {
  "method": "GET",
  "hostname": "bonus.ly",
  "port": null,
  "path": "/api/v1/analytics/trends?access_token=YOUR%20API%20KEY%20HERE",
  "headers": {
    "accept": "application/json"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();
import http.client

conn = http.client.HTTPSConnection("bonus.ly")

headers = { 'accept': "application/json" }

conn.request("GET", "/api/v1/analytics/trends?access_token=YOUR%20API%20KEY%20HERE", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://bonus.ly/api/v1/analytics/trends?access_token=YOUR%20API%20KEY%20HERE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://bonus.ly/api/v1/analytics/trends?access_token=YOUR%20API%20KEY%20HERE"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("accept", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Responses

200 Success Analytics Trending hashtags
[
  "items": {
  "items": { ... }
Object

Array Items

    "hashtag": "#teamwork",
String
    "count": "5"
String
  }
]
449 Data not ready Errors 449 - data not ready
{
  "message": "Data not ready. Please retry in 5 minutes"
String
}

Leaderboards | Index

Open in API Explorer
GET /analytics/leaderboards

This endpoint returns users ranked by the number of bonuses they've given or received. You can make your query more specific by requesting bonuses with a particular hashtag, bonuses given/received by users on a particular team, or bonuses given/received within a particular date range.

Example Request

Format:
curl --request GET \
  --url 'https://bonus.ly/api/v1/analytics/leaderboards?direction=given&hashtag=go-get-results&scope=59350a4af9f4ff084f7a0df6&start_date=19%2BMar%2B2017&end_date=01%2BJan%2B2018&access_token=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json'
require 'uri'
require 'net/http'

url = URI("https://bonus.ly/api/v1/analytics/leaderboards?direction=given&hashtag=go-get-results&scope=59350a4af9f4ff084f7a0df6&start_date=19%2BMar%2B2017&end_date=01%2BJan%2B2018&access_token=YOUR%20API%20KEY%20HERE")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'

response = http.request(request)
puts response.read_body
var http = require("https");

var options = {
  "method": "GET",
  "hostname": "bonus.ly",
  "port": null,
  "path": "/api/v1/analytics/leaderboards?direction=given&hashtag=go-get-results&scope=59350a4af9f4ff084f7a0df6&start_date=19%2BMar%2B2017&end_date=01%2BJan%2B2018&access_token=YOUR%20API%20KEY%20HERE",
  "headers": {
    "accept": "application/json"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();
import http.client

conn = http.client.HTTPSConnection("bonus.ly")

headers = { 'accept': "application/json" }

conn.request("GET", "/api/v1/analytics/leaderboards?direction=given&hashtag=go-get-results&scope=59350a4af9f4ff084f7a0df6&start_date=19%2BMar%2B2017&end_date=01%2BJan%2B2018&access_token=YOUR%20API%20KEY%20HERE", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://bonus.ly/api/v1/analytics/leaderboards?direction=given&hashtag=go-get-results&scope=59350a4af9f4ff084f7a0df6&start_date=19%2BMar%2B2017&end_date=01%2BJan%2B2018&access_token=YOUR%20API%20KEY%20HERE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://bonus.ly/api/v1/analytics/leaderboards?direction=given&hashtag=go-get-results&scope=59350a4af9f4ff084f7a0df6&start_date=19%2BMar%2B2017&end_date=01%2BJan%2B2018&access_token=YOUR%20API%20KEY%20HERE"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("accept", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Query Parameters

Name Type Required Description Example
direction String Optional

Specifies whether to rank users based on number of bonuses given, or number of bonuses received. Options are "received" (the default) or "given".

given
hashtag String Optional

If specified, only bonuses whose most relevant hashtag matches the given hashtag will be returned.

go-get-results
scope String Optional

Restricts users returned to those on a particular team, or in a particular part of your company. This argument may be either the id of a manager, eg. '59350a4af9f4ff084f7a0df6', or a set of custom properties in a JSON-encoded string, eg. '{"department":"product+development"}'.

59350a4af9f4ff084f7a0df6
start_date String Optional

If specified, only bonuses given on or after this date will be considered. Defaults to 30 days before the date of your query. Date format must be a two digit date followed by a space, a three letter month followed by a space, and a four digit year, eg. "19+Mar+2017".

19%2BMar%2B2017
end_date String Optional

If specified, only bonuses given on or before this date will be considered. Defaults to the date of your query. Date format must be a two digit date followed by a space, a three letter month followed by a space, and a four digit year, eg. "19+Mar+2017".

01%2BJan%2B2018

Standouts | Index (Deprecated)

Open in API Explorer
GET /analytics/standouts

This is a legacy endpoint that still functions but is no longer being updated, except for critical security fixes.

Example Request

Format:
curl --request GET \
  --url 'https://bonus.ly/api/v1/analytics/standouts?role=giver%2Freceiver&value=foo&limit=42&period=foo&custom_property_name=foo&custom_property_value=foo&access_token=YOUR%20API%20KEY%20HERE' \
  --header 'accept: application/json'
require 'uri'
require 'net/http'

url = URI("https://bonus.ly/api/v1/analytics/standouts?role=giver%2Freceiver&value=foo&limit=42&period=foo&custom_property_name=foo&custom_property_value=foo&access_token=YOUR%20API%20KEY%20HERE")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'

response = http.request(request)
puts response.read_body
var http = require("https");

var options = {
  "method": "GET",
  "hostname": "bonus.ly",
  "port": null,
  "path": "/api/v1/analytics/standouts?role=giver%2Freceiver&value=foo&limit=42&period=foo&custom_property_name=foo&custom_property_value=foo&access_token=YOUR%20API%20KEY%20HERE",
  "headers": {
    "accept": "application/json"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();
import http.client

conn = http.client.HTTPSConnection("bonus.ly")

headers = { 'accept': "application/json" }

conn.request("GET", "/api/v1/analytics/standouts?role=giver%2Freceiver&value=foo&limit=42&period=foo&custom_property_name=foo&custom_property_value=foo&access_token=YOUR%20API%20KEY%20HERE", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://bonus.ly/api/v1/analytics/standouts?role=giver%2Freceiver&value=foo&limit=42&period=foo&custom_property_name=foo&custom_property_value=foo&access_token=YOUR%20API%20KEY%20HERE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://bonus.ly/api/v1/analytics/standouts?role=giver%2Freceiver&value=foo&limit=42&period=foo&custom_property_name=foo&custom_property_value=foo&access_token=YOUR%20API%20KEY%20HERE"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("accept", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Query Parameters

Name Type Required Description Example
role String Optional giver%2Freceiver
value String Optional foo
limit Integer Optional

min: 1, max: 100

42
period String Optional foo
custom_property_name String Optional foo
custom_property_value String Optional foo

Responses

200 Success Analytics Leaderboard
[
  "count": 42,
Integer
  "user": {
  "user": { ... }
Object
    "id": "24abcdef1234567890abcdef",
String
    "short_name": "Bill",
String
    "display_name": "Bill",
String
    "username": "blumbergh",
String
    "email": "blumbergh@initech56313d8f1ba2397878000004.com",
String (Email)
    "path": "/company/users/56313d971ba23978780000c6",
String
    "full_pic_url": "http://bonus.ly/avatar/blumbergh.png",
String (Url)
    "profile_pic_url": "http://bonus.ly/avatar/blumbergh.png",
String (Url)
    "first_name": "Bill",
String
    "last_name": "Lumbergh",
String
    "last_active_at": null,
String (Date-time)
    "external_unique_id": "foo",
String

Unique identifier from external service

    "budget_boost": 0,
Integer
    "user_mode": "normal",
String
    "country": "US",
String
    "time_zone": "America/New_York",
String
    "*custom_property_name*": "*custom_property_value*",
String

Use the form property_name=property_value

    "can_give": true,
Boolean
    "earning_balance": 80,
Integer

only returned to self or admins

    "earning_balance_with_currency": "80 points",
String

only returned to self or admins

    "lifetime_earnings": 80,
Integer

only returned to self or admins

    "lifetime_earnings_with_currency": "80 points",
String

only returned to self or admins

    "can_receive": true,
Boolean
    "giving_balance": 42,
Integer

only returned to self or admins

    "giving_balance_with_currency": "42 points",
String

only returned to self or admins

    "time_zone": "America/Los_Angeles",
String

only returned to self or admins

    "status": "archived"
String

Will return either 'archived' or 'active'.

  }
]
400 Errors Errors 400 - errors
{
  "message": "foo"
String
}
400 Out of range Errors 400 - out of range
{
  "message": "Sorry, *min* ≤ *value* ≤ *max*"
String
}
449 Data not ready Errors 449 - data not ready
{
  "message": "Data not ready. Please retry in 5 minutes"
String
}