How to use Bunchball APIs to sync user data with external HR platforms

If you’ve ever tried to get your user data synced between your HR system and your gamification platform, you know it’s not always as plug-and-play as the sales pitch made it sound. This guide is for admins, IT folks, or developers who need to connect Bunchball’s APIs to an external HR platform—without losing a weekend in the process.

We’ll walk through how to pull and push user data, handle the rough edges, and avoid common dead ends. I’ll call out where things actually work well, where they’re a pain, and what you can safely ignore. No marketing fluff, just the steps you need.

Why Sync Bunchball with Your HR Platform?

Short version: You want your HR system (like Workday, BambooHR, or SAP SuccessFactors) and Bunchball to be in sync. That way, when someone joins, leaves, or changes roles, those updates show up automatically in your gamification system—no manual updates, no angry emails about missing badges.

If you don’t do this, you’ll end up with stale user lists, weird duplicate profiles, and a lot of wasted time fixing mistakes.

A few things to keep in mind: - Bunchball’s API isn’t always as modern as you’d hope. It works, but expect some clunky XML and older REST patterns. - Not every HR platform is friendly about letting you push or pull data. Sometimes, you’ll need a middleware or custom script. - “Sync” can mean different things—decide early if you want one-way or two-way sync, and what fields matter.

Step 1: Understand What Each System Can Actually Do

Before writing a line of code, get clear on what’s possible:

With Bunchball: - The core APIs for user management are the User Service and Batch Import. - You can create, update, or deactivate users. - Bunchball user IDs are usually not the same as your HR system’s IDs, unless you set it up that way.

With your HR platform: - Some HR systems have decent APIs (like Workday’s REST or BambooHR’s API). - Others only support scheduled CSV exports or old-school SFTP drops. - Figure out: Can you get a user list out easily? Can you get notified when users change? Can you push updates back in (if needed)?

Pro tip:
Don’t take the vendor’s word for it. Log in and poke around the docs or admin console yourself.

Step 2: Map Your User Data Fields

You can’t sync what you can’t match. Make a quick table—yes, actually write it down—of which fields you care about. The most common ones:

| HR Platform Field | Bunchball Field | Notes | |-------------------|-------------------|-------------------------| | Employee ID | externalId | Use this as your link | | First Name | firstName | | | Last Name | lastName | | | Email | email | Bunchball may require | | Department | custom1, custom2… | Map to custom fields | | Status | status | "active" or "inactive" |

Don’t try to sync everything—start with the basics. You can always add more fields later.

What to ignore:
Physical address, phone number, weirdly specific HR fields. Unless your gamification program needs them, skip them for now.

Step 3: Get API Access and Credentials

This is where most projects get stuck: someone forgot to request API access early. Save yourself some pain.

  • For Bunchball, you’ll need an API key (sometimes called a “partner key”) and maybe a secret. You get this from your Bunchball admin portal.
  • For your HR platform, you may need to create an API user, set up OAuth, or generate an access token.
  • If your HR system only does CSV exports, plan to schedule and fetch those files instead.

Pro tip:
Test your credentials immediately using a tool like Postman or curl. Don’t wait until you’ve built your whole script.

Step 4: Write (or Use) a Script to Pull User Data from HR

Here’s where you fetch your latest user data from the HR side:

  • If your HR system has an API, hit the endpoint that returns user lists. Usually it’s a paginated REST endpoint.
  • If you’re stuck with CSV exports, write a script (Python, Node.js—whatever you like) to read and parse the file.

Sample Python pseudocode:

python import requests

Example for HR API

resp = requests.get('https://api.hrplatform.com/users', headers={'Authorization': 'Bearer YOUR_TOKEN'}) users = resp.json() # or .csv parsing if needed

Or, if CSV:

import csv with open('users.csv') as f: reader = csv.DictReader(f) users = [row for row in reader]

What can go wrong: - Date/time fields are in weird formats, or blank. - Some users are missing email or IDs. - The HR system doesn’t flag “terminated” users clearly.

Clean your data before you try to send it to Bunchball.

Step 5: Transform and Prepare Data for Bunchball

Bunchball expects data in a specific format. Usually, you’ll need to:

  • Rename fields to match Bunchball’s API.
  • Fill in required fields (externalId, email, firstName, lastName, status).
  • Map department or roles to custom fields.
  • Set “status” as “active” or “inactive” based on your HR data.

Example transformation:

python def transform_user(hr_user): return { "externalId": hr_user["employee_id"], "email": hr_user["email"], "firstName": hr_user["first_name"], "lastName": hr_user["last_name"], "custom1": hr_user.get("department", ""), "status": "active" if hr_user["status"] == "Employed" else "inactive" }

What to ignore:
Don’t try to sync passwords or authentication fields. That’s a different beast.

Step 6: Push Data to Bunchball Using the API

Now, actually send the cleaned and mapped user data to Bunchball.

Options:

  • Batch Import API: If you’re updating lots of users, use the Batch Import endpoint. It takes a CSV or XML payload.
  • User Service API: For small updates or real-time sync, use the REST endpoints to create/update users one at a time.

Sample Batch Import (CSV):

  1. Create a CSV file in the required format.
  2. POST it to the batch import endpoint with your API key.

Sample User Update (REST):

python import requests

user = transform_user(hr_user) resp = requests.post( "https://api.bunchball.net/nitro/v1/user", params={"apiKey": "YOUR_API_KEY"}, json=user ) if resp.status_code != 200: print(f"Failed to update user: {resp.text}")

Honest take:
Batch Import is faster for lots of users, but the error reporting is vague. REST is slower but easier to debug. For the first run, try both with a test account.

Common problems: - Bunchball rejects users with missing required fields, but doesn’t always say which one. - Duplicate users error out if you use the wrong ID. - Batch jobs can take a while to process; don’t expect instant feedback.

Step 7: Handle Deletions and Status Changes

Don’t just create new users—handle people who leave or change roles.

  • Mark users as "inactive" in Bunchball when they leave, instead of deleting them. Actual deletion is rarely needed and can break reports.
  • If someone changes departments or roles, update the relevant custom fields.
  • Schedule your sync to run daily (or weekly, if things don’t change much).

Pro tip:
Have a “dry-run” mode that logs what would change, so you can check before making real updates.

Step 8: Monitor, Test, and Iterate

Set up basic monitoring:

  • Log errors and failed updates.
  • Spot-check a few users after each sync.
  • Set up an alert for failed syncs (email, Slack, whatever).

Don’t try to build a perfect system on day one. You’ll find weird edge cases—contractors without emails, name changes, HR data that’s just plain wrong. Tweak your mappings as you go.

What Actually Works, and What to Watch Out For

What works well: - Regular, one-way syncs from HR to Bunchball are reliable once set up. - Batch Import is efficient for big user lists. - Bunchball’s APIs are stable, if a bit old-fashioned.

What doesn’t: - Two-way sync (Bunchball to HR) is rarely worth the effort. - Real-time updates are tricky unless your HR vendor supports webhooks. - Error messages from Bunchball can be vague. Plan to do some detective work.

What you can ignore: - Fancy custom gamification rules in Bunchball—don’t mess with these during your sync project. - SSO and authentication—leave that to your IT/security team.

Keep It Simple, and Iterate

Don’t overthink your first sync. Start with just the fields you actually need, set up a basic daily job, and see what breaks. You can always add more complexity later. Most of the pain comes from edge cases, not from the main flow.

If you hit a wall, ask both vendors for help—but don’t expect miracles. Most of the time, a simple CSV export and a small script gets the job done.

Good luck, and remember: working sync beats perfect sync every time.