Check + Benbase Integration Guide

Introduction

Benbase is an AI-native benefits broker that helps modern payroll platforms offer embedded health benefits, 401(k), and workers' compensation administration to their customers. Benbase handles plan quoting, enrollment, census sync, and ongoing deduction management — all through embeddable iframe components.

The Check + Benbase Integration enables any partner to offer a full suite of employee benefits directly in their platform. This enables partners to:

• Quickly test for product-market-fit across health, retirement, and workers' comp benefits
• Differentiate their payroll offering with a unified benefits experience
• Add a new revenue stream for their business

🚧

Implementation Timeline Expectations

In order to integrate with Benbase, Check requires additional information to properly stage you with Benbase. Additionally, in order to launch the Benbase integration in production, you may need to sign a contract amendment.

This implementation process may take up to 2 weeks to complete.

If interested in integrating, please reach out to your Check representative to get this process started.

Integration Overview

Unlike other Check ecosystem integrations that use Check's /components/integrations endpoint, the Benbase integration is Benbase-driven — partners interact primarily with Benbase's iframe components and only make a single Check API call to authorize the payroll connection.

The integration follows a three-step process:

1. Embed the Employer Flow — Surface Benbase's employer enrollment iframe so the employer can browse and select benefit plans.
2. Connect Payroll — Authorize Benbase to access the company's payroll data through Check's integration authorization endpoint.
3. Embed the Employee Flow — Surface Benbase's employee enrollment iframe so individual employees can enroll in their employer's selected plans.

📘

Supported Payroll Engine

Check is currently the only supported payroll engine for the Benbase integration.

Step 1: Embed the Employer Flow

Start the employer benefits enrollment by requesting an iframe URL from Benbase.

Request

Make a POST request to Benbase's employer flow endpoint:

https://embed-sandbox.benbase.com/api/flows/employer

Include the following in the body of the request:

{
  "employer_id": "com_abc123",          // your Check company ID
  "employer_name": "Stark Industries",  // the employer's business name
  "employer_fein": "12-3456789",        // the employer's FEIN
  "flow": "health",                     // the benefit type: "health", "retirement", or "workers_comp"
  "metadata": {
    "hq_zip": "94107"                   // employer's headquarters ZIP code
  }
}

📘

Production URL

In production, use https://embed.benbase.com/api/flows/employer instead of the sandbox URL.

Response

Benbase returns a single-use iframe URL:

{
  "url": "https://embed-sandbox.benbase.com/flows/employer?token=abc123..."
}

Embedding the Iframe

Render the iframe URL in your application:

<iframe
  id="benbase-employer-frame"
  src="IFRAME_URL_FROM_RESPONSE"
  style="width: 100%; border: none;"
></iframe>

Handling PostMessage Events

Benbase sends postMessage events from the iframe that your application should listen for:

window.addEventListener("message", (event) => {
  if (event.data.type === "benbase-embed.height-updated") {
    // Resize the iframe to match the content height
    const iframe = document.getElementById("benbase-employer-frame");
    iframe.style.height = event.data.height + "px";
  }

  if (event.data.type === "benbase-embed.authorize-start") {
    // The employer is ready to connect payroll — proceed to Step 2
  }
});

Step 2: Connect Payroll (Authorize Benbase via Check)

When the employer is ready to connect their payroll data (triggered by the benbase-embed.authorize-start event), authorize Benbase to access the company's data through Check.

Request

Make a POST request to Check's integration authorization endpoint:

https://sandbox.checkhq.com/companies/{company_id}/components/integrations/authorize

Include the following in the body of the request:

{
  "integration_partner": "int_DjupWSJkIYfQ2xfIB3sL",   // Benbase integration partner ID
  "integration_permission": "ipe_keLxIxEPasWS9Za6UKCu", // Benbase integration permission ID
  "email": "[email protected]",                        // employer's email address
  "redirect_url": "https://yourapp.com/benbase/callback"  // where to redirect after authorization
}

Authorization Flow

The authorization follows a standard OAuth flow:

1. Your application calls the Check authorize endpoint with the Benbase integration partner and permission IDs.
2. Check returns a component URL that you present to the employer.
3. The employer reviews the requested permissions and clicks "Authorize".
4. Check generates an authorization code and sends it directly to Benbase via an OAuth callback. Your application does not need to handle this callback.
5. Benbase exchanges the authorization code for an access token.
6. Benbase uses the access token to sync census data and manage deductions.
7. The employer is redirected to your redirect_url.

📘

OAuth Callback

Unlike typical OAuth integrations where your application handles the callback, Check sends the OAuth callback directly to Benbase. Your application only needs to handle the redirect after authorization is complete.

Post-Connection

After the employer authorizes the connection:

• Census sync — Benbase automatically pulls employee data from Check to populate plan enrollment.
• Plan quoting — Benbase generates quotes based on the employer's census data.
• Deduction management — Once employees enroll, Benbase automatically creates and manages benefit deduction objects in Check, ensuring payroll deductions stay in sync. Benefits managed by Benbase will have a source field of int_DjupWSJkIYfQ2xfIB3sL.

No additional API calls or webhook handling is required from your application for these ongoing sync operations.

Step 3: Embed the Employee Flow

After the employer has selected their benefit plans and connected payroll, surface the employee enrollment iframe for each employee.

Request

Make a POST request to Benbase's employee flow endpoint:

https://embed-sandbox.benbase.com/api/flows/employee

Include the following in the body of the request:

{
  "employer_id": "com_abc123",  // your Check company ID
  "employee_id": "emp_xyz789"   // the Check employee ID
}

📘

Production URL

In production, use https://embed.benbase.com/api/flows/employee instead of the sandbox URL.

Response

Benbase returns a single-use iframe URL for the specific employee:

{
  "url": "https://embed-sandbox.benbase.com/flows/employee?token=def456..."
}

Embedding the Iframe

Render the iframe URL in your application:

<iframe
  id="benbase-employee-frame"
  src="IFRAME_URL_FROM_RESPONSE"
  style="width: 100%; border: none;"
></iframe>

Handling PostMessage Events

Listen for the same height-updated event to resize the iframe:

window.addEventListener("message", (event) => {
  if (event.data.type === "benbase-embed.height-updated") {
    const iframe = document.getElementById("benbase-employee-frame");
    iframe.style.height = event.data.height + "px";
  }
});

Automatic Data Sync

Once the integration is authorized, all ongoing data sync between Check and Benbase is automatic:

• Census data — Employee information is synced from Check to Benbase on an ongoing basis, ensuring plan eligibility and enrollment records stay current.
• Deduction management — Benbase creates and manages benefit objects in Check's system. When employees enroll in or change plans, the corresponding payroll deductions are updated automatically.
• No partner action required — Your application does not need to make additional API calls, handle webhooks, or perform any manual sync operations after the initial setup.

Customer Support

After an employer has signed up with Benbase, employers and employees will have a direct relationship with Benbase for benefits administration. Any ongoing support questions related to plan selection, enrollment, or benefits administration should be raised directly with Benbase.

If there are any technical or data sync issues that the employer raises to you, please reach out to Check's Support team or your Check contact. These will be handled internally by Check's Partnerships team.