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!
