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.

An unhandled error has occurred. Reload ๐Ÿ—™