Let’s be honest: manually doling out kudos, points, and peer shoutouts is nobody’s idea of a good time. If you’re managing a team or running HR ops, you want recognition to just work—without reminders, spreadsheets, or “Did I forget someone again?” guilt. If you’ve landed here, you probably use Bonusly and want to automate more of the tedious stuff. Good call.
This guide is for anyone who’s sick of repetitive recognition tasks and wants to hook Bonusly into their existing systems—without falling into a rabbit hole of vendor hype or half-baked scripts. We’ll walk through real steps, honest pitfalls, and actionable code. Let’s get your time back.
1. Know What the Bonusly API Can and Can’t Do
Before you go wild building automations, set your expectations. The Bonusly API is solid, but it’s not magic. Here’s what it covers:
What you can automate: - Giving recognition (a.k.a. making “bonuses”) - Listing users, their balances, and activity - Fetching reward catalogs and company data - Some admin actions (like creating users, but only via certain plans)
What you can’t automate (as of early 2024): - Custom triggers for recognition (the API works, but triggers are up to your system) - Advanced reporting—API data is raw, not pretty - Real-time notifications (webhooks are limited)
Pro tip: If you’re hoping for full “If This Then That” (IFTTT)-style automation, you’ll have to write some glue code. The API is a tool, not a full solution.
2. Get Your API Access in Order
You’ll need an API key with the right permissions. Here’s how to get it:
- Log into Bonusly as an admin.
- Go to
Integrations>API. - Generate an API key (choose “Admin” or “User” scope based on what you’ll automate).
- Save this key somewhere safe. (Seriously! Treat it like a password.)
Watch out: API keys give broad access. If you leave one in a public repo, anyone could drain your company’s recognition budget or access user info.
3. Map Out What to Automate (Don’t Skip This)
It’s tempting to just start coding. But automating the wrong thing wastes time. Ask yourself:
- What’s the pain point? (e.g., monthly birthdays, project launches, peer-to-peer, manager-to-team)
- What systems should trigger recognition? (HRIS, Slack, Jira, email, etc.)
- Who should get recognized, and why? (Don’t automate generic “Great job!” spam.)
Example automations people actually use: - Automatically give birthday points based on your HR system - Send bonus points when a Jira ticket is closed by a teammate - Reward sales reps when deals close in Salesforce
Don’t try to automate everything at once. Start with one workflow.
4. Make Your First API Call
Let’s get real: most official API docs are dry, and Bonusly’s is no exception. Here’s how you actually test if your key works.
Quick test with curl:
sh curl -H "Authorization: Bearer YOUR_API_KEY" https://bonus.ly/api/v1/users/me
You should see your user info in the response. If you get an error, double-check your key and permissions.
Honest gotcha: The API rate limits aren’t super high. Don’t run massive batch jobs or you’ll get throttled.
5. Automate a Simple Recognition Workflow (Birthday Example)
Let’s walk through a practical example: giving recognition automatically for employee birthdays.
Assumptions: - You use an HR system (or spreadsheet) with employee names and birthdays. - You want to post a Bonusly recognition on birthdays. - You know how to run a daily script (e.g., with cron or a serverless scheduler).
Step-by-step:
a. Gather Employee Data
Export a CSV or query your HR system for names, Bonusly user emails, and birthdays. Example CSV:
name,email,birthday Alice Smith,alice@company.com,1990-06-12 Bob Lee,bob@company.com,1985-06-13
b. Find Bonusly User IDs
You need user IDs, not just emails. Here’s a script to fetch all users and match by email (Python example):
python import requests
API_KEY = "YOUR_API_KEY" headers = {"Authorization": f"Bearer {API_KEY}"}
def get_users(): resp = requests.get("https://bonus.ly/api/v1/users", headers=headers) resp.raise_for_status() return resp.json()["result"]
users = get_users() email_to_id = {u["email"]: u["id"] for u in users}
c. Check for Today’s Birthdays
Loop through your employee list, check if today matches their birthday (ignore the year).
python from datetime import datetime
def is_birthday(birthday_str): today = datetime.today() month_day = birthday_str[5:] # 'MM-DD' return today.strftime('%m-%d') == month_day
d. Send Recognition with the Bonusly API
For each birthday person, make a POST request:
python def give_bonus(user_id, message): payload = { "user_id": user_id, "reason": message, "amount": 10 # Points to give } resp = requests.post("https://bonus.ly/api/v1/bonuses", headers=headers, json=payload) resp.raise_for_status() return resp.json()
Call it like:
python for row in employee_list: if is_birthday(row['birthday']): uid = email_to_id.get(row['email']) if uid: give_bonus(uid, f"Happy birthday, {row['name']}! 🎉")
Pro tip: Don’t go wild with emojis or generic messages. People can spot an automated “Happy birthday” a mile away. Add a little flavor or rotate messages if you can.
6. Monitor and Debug (Don’t Set and Forget)
Automations break. APIs change. People leave or join. Here’s what to watch for:
- API errors: Log failures and review them. Don’t swallow errors silently.
- Duplicate bonuses: Make sure you don’t send two recognitions for the same person in one day.
- Permission issues: If someone isn’t in Bonusly yet, your script will fail for them.
- Rate limits: If you bulk-import, slow down your requests.
Pro tip: Set up a simple daily summary (email, Slack) so you know if your automation ran or failed.
7. When to Say “No” to Automation
Not every recognition should be automated. Here’s what to skip:
- Genuine, personal shoutouts: The best recognition is thoughtful, not robotic.
- Performance-based bonuses: These often need context and nuance.
- Spammy “participation” points: If nobody cares, you’re just adding noise.
Automate the boring, predictable stuff. Leave the meaningful moments for humans.
8. Advanced Moves (Optional, Not for the Faint of Heart)
If you’re comfortable coding, you can get fancier:
- Integrate with Slack or Teams: Trigger recognition from chatbots or reactions.
- Custom triggers: Use Zapier, Make.com, or write your own webhook listeners.
- Analyze Bonusly data: Pull recognition data for custom reports (but expect some data cleaning).
But honestly, don’t overengineer. Most teams just need the basics working reliably.
9. Avoid These Common Mistakes
- Hardcoding usernames or emails: People change names, get married, or leave.
- Ignoring opt-outs: Some folks don’t want public attention. Respect that.
- Not testing with a sandbox account: Don’t spam your real team when testing.
10. Keep It Simple—And Iterate
You don’t have to build the “perfect” workflow on day one. Start with the most annoying manual task, automate just that, and see how it goes. If it saves time and people like it, add another. If not, scrap it and try something else.
Don’t buy into the hype that everything must be automated. Good automation is invisible and boring—which, in this case, is exactly what you want.
Now go make recognition work for you, not the other way around.