Skip to main content
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 Lines of Business

Find lines of business you want to query. Lines of business can be filtered by category (commercial, medicare_advantage, medicaid, etc.) and payer. 
curl -X GET "https://api-sandbox.penelope.health/v1/lobs" \
  -H "x-api-key: $PENELOPE_API_KEY"
Response: 
{
  "data": [
    {
      "lob_id": "ACIRL_medicare_part_a_VA",
      "payer_id": "ACIRL",
      "payer_name": "Medicare Virginia Part A",
      "lob": "medicare_part_a",
      "state": "VA"
    },
    {
      "lob_id": "ACIRL_medicare_part_a_WV",
      "payer_id": "ACIRL",
      "payer_name": "Medicare Virginia Part A",
      "lob": "medicare_part_a",
      "state": "WV"
    },
    {
      "lob_id": "AMCKE_medicare_part_b_TN",
      "payer_id": "AMCKE",
      "payer_name": "Medicare Tennessee Part B",
      "lob": "medicare_part_b",
      "state": "TN"
    }
  ],
  "limit": 20,
  "offset": 0,
  "has_more": false
}
Save the lob_id values—you’ll use these to filter policy queries.

List LOBs 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": "CPT",
        "codes": [
          "15823"
        ]
      }
    ],
    "lob_ids": [
      "HPQRS_commercial_US_"
    ]
  }
}'
Response: 
{
  "data": [],
  "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": "CPT",
        "codes": [
          "15823"
        ],
        "relationship": [
          "COVERS"
        ]
      }
    ]
  }
}'
Response: 
{
  "data": [
    {
      "policy_id": "aetna/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
    },
    {
      "policy_id": "aetna/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
    },
    {
      "policy_id": "aetna/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": [
    {
      "policy_id": "anthem/abcny/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.3,
      "applicability": null,
      "code_groups": null
    },
    {
      "policy_id": "anthem/abcbs/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.3,
      "applicability": null,
      "code_groups": null
    },
    {
      "policy_id": "anthem/abcbs_va/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.3,
      "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 lines of business this policy applies to. Combine with lob_ids to scope the search to specific lines of business. 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 policy_id. 
curl -X GET "https://api-sandbox.penelope.health/v1/policies/bcbsfl/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_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/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_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