URL Structure

API requests start with:

For example:


Authentication to the API is controlled using an access token. You may send your access token as a query param or HTTP header.

Creating an API token

  • Go to the API page at
  • Click the "Create New API Access Token" link which will take you to a page titled "New Access Token".
  • Give your token a label so you can easily keep track of different tokens
  • Decide if you want your token to be read-only
  • Click "Create" at the bottom of the screen
  • You should be taken back to your settings with a message at the top of the screen that says "New Access Token Created: [your access token here]". You'll need to copy your token to a secure location since you will not be able to see it again.

Authenticating with your API token

To send the token as a query param set the access_token value in the url.

To send as an HTTP header set the Authorization header.

Authorization: Bearer API-KEY

We recommend sending the token as an HTTP header for security reasons.

Your authentication access token can be found at

Making a request without an access token or with a bad access token will result in a 401 - bad or missing access token error. (The exception is the /sessions endpoint which is used to get a user's access token)

Your Application Name

You can set your application name by either setting the HTTP_APPLICATION_NAME HTTP header or setting an APPLICATION_NAME cookie.

Setting the application name will set the via property of every bonus created by that application to the application name.

Rate Limiting

Requests are rate limited to ensure that an excessive number of requests are not made within a short period of time. If you go over the rate limit, your requests will be denied until the limit resets.


ATOM Extension

Bonuses -

You can get a list of bonuses as an ATOM RSS Feed by adding the extension .atom to the normal bonuses 'Index' API call.

For example:

Once making a .atom RSS call, you can add the parameter navori=true to get an xml response with formating for Navori.


Calls to the Bonusly API generally return a JSON in the format of either:


  "success": true, 
  "result": {*results*}



  "success": false, 
  "message": "*message*"

Possible results (successes) and messages (errors) are listed for each endpoint.

Giving a Bonus from the Company

You can give a bonus from the company via our API if you are a Bonusly Pro subscriber. This is functionally equivalent to giving a bonus from a company bonus fund. To do this:

  1. Get a list of all the bot user email addresses via the users index endpoint:
  2. Create a bonus as usual with the added param giver_email=[bot_email_address]. Note that you must have an administrator’s API key to use the giver_email param.

Giving a bonus from the company requires you to create a bot user beforehand via the API or by creating a company bonus fund. You must be an administrator for a Bonusly Pro account to perform either of these tasks.

You can create a bot user via the API by creating a user with "user_mode": "bot". You must be an administrator for a Bonusly Pro account to create a bot via the API. Read more about creating a user here.

You can also create a company fund. To create a company fund, you must be an admin for a Bonusly Pro account. You can view, create and manage your funds from the manage funds page.