Getting Started - Penelope

This guide walks you through the six 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": true
}

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": {
      "refs": [
        {
          "code_system": "CPT",
          "codes": [
            "15823"
          ]
        }
      ]
    },
    "lob_ids": [
      "HPQRS_commercial_US_"
    ]
  }
}'

Response:

{
  "data": [],
  "limit": 20,
  "offset": 0,
  "has_more": false
}

Results are relevance-ranked by default: policies whose title or summary match the descriptions of your codes come first, so a policy about the procedure outranks one that merely lists the code.

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": {
      "refs": [
        {
          "code_system": "CPT",
          "codes": [
            "15823"
          ],
          "relationship": [
            "COVERS"
          ]
        }
      ]
    }
  }
}'

Response:

{
  "data": [
    {
      "policy_id": "cigna/0045/2026-06-15",
      "policy_number": "0045",
      "title": "Blepharoplasty, Reconstructive Eyelid Surgery, and Brow Lift - (0045)",
      "effective_from_date": "2026-06-15",
      "effective_to_date": null,
      "file_url": "https://static.cigna.com/assets/chcp/pdf/coveragePolicies/medical/mm_0045_coveragepositioncriteria_blepharoplasty.pdf",
      "file_type": "pdf",
      "listing_url": "https://static.cigna.com/assets/chcp/resourceLibrary/coveragePolicies/medical_a-z.html",
      "summary": "This Cigna medical coverage policy (Policy 0045) addresses functional indications, documentation requirements, and coding for blepharoplasty, blepharoptosis (ptosis) repair, brow lift, and eyelid retraction surgery. It defines medically necessary criteria for upper and lower reconstructive blepharop...",
      "score": 4.3,
      "applicability": null,
      "code_groups": null
    },
    {
      "policy_id": "cigna/0045/2025-04-15",
      "policy_number": "0045",
      "title": "Blepharoplasty, Reconstructive Eyelid Surgery, and Brow Lift",
      "effective_from_date": "2025-04-15",
      "effective_to_date": "2026-04-15",
      "file_url": "https://static.cigna.com/assets/chcp/pdf/coveragePolicies/medical/mm_0045_coveragepositioncriteria_blepharoplasty.pdf",
      "file_type": "pdf",
      "listing_url": "https://static.cigna.com/assets/chcp/resourceLibrary/coveragePolicies/medical_a-z.html",
      "summary": "This Coverage Policy addresses reconstructive and functional eyelid and brow procedures, focusing on indications for blepharoplasty, blepharoptosis repair, brow ptosis correction and eyelid malposition surgery when functional impairment is documented. Covered conditions include dermatochalasis/bleph...",
      "score": 4.2,
      "applicability": null,
      "code_groups": null
    },
    {
      "policy_id": "cigna/0045/2026-04-15",
      "policy_number": "0045",
      "title": "Blepharoplasty, Reconstructive Eyelid Surgery, and Brow Lift - (0045)",
      "effective_from_date": "2026-04-15",
      "effective_to_date": "2026-06-15",
      "file_url": "https://static.cigna.com/assets/chcp/pdf/coveragePolicies/medical/mm_0045_coveragepositioncriteria_blepharoplasty.pdf",
      "file_type": "pdf",
      "listing_url": "https://static.cigna.com/assets/chcp/resourceLibrary/coveragePolicies/medical_a-z.html",
      "summary": "This Cigna coverage policy (0045) addresses medical necessity criteria for blepharoplasty, blepharoptosis repair, brow lift, and eyelid retraction surgery focused on functional indications affecting vision and ocular surface. It delineates objective preoperative requirements (visual field testing, M...",
      "score": 4.1,
      "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": "bcbsm/76765/2026-03-01",
      "policy_number": "76765",
      "title": "MEDICAL POLICY - BLEPHAROPLASTY AND REPAIR OF BROW PTOSIS",
      "effective_from_date": "2026-03-01",
      "effective_to_date": null,
      "file_url": "https://www.bcbsm.com/amslibs/content/dam/public/mpr/mprsearch/pdf/76765.pdf",
      "file_type": "pdf",
      "listing_url": "https://www.bcbsm.com/providers/mpradmin/",
      "summary": "This policy addresses surgical management of upper eyelid redundant tissue and eyebrow descent\u2014blepharoplasty and repair of brow ptosis\u2014focusing on restoration of function (visual field preservation, relief of dermatitis, prosthetic fit, and refractory blepharospasm). It defines objective functional...",
      "score": 4.3,
      "applicability": null,
      "code_groups": null
    },
    {
      "policy_id": "bsc/medical/BSC7.01/2026-04-01",
      "policy_number": "BSC7.01",
      "title": "Blepharoplasty, Blepharoptosis Repair (Levator Resection) and Brow Lift (Repair of Brow Ptosis)",
      "effective_from_date": "2026-04-01",
      "effective_to_date": null,
      "file_url": "https://www.blueshieldca.com/content/dam/bsca/en/provider/docs/medical-policies/Blepharoplasty-Blepharoptosis-Repair-Brow-Lift.pdf",
      "file_type": "pdf",
      "listing_url": "https://www.blueshieldca.com/en/provider/authorizations/policy-medical/list",
      "summary": "This Blue Shield of California medical policy (BSC7.01) addresses functional indications and medical necessity criteria for upper and lower eyelid blepharoplasty, blepharoptosis/ptosis repair (including levator resection and frontalis sling techniques), and brow lift/brow ptosis repair. It applies R...",
      "score": 4.2,
      "applicability": null,
      "code_groups": null
    },
    {
      "policy_id": "bcbstn/CAM040/2025-06-09",
      "policy_number": "CAM040",
      "title": "Blepharoplasty (Upper and Lower)",
      "effective_from_date": "2025-06-09",
      "effective_to_date": "2026-06-09",
      "file_url": "https://www.myhealthtoolkit.com/web/public/brands/medicalpolicy/external/external-policies/blepharoplasty-upper-and-lower",
      "file_type": "html",
      "listing_url": "https://www.myhealthtoolkit.com/web/public/brands/medicalpolicy/external/",
      "summary": "This medical policy (CAM 040) addresses surgical management of eyelid conditions including blepharoplasty (upper and lower), blepharoptosis (ptosis) repair, entropion and ectropion repair, and brow ptosis/brow lift procedures. It focuses on functional/reconstructive indications vs cosmetic indicatio...",
      "score": 4.1,
      "applicability": null,
      "code_groups": null
    }
  ],
  "limit": 3,
  "offset": 0,
  "has_more": false
}

Results are ranked by relevance score — a relative signal for ordering matches within a single response, not an absolute value to compare across searches. 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. Each result includes a policy_id — save it to fetch the policy’s coverage criteria in the next step.

List Policies API

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

Step 5: Get Policy Coverage Criteria

Steps 3 and 4 return a policy_id for each matching policy. Pass that policy_id to the Get Policy endpoint to retrieve the full policy detail — including the criteria_text, the medical-necessity criteria extracted from the policy as LLM-ready markdown.

curl -X GET "https://api-sandbox.penelope.health/v1/policies/uhc/MP.002/2026-01-01" \
  -H "x-api-key: $PENELOPE_API_KEY"

Response:

{
  "policy_id": "uhc/MP.002/2026-01-01",
  "policy_number": "MP.002.28",
  "title": "Brow Ptosis and Eyelid Repair",
  "effective_from_date": "2026-01-01",
  "summary": "This policy covers blepharoplasty and brow lift procedures when medically necessary for functional impairment...",
  "applicability": [
    {
      "payer_ids": ["KMQTZ"],
      "payer_names": ["UnitedHealthcare"],
      "lobs": ["commercial", "individual_aca"]
    }
  ],
  "code_groups": [
    {
      "code_system": "CPT",
      "relationship": "COVERS",
      "category": "Brow Ptosis Procedures",
      "codes": ["15822", "15823"],
      "descriptions": ["Upper eyelid blepharoplasty", "Repair blepharoptosis"]
    }
  ],
  "criteria_text": "## Coverage Criteria\n\nBlepharoplasty is considered medically necessary when ALL of the following are met:\n- Visual field obstruction documented..."
}

The response also includes the policy’s code_groups (covered/excluded codes), applicability (payers and lines of business), and summary. Use criteria_text when you need the coverage rules themselves — for example to drive a prior-authorization check or surface requirements to a user.

Get Policy API

Retrieve a single policy’s criteria text, code groups, and applicability by policy_id

Step 6: Download Policy Files

To work with the original source document rather than the extracted criteria, download the full file (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

​Prerequisites

​Step 1: Authenticate

​Step 2: List Lines of Business

List LOBs 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: Get Policy Coverage Criteria

Get Policy API

​Step 6: Download Policy Files

Download Policy API

​Next Steps

Key Concepts

Data Coverage

Examples

API Reference

Prerequisites

Step 1: Authenticate

Step 2: List Lines of Business

Step 3: Query Policies by Medical Codes

Filtering by Coverage Type

Step 4: Search Policies by Keywords

Step 5: Get Policy Coverage Criteria

Step 6: Download Policy Files

Next Steps