1. Embed Employer Flow
Embed the Employer Flow iframe in your platform.
Embed Employer Flow
The Employer Flow is shown to the employer (your customer). It covers quoting, plan selection, and enrollment management.
Each time an employer needs to access their benefits dashboard, you generate a single-use iframe URL by calling the Benbase API. The URL contains a one-time token — generate a new one for each session.
curl -X POST https://embed-sandbox.benbase.com/api/flows/employer \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"employer_id": "<employer-id>",
"employer_name": "<employer-name>",
"employer_fein": "<employer-fein>",
"flow": "marketplace",
"metadata": { "hq_zip": "<employer-hq-zip>", "sic_code": "<sic-code>" }
}'Request body
Set flow to "marketplace". Provide the employer's details in metadata, and optionally an employee census.
Fields
| Field | Type | Required | Notes |
|---|---|---|---|
employer_id | string | Yes | Partner's unique ID for the employer |
employer_name | string | Yes | Company name |
employer_fein | string | null | No | Federal EIN. 9 digits, optional dashes — 12-3456789 or 123456789 |
flow | "marketplace" | Yes | Must be "marketplace" |
metadata | object | Yes | See metadata fields |
census | array | No | Employee census. See census fields |
metadata fields
| Field | Type | Required | Notes |
|---|---|---|---|
hq_zip | string | Yes | Company headquarters ZIP, 5 characters |
sic_code | string | No | 1987 4-digit SIC code. Empty string "" or omit → default 8742 (Management Consulting Services). A non-empty value must be a valid SIC code |
census fields
Providing an employee census with as much data as possible improves quote quality.
Each element of census is an employee.
This inline census is for marketplace quoting. For the full integration (enrollment + payroll deductions), Benbase also requests a census by webhook — see Connect API.
| Field | Type | Required | Notes |
|---|---|---|---|
firstName | string | null | No | |
lastName | string | null | No | |
birthDate | string | Yes | YYYY-MM-DD |
gender | "M" | "F" | Yes | |
zipCode | string | Yes | Employee's residential ZIP (min 5) |
annualSalary | number | No | Whole dollars, positive integer. Required for Life and Disability rates |
hoursPerWeek | number | No | Integer, 1–168. Required for Life and Disability rates |
SSN, home address, and tobacco use are not collected for census-based quoting — they aren't needed to produce a quote. All dates use YYYY-MM-DD format.
Marketplace flow with census
This example includes an employee census. Provide as much census data as possible to improve quote quality.
curl -X POST https://embed-sandbox.benbase.com/api/flows/employer \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"employer_id": "acme-123",
"employer_name": "Acme Inc.",
"employer_fein": "12-3456789",
"flow": "marketplace",
"metadata": { "hq_zip": "90210", "sic_code": "7372" },
"census": [
{
"firstName": "Jane",
"lastName": "Doe",
"birthDate": "1990-04-15",
"gender": "F",
"zipCode": "90210",
"annualSalary": 75000,
"hoursPerWeek": 40
}
]
}'Embed the returned URL in your app.
Required: Flow iframes emit benbase-embed.height-updated events via postMessage whenever their content height changes. Your parent page must listen for this event and resize the iframe accordingly — otherwise the iframe will scroll internally. All examples below include this listener.
<iframe id="benbase-employer" src="{{url}}" style="width:100%;border:none"></iframe>
<script>
window.addEventListener('message', function(event) {
var eventName = event.data.event;
var data = event.data.data;
if (eventName === 'benbase-embed.height-updated') {
document.getElementById('benbase-employer').style.height = data.height + 'px';
}
});
</script>Once rendered, Benbase uses the census data you provide to generate quotes for the employer. No action needed from you during this phase.