All Collections
Getting Started with Bonusly
API:
Getting started with the Bonusly API
Getting started with the Bonusly API

Bonusly's RESTful JSON API lets you programmatically manage parts of your organization's account, including users, bonuses and more.

Adrianne Hipsher avatar
Written by Adrianne Hipsher
Updated over a week ago

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. *You must have either Global Permissions or Tech Permissions to access this feature. You can learn more about enabling admin permissions here

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 API documentation. 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": "[email protected]",
        ...
    }
}

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 doc.bonus.ly. We can't wait to see what you build!


Questions? Send us a note to [email protected]; we'd be happy to help!

Was this article helpful? Let us know by rating it below with an emoji and sharing your feedback!

Did this answer your question?