Getting Started - Penelope

This guide walks you through the five essential steps to start using the Penelope API for medical policy coverage verification.

Prerequisites

Before you begin, you’ll need:

An API key from Penelope (contact us at [email protected])
A tool to make HTTP requests (curl, Postman, or your preferred language)

Step 1: Authenticate

All Penelope API requests require authentication via the x-api-key header.

curl -X GET https://api-sandbox.penelope.health/health \
  -H "x-api-key: your_api_key_here"

If your key is valid, you’ll receive a 200 response. See the Authentication docs for error handling and security best practices.

Store your API key as an environment variable to avoid exposing it in code:

export PENELOPE_API_KEY="your_api_key_here"

Step 2: List Available Plans

Find insurance plans you want to query. Plans can be filtered by type (commercial, medicare_advantage, medicaid, etc.) and payer.

curl -X GET "https://api-sandbox.penelope.health/v1/plans" \
  -H "x-api-key: $PENELOPE_API_KEY"

Response:

{
  "data": [
    {
      "plan_id": "ACIRL_medicare_part_a_VA",
      "payer_id": "ACIRL",
      "payer_name": "Medicare Virginia Part A",
      "plan_type": "medicare_part_a",
      "country_wide": false,
      "states": [
        "VA"
      ]
    },
    {
      "plan_id": "ACIRL_medicare_part_a_WV",
      "payer_id": "ACIRL",
      "payer_name": "Medicare Virginia Part A",
      "plan_type": "medicare_part_a",
      "country_wide": false,
      "states": [
        "WV"
      ]
    },
    {
      "plan_id": "AFQTI_commercial_NY",
      "payer_id": "AFQTI",
      "payer_name": "Excellus Blue Cross Blue Shield New York Utica Watertown",
      "plan_type": "commercial",
      "country_wide": false,
      "states": [
        "NY"
      ]
    }
  ],
  "limit": 20,
  "offset": 0,
  "has_more": false
}

Save the plan_id values—you’ll use these to filter policy queries.

List Plans API

View all filtering options and response fields

Step 3: Query Policies by Medical Codes

Find policies related to specific CPT, HCPCS, or ICD-10-CM codes. This is the primary way to check coverage for a procedure or diagnosis.

curl -X POST "https://api-sandbox.penelope.health/v1/policies/filter" \
  -H "x-api-key: $PENELOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "policies": {
    "code_refs": [
      {
        "code_system": "CPTCode",
        "codes": [
          "15823"
        ]
      }
    ],
    "plan_ids": [
      "HPQRS_commercial_US"
    ]
  }
}'

Response:

{
  "data": [
    {
      "node_id": "aetna/US/0031/2025-07-08",
      "policy_number": "0031",
      "title": "Cosmetic Surgery and Procedures",
      "effective_from_date": "2025-07-08",
      "effective_to_date": "2026-01-30",
      "file_url": "https://www.aetna.com/cpb/medical/data/1_99/0031.html",
      "listing_url": "https://www.aetna.com/content/dam/aetna/xml/aetnacom/health-care-professionals/mcpb-alpha.xml",
      "summary": "Aetna's CPB 0031 addresses cosmetic surgery and procedures coverage, excluding most cosmetic surgeries but covering medically necessary procedures with functional or therapeutic indications. The policy covers blepharoplasty (eyelid surgery) when meeting criteria from CPB 0084, breast reduction per C...",
      "score": null,
      "applicability": null,
      "code_groups": null
    },
    {
      "node_id": "aetna/US/0031/2026-01-30",
      "policy_number": "0031",
      "title": "Cosmetic Surgery and Procedures - CPB 0031",
      "effective_from_date": "2026-01-30",
      "effective_to_date": "2026-03-12",
      "file_url": "https://www.aetna.com/cpb/medical/data/1_99/0031.html",
      "listing_url": "https://www.aetna.com/content/dam/aetna/xml/aetnacom/health-care-professionals/mcpb-alpha.xml",
      "summary": "Aetna's Cosmetic Surgery and Procedures policy (CPB 0031) addresses coverage for cosmetic versus reconstructive procedures. The policy covers medically necessary surgeries including blepharoplasty (eyelid surgery), breast reduction, chemical peels, dermabrasion, dermal fillers for HIV-related facial...",
      "score": null,
      "applicability": null,
      "code_groups": null
    },
    {
      "node_id": "aetna/US/0031/2026-03-12",
      "policy_number": "0031",
      "title": "Cosmetic Surgery and Procedures - CPB 0031",
      "effective_from_date": "2026-03-12",
      "effective_to_date": null,
      "file_url": "https://www.aetna.com/cpb/medical/data/1_99/0031.html",
      "listing_url": "https://www.aetna.com/content/dam/aetna/xml/aetnacom/health-care-professionals/mcpb-alpha.xml",
      "summary": "This Aetna Clinical Policy Bulletin (CPB 0031) addresses coverage for cosmetic surgery and procedures. Aetna excludes coverage for cosmetic surgeries not deemed medically necessary, but covers procedures needed to improve body part functioning or otherwise medically necessary even if they affect app...",
      "score": null,
      "applicability": null,
      "code_groups": null
    }
  ],
  "limit": 20,
  "offset": 0,
  "has_more": false
}

Set "include_code_groups": true in the request body to get code_groups — codes grouped by system (CPT, HCPCS, ICD-10-CM), relationship (COVERS, DOES_NOT_COVER, REFERENCES), and category.

Filtering by Coverage Type

Use the edge_types parameter to filter by relationship type:

COVERS — policy explicitly covers the code
DOES_NOT_COVER — policy explicitly excludes the code
REFERENCES — code is mentioned but coverage isn’t explicit

curl -X POST "https://api-sandbox.penelope.health/v1/policies/filter" \
  -H "x-api-key: $PENELOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "policies": {
    "code_refs": [
      {
        "code_system": "CPTCode",
        "codes": [
          "15823"
        ],
        "relationship": [
          "COVERS"
        ]
      }
    ]
  }
}'

Response:

{
  "data": [
    {
      "node_id": "aetna/US/0031/2025-07-08",
      "policy_number": "0031",
      "title": "Cosmetic Surgery and Procedures",
      "effective_from_date": "2025-07-08",
      "effective_to_date": "2026-01-30",
      "file_url": "https://www.aetna.com/cpb/medical/data/1_99/0031.html",
      "listing_url": "https://www.aetna.com/content/dam/aetna/xml/aetnacom/health-care-professionals/mcpb-alpha.xml",
      "summary": "Aetna's CPB 0031 addresses cosmetic surgery and procedures coverage, excluding most cosmetic surgeries but covering medically necessary procedures with functional or therapeutic indications. The policy covers blepharoplasty (eyelid surgery) when meeting criteria from CPB 0084, breast reduction per C...",
      "score": null,
      "applicability": null,
      "code_groups": null
    },
    {
      "node_id": "aetna/US/0031/2026-01-30",
      "policy_number": "0031",
      "title": "Cosmetic Surgery and Procedures - CPB 0031",
      "effective_from_date": "2026-01-30",
      "effective_to_date": "2026-03-12",
      "file_url": "https://www.aetna.com/cpb/medical/data/1_99/0031.html",
      "listing_url": "https://www.aetna.com/content/dam/aetna/xml/aetnacom/health-care-professionals/mcpb-alpha.xml",
      "summary": "Aetna's Cosmetic Surgery and Procedures policy (CPB 0031) addresses coverage for cosmetic versus reconstructive procedures. The policy covers medically necessary surgeries including blepharoplasty (eyelid surgery), breast reduction, chemical peels, dermabrasion, dermal fillers for HIV-related facial...",
      "score": null,
      "applicability": null,
      "code_groups": null
    },
    {
      "node_id": "aetna/US/0031/2026-03-12",
      "policy_number": "0031",
      "title": "Cosmetic Surgery and Procedures - CPB 0031",
      "effective_from_date": "2026-03-12",
      "effective_to_date": null,
      "file_url": "https://www.aetna.com/cpb/medical/data/1_99/0031.html",
      "listing_url": "https://www.aetna.com/content/dam/aetna/xml/aetnacom/health-care-professionals/mcpb-alpha.xml",
      "summary": "This Aetna Clinical Policy Bulletin (CPB 0031) addresses coverage for cosmetic surgery and procedures. Aetna excludes coverage for cosmetic surgeries not deemed medically necessary, but covers procedures needed to improve body part functioning or otherwise medically necessary even if they affect app...",
      "score": null,
      "applicability": null,
      "code_groups": null
    }
  ],
  "limit": 20,
  "offset": 0,
  "has_more": false
}

List Policies API

Full documentation for code-based policy queries

Step 4: Search Policies by Keywords

For exploratory research when you don’t have specific codes, use full-text search across policy titles and summaries.

curl -X POST "https://api-sandbox.penelope.health/v1/policies/filter" \
  -H "x-api-key: $PENELOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "policies": {
    "q": "blepharoplasty"
  },
  "sort": "relevance",
  "limit": 3
}'

Response:

{
  "data": [
    {
      "node_id": "anthem/abcny/US/CG-SURG-03/2025-01-30",
      "policy_number": "CG-SURG-03",
      "title": "CG-SURG-03 Blepharoplasty, Blepharoptosis Repair, and Brow Lift",
      "effective_from_date": "2025-01-30",
      "effective_to_date": "2026-01-06",
      "file_url": "https://anthem.com/medpolicies/abcny/active/gl_pw_a051144.html",
      "listing_url": "https://www.anthembluecross.com/medpolicies/abcny/active/fulllist.json",
      "summary": "This clinical UM guideline (CG-SURG-03) addresses indications, coding, and coverage criteria for blepharoplasty, blepharoptosis repair and brow lift procedures focused on functional impairment of superior/central visual fields. It delineates medically necessary (MN) criteria for occlusion/deprivatio...",
      "score": 4.326983887947496,
      "applicability": null,
      "code_groups": null
    },
    {
      "node_id": "anthem/abcbs/US/CG-SURG-03/2026-01-06",
      "policy_number": "CG-SURG-03",
      "title": "CG-SURG-03 Blepharoplasty, Blepharoptosis Repair, and Brow Lift",
      "effective_from_date": "2026-01-06",
      "effective_to_date": null,
      "file_url": "https://anthem.com/medpolicies/abcbs/active/gl_pw_a051144.html",
      "listing_url": "https://www.anthem.com/medpolicies/abcbs/active/fulllist.json",
      "summary": "This clinical UM guideline (CG-SURG-03) addresses medical necessity criteria for blepharoplasty, blepharoptosis (ptosis) repair, and brow lift procedures of the upper and lower eyelids and forehead when performed for functional/visual-field impairment. It distinguishes medically necessary, reconstru...",
      "score": 4.320315657945615,
      "applicability": null,
      "code_groups": null
    },
    {
      "node_id": "anthem/abcbs_va/US/CG-SURG-03/2026-01-06",
      "policy_number": "CG-SURG-03",
      "title": "CG-SURG-03 Blepharoplasty, Blepharoptosis Repair, and Brow Lift",
      "effective_from_date": "2026-01-06",
      "effective_to_date": null,
      "file_url": "https://anthem.com/medpolicies/abcbs_va/active/gl_pw_a051144.html",
      "listing_url": "https://www.anthem.com/medpolicies/abcbs_va/active/fulllist.json",
      "summary": "This Clinical UM Guideline (CG-SURG-03) addresses surgical management of upper and lower eyelid disorders and brow ptosis, focusing on indications for blepharoplasty, blepharoptosis repair, and brow lift when functional visual impairment is present. The guideline defines medically necessary versus c...",
      "score": 4.282732531186605,
      "applicability": null,
      "code_groups": null
    }
  ],
  "limit": 3,
  "offset": 0,
  "has_more": false
}

Results are ranked by relevance score. The applicability field shows which payers and plan types this policy applies to. Combine with plan_ids to scope the search to specific plans. Set "include_code_groups": true to get associated codes.

List Policies API

Use the q parameter for full-text search across policy titles and summaries

Step 5: Download Policy Files

Once you’ve found a relevant policy, download the full document (PDF or HTML) using the policy’s node_id.

curl -X GET "https://api-sandbox.penelope.health/v1/policies/bcbsfl/US/01-90900-01/2025-07-15/download-url" \
  -H "x-api-key: $PENELOPE_API_KEY"

Response:

{
  "url": "https://s3.example.com/presigned-url",
  "content_type": "application/pdf",
  "filename": "bcbsfl_US_01-90900-01_2025-07-15.pdf"
}

Use variant=text to get an LLM-optimized markdown version:

curl -X GET "https://api-sandbox.penelope.health/v1/policies/bcbsfl/US/01-90900-01/2025-07-15/download-url?variant=text" \
  -H "x-api-key: $PENELOPE_API_KEY"

Response:

{
  "url": "https://s3.example.com/presigned-url",
  "content_type": "text/markdown",
  "filename": "bcbsfl_US_01-90900-01_2025-07-15.md"
}

The presigned URL expires after 1 hour. Download the file promptly or request a fresh URL.

Download Policy API

Get temporary download links for policy documents

Next Steps

Key Concepts

Understand the data model and relationships

Data Coverage

See which payers and plans are covered

Examples

More examples

API Reference

Complete API documentation

Penelope API

​Prerequisites

​Step 1: Authenticate

​Step 2: List Available Plans

List Plans API

​Step 3: Query Policies by Medical Codes

​Filtering by Coverage Type

List Policies API

​Step 4: Search Policies by Keywords

List Policies API

​Step 5: Download Policy Files

Download Policy API

​Next Steps

Key Concepts

Data Coverage

Examples

API Reference

Prerequisites

Step 1: Authenticate

Step 2: List Available Plans

Step 3: Query Policies by Medical Codes

Filtering by Coverage Type

Step 4: Search Policies by Keywords

Step 5: Download Policy Files

Next Steps