Developers
One API. Every Carrier.
Integrate normalized health plan data into your application in minutes. Versioned, documented, and conformant to the Benefit Plan Standard.
Quickstart
Authenticate with your API key and start querying plans immediately. All responses are strictly typed JSON.
GET https://api.healthplanapi.com/v1/plans
Authorization: Bearer {YOUR_API_KEY}The Power of Normalization
Don't write if (carrier == 'X'). The API returns consistent,
BPS-conformant objects regardless of the source PDF.
{
"plan_metadata": {
"carrier": "Example Carrier",
"plan_year": 2026,
"plan_type": "PPO"
},
"accumulators": {
"individual_deductible": 1500.00,
"family_deductible": 3000.00
}
}Key Endpoints
Full access to the data layer.
This is a high-level view. The full OpenAPI specification is available for import into your tools.
Get the BPS document
GET /v1/plans/{id}/bps
Returns the full plan as a Benefit Plan Standard conformant JSON
document, schema-validated on the way out. Never a silently
non-conformant response.
Get the provenance
GET /v1/plans/{id}/bps/provenance
The citation sidecar: every field in the BPS document mapped to its
page, bounding box, and source text in the original PDF.
Search plans
GET /v1/plans
Filter by carrier, year, market segment, network type, and specific
financial values (e.g., "deductible < $2000").
Metadata only
GET /v1/metadata/plans/{id}
Retrieve identifiers, validation status, and timestamps without
incurring the latency of fetching the full benefit tree.
Schema versions
GET /v1/schema/{version}
Programmatically fetch the exact JSON Schema used for validation.
Ensures your client-side validation never drifts.
Audit artifacts
GET /v1/plans/{id}/raw
Access raw extraction output, mapping logs, and validation reports.
Essential for enterprise audit trails.
OpenAPI & SDKs
Health Plan API provides a full OpenAPI 3.1 specification that you can import into Postman, Insomnia, or your code generator of choice to create client SDKs.
If you're interested in an officially supported SDK (TypeScript, Python, or another language), let us know your stack and we can prioritize accordingly.
MCP Server
Access via AI agents.
In addition to the REST API, Health Plan API runs a hosted MCP server for Claude Code, Cursor, VS Code and any MCP-compatible assistant.
Connecting
The MCP server is hosted: there is nothing to install. An assistant connects to it with your API key in a header. It opens with self-service access, and the connection steps for Claude Code, Cursor and VS Code will be here then.
Its tools
Seven read-only tools, each reading what its REST operation reads. A plan, or one part of it, comes back with the stored citation of every value:
resolve_plans: find plans by carrier, plan name, state, year or HIOS id.list_plans: your plans, or the published plans.get_plan: a plan as a Benefit Plan Standard document, or one part of it, with citations.get_citation: the stored citation of one value.get_provenance_image: the page a value was read from, with its region outlined.lookup_drug: a drug's coverage on one plan.lookup_drug_across_plans: a drug's coverage across the plans you can see.
When to use MCP vs. REST
Use the REST API when you need programmatic access in production systems: enrollment platforms, quoting engines, data pipelines. Use the MCP Server when an AI agent is in the loop: answering coverage questions, comparing benefits during development, or reasoning over plan content. Cited answers matter most exactly there.
Both access methods share the same underlying data, the same auth, and the same rate limits. They are complementary, not alternatives.