The Bonusly RESTful JSON API is a great way to programmatically manage parts of your organization's account. You can use it to roll your own solutions, gather data and more. Our API is easy to integrate with any stack or programming language. 

In this article, we'll walk through generating an API key and making a request to the API using your key. This article assumes some familiarity with RESTful APIs, including making requests, setting headers and interpreting JSON responses. 

Getting an API access token

The first step to using the Bonusly API is to get an API access token. You can generate an API access token from this page. Simply click on the link that says "Create New API Access Token" to get a new access token. 

Note that we will not display read/write access tokens more than once, so be sure to store it in a safe place. If you lose your token, you will need to generate a new one. 

A note on admin access tokens

There are two kinds of API access tokens: administrator and normal user. With administrator access tokens, you're able to perform a range of administrator-only tasks, like managing users, company settings and bonuses from all users. 

All API keys created with an administrator account are administrator keys. Trying to access certain endpoints with a normal user's key will return a 403 error.  

Sending your access token to the API 

All of our API endpoints begin with https://bonus.ly/api/v1/ . You can pass along your access token as a query parameter or as an HTTP header. We recommend using HTTP headers for security. 

Sending the access token with GET

To send your access token as a query parameter, simply append it to the URL using the parameter access_token , e.g. https://bonus.ly/api/v1/users/me?access_token=0123456789abcdefghijklmnopqrstuv

Sending the access token as an HTTP header

To send your access token as an HTTP header, set the Authorization  header to Bearer API_KEY . Be sure to include Bearer , e.g. Authorization: Bearer 0123456789abcdefghijklmnopqrstuv .

Making a request to the API

You can read about our various endpoints in our Gelato documentation here. We have endpoints for analytics, bonuses, company information, redemptions, rewards and users. 

As an example, let's view my own user information. To do this, I'll send a GET request to the /users/me  endpoint. I'll send my API key as a GET parameter. 

I send a GET request to https://bonus.ly/api/v1/users/me?access_token=0123456789abcdefghijklmnopqrstuv . The request was successful. The API returns the following JSON, truncated here for brevity: 

{
    "success": true,
    "result": {
        "id": "0123456789abcdefghijklmn",
        "short_name": "Armando Leon",
        "display_name": "Armando Leon",
        "username": "armando.leon",
        "email": "armando@bonus.ly",
        ...
    }
}

You should see a similar output with your own information if your request to the /users/me  endpoint is successful. You can read our full documentation about the me endpoint here

Next steps: full API documentation and API explorer

You can access our full API documentation and use our API explorer on Gelato at bonusly.gelato.io. We can't wait to see what you build!

Still need help with our API? Send us an email at support@bonus.ly and we'll be glad to help you out. 

Did this answer your question?