Bonusly

Basics

URL Structure

API requests start with:

https://bonus.ly/api/v1/

For example:

https://bonus.ly/api/v1/bonuses

Authentication

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 https://bonus.ly/api.
  • 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.

http://bonus.ly/api/v1/bonuses?access_token=API-KEY

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 http://bonus.ly/api

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.

RSS

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: https://bonus.ly/api/v1/bonuses.atom?access_token=API-KEY

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

Responses

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

Success:

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

or

Failure:

{
  "success": false, 
  "message": "*message*"
}

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