Skip to content

How to Integrate 4Geeks Perks with Your Existing HR Software

🤖 Explain with AI

Managing employee benefits manually across different spreadsheets and systems is time-consuming and prone to error. By integrating 4Geeks Perks with your existing Human Resources Information System (HRIS) or payroll software, you can automate user management, ensure accurate benefit eligibility, and streamline the onboarding process.

This article guides you through connecting your HR software to 4Geeks Perks, enabling seamless data synchronization and reducing administrative overhead.

Prerequisites

Before starting the integration process, ensure you meet the following requirements:

  • Active Premium Plan: HR system integration is available on the Premium plan. Ensure your account is upgraded.
  • Admin Access: You must have Administrator privileges on both the 4Geeks Console and your target HRIS (e.g., Microsoft Entra ID, Workday, BambooHR).
  • API Credentials: If using a custom integration, you will need your unique API Keys (Test and Live) from the Settings > API Keys section of the console.

Integration Methods

There are two primary ways to integrate your HR systems with 4Geeks Perks:

  1. Native SSO & Directory Sync: Best for organizations using major identity providers like Microsoft Entra ID (formerly Azure AD) to manage employee access and identity.
  2. Custom API Integration: Ideal for bespoke HR systems or when you need specific, complex synchronization logic using the 4Geeks Custom API.

Method 1: Connecting via Microsoft Entra ID (SSO)

Connecting your identity provider is the fastest way to sync your workforce.

Step 1: Access Integration Settings

  1. Log in to the 4Geeks Console.
  2. Navigate to the Perks module.
  3. Click on Settings in the sidebar and select Integrations.

Step 2: Authorize the Connection

  1. Locate Microsoft Entra ID (or your specific provider) in the list of available integrations.
  2. Click Connect. You will be redirected to your Microsoft login page.
  3. Sign in with your organization’s Admin credentials and grant 4Geeks Perks permission to read directory data (users and groups).

Step 3: Configure Sync Rules

Once connected, configure how data flows between systems: * User Provisioning: Enable “Auto-Create Users” to automatically generate a 4Geeks Perks wallet for new employees added to your HR system. * De-provisioning: Enable “Auto-Archive Users” to instantly revoke perk access when an employee leaves the company, protecting your budget.

Method 2: Using the Custom API

For unique workflows, you can use the 4Geeks API to programmatically manage employees and their benefits.

Step 1: Generate API Keys

  1. Go to the 4Geeks Console > Settings > API Keys.
  2. Copy your Live Key (starts with sk_live_). Warning: Never share this key publicly.

Step 2: Implement User Sync

Use your development team or 4Geeks Teams to build a connector that calls the 4Geeks API. You will primarily interact with the Users endpoints to create, update, or deactivate employees based on triggers from your HR software.

  • Endpoint: POST /v1/users/
  • Payload Example: 
    {
  "email": "employee@company.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "role": "employee",
  "status": "active"
}

Step 3: Test the Integration

Use your Test Key (sk_test_) to simulate employee onboarding without affecting real data. Ensure that creating a user in your HR sandbox correctly triggers the creation of a user in the 4Geeks Perks sandbox environment.

Common Use Cases

Scenario 1: Automated Onboarding

Situation: A high-growth tech company hires 10 new developers every month. Manually creating perk wallets for each is tedious. Solution: By integrating with their HRIS, as soon as a new hire is marked “Active” in the HR system, 4Geeks Perks automatically creates their profile and assigns them the standard “New Hire” benefit package. Result: The new employee receives their digital 4Geeks Perks Card via email on their first day without manual HR intervention.

Scenario 2: Instant Offboarding

Situation: An employee resigns, and HR forgets to cancel their perks card, leading to unauthorized spending on meals after their departure. Solution: With integration enabled, marking the employee as “Terminated” in the HR system triggers an immediate status update in 4Geeks Perks. Result: The employee’s wallet is frozen instantly, preventing any post-employment usage and saving costs.

Troubleshooting

Issue 1: Employee data is not syncing

  • Cause: The sync interval may not be immediate (some systems sync every 24 hours), or permissions were revoked.
  • Solution: Check the “Last Sync” timestamp in your Integration Settings. You can often force a “Sync Now” action. If that fails, verify that the 4Geeks application still has “Read” permissions in your HRIS.

Issue 2: “User already exists” error

  • Cause: You manually created a user in 4Geeks Perks before the integration attempted to import them.
  • Solution: The system usually matches by email address. Ensure the email in your HR system matches the one manually created. If the issue persists, contact support to merge the records.

Issue 3: New hires are not receiving their Perks Card email

  • Cause: The user profile was created but the “Welcome Email” trigger might be disabled.
  • Solution: In the 4Geeks Console, go to Perks > Settings > Notifications and ensure the “New User Welcome” email is active.

Conclusion

Integrating 4Geeks Perks with your HR software transforms benefits management from a manual chore into a strategic, automated advantage. By ensuring data accuracy and timeliness, you improve the employee experience while safeguarding company resources.

Need help with a complex integration? * Explore: 4Geeks Documentation for API references. * Contact: Reach out to our Support Team for guided implementation assistance.