Bnchmrk API
Two directions. Push data in to manage employers, plans, and users, and pull data out (in development) to render benchmarking and analytics on your own platform.
Getting started
Environments
- Production
https://api.bnchmrk.com/partner- Production Environment - Live data, rate-limited
- Staging
https://api-testing.bnchmrk.com/partner- Staging Environment - Test data, higher rate limits for development
Authentication
Send your token in the Authorization header, prefixed with Token:
Authorization: Token YOUR_API_TOKEN
Content-Type: application/jsonTokens are environment-specific. Need one? Request API access.
Conventions
Creating & updating
Create a record with POST to the collection; a successful create returns 200 with the new record (including its generated id). Update with PUT to /…/{id}/ and send the full body (same required fields as create).
Dates & validation
Dates use YYYY-MM-DD. On a bad request the API returns 400 with a list of per-field validation errors.
Validation is necessary, but not sufficient
A payload can pass validation and still model a plan incorrectly (for example an HDHP submitted as a standard plan, or a prescription carve-out left on a separate record). When you map source data into the API, follow the integration guides so plans are represented correctly, not just accepted.
Cost-share fields (the “_ded_apply” values)
Service cost-share fields such as pcp_ded_apply tell us how the deductible and coinsurance apply:
FALSE: deductible and coinsurance do not applyFALSE_COIN: only coinsurance appliesTRUE: only deductible appliesTRUE_COIN: deductible and coinsurance both apply
Full meaning for every field, including allowed values and when each is required, is in the Field Dictionary.
Management API
Data inLivev2.2.1Create and manage employers, benefit plans, users, and divisions. Generated from the live API schema.
Employer records serve as the foundational entity in the Bnchmrk ecosystem, representing companies, organizations, or clients for whom employee benefit plans are administered.
Medical and Prescription (Rx) plans represent the core healthcare coverage offerings, encompassing doctor visits, hospital care, prescription medications, and preventive services.
Dental benefit plans provide coverage for oral healthcare services, from routine cleanings and preventive care to major restorative procedures and orthodontic treatment.
Vision benefit plans provide coverage for eye care services, including routine eye exams, corrective lenses, frames, and contact lenses.
Basic Life and Accidental Death & Dismemberment (AD&D) plans provide employer-sponsored financial protection for employees' beneficiaries in the event of death or serious injury.
Voluntary Life and Accidental Death & Dismemberment (AD&D) plans provide employee-elected supplemental life coverage, allowing employees to purchase additional protection for themselves and their dependents.
Short-Term Disability (STD) plans provide temporary income replacement for employees unable to work due to illness or injury, typically covering periods up to 52 weeks.
Long-Term Disability (LTD) plans provide extended income replacement for employees with prolonged disabilities, offering coverage from the end of STD benefits until retirement age or recovery.
Stop Loss insurance provides financial protection for self-funded health plans against catastrophic claims, limiting the employer's exposure to large medical expenses.
Supplemental plans capture the voluntary and ancillary benefits an employer offers alongside its core medical, dental, vision, life, and disability coverage.
User management enables programmatic control over access to your Bnchmrk account, implementing role-based permissions and data isolation through division-based security.
Bnchmrk Insights API
Data outIn developmentv0.5.0-draftData-out: the benchmarking Bnchmrk returns to clients. One benchmark model with two faces - weekly pre-computed market cuts (single dimension) and on-demand async employer reports scored against a multi-dimension peer group. ng returns the scoring in the JSON. In development; not yet live.
These endpoints are a draft, not yet live.
Endpoint shapes, field names, and response details may still change before release.
The market face: benchmark tables for one dimension at a time (any state, industry, size band, or account 'other' grouping), refreshed weekly and uncapped. Covers the 8 benchmarkable benefits (medical, dental, vision, basiclife, voluntarylife, std, ltd, stoploss); stop loss is size-only. Distribution statistics are the 25th / 50th / 75th percentiles (Limited / Balanced / Robust), alongside prevalence_data.
The scored face: score one of your plans against a multi-dimension cohort (query). On-demand and always async (202 -> poll); the result is transient (short TTL, retrieved once), not stored. ng returns a 0-100 score + band per plan. Per-plan only - there is no employer-level endpoint or composite; assemble employer views client-side from per-plan scores (a guide, not an endpoint).
The metric catalog per benefit and the dimensions you can query, with the current data vintage.