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.

Request API access See how the pipeline works

MCP Server

Access via AI agents.

In addition to the REST API, Health Plan API exposes an MCP Server for use with Claude Code, Cursor, Windsurf, and any MCP-compatible AI coding tool.

Configuration

Add this to your MCP config file. Your existing API key is the only credential required.

{
  "mcpServers": {
    "healthplanapi": {
      "command": "npx",
      "args": ["-y", "@healthplanapi/mcp-server"],
      "env": {
        "HEALTHPLANAPI_KEY": "your_api_key"
      }
    }
  }
}

Available tools

Once connected, your AI agent can call any of the following tools directly by name.

search_plans: Filter by carrier, year, or benefit criteria.
get_plan_summary: Concise plan overview with key cost shares and validation status.
get_plan_benefits: Full benefit tree for a plan ID.
get_copay: Copay and coinsurance for a specific benefit.
get_formulary: Pharmacy and drug-tier coverage for a plan.
compare_plans: Side-by-side comparison of two to five plans.
validate_plan: Validate a plan against the Benefit Plan Standard schema.
list_carriers: Available carriers and plan counts.

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.