Examples - Penelope

Authentication

All API requests require an API key passed in the x-api-key header:

curl -H "x-api-key: your-api-key" https://api.penelope.health/v1/lobs

Example Use Cases

Use Case 1: Check Coverage for a Procedure

Scenario: Verify if Aetna Commercial insurance covers CPT code 15823 (upper eyelid blepharoplasty). Step 1: Get Aetna Commercial lob_id

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
}

Step 2: Check if the line of business covers CPT 15823

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"
          ]
        }
      ]
    },
    "lob_ids": [
      "HPQRS_commercial_US_"
    ]
  }
}'

Response:

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

Result: CPT 15823 is covered by Aetna Commercial under the Eyelid Surgery policy. The applicability field confirms this policy applies to all Aetna lines of business nationwide.

Set "include_code_groups": true in the request body to see all codes grouped by system and relationship type.

Use Case 2: Search Policies by Topic

Scenario: Search for policies related to “blepharoplasty” to understand coverage across payers.

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",
    "retired": false
  },
  "sort": "relevance",
  "limit": 3,
  "include_applicability": true
}'

Response:

{
  "data": [
    {
      "policy_id": "medicare/article/56503/2025-01-01",
      "policy_number": "56503",
      "title": "Billing and Coding: Blepharoplasty, Eyelid Surgery, and Brow Lift",
      "effective_from_date": "2025-01-01",
      "effective_to_date": null,
      "file_url": "https://www.cms.gov/medicare-coverage-database/view/article.aspx?articleid=56503",
      "file_type": "md",
      "listing_url": "https://downloads.cms.gov/medicare-coverage-database/downloads/exports/current_article.zip",
      "summary": "<p><span style=\"line-height: 115%;\">The information in this article contains billing, coding or other guidelines that complement the Local Coverage Determination (LCD) for Blepharoplasty, Eyelid Surgery, and Brow Lift L34411.</span></p>\n<p><span style=\"line-height: 115%;\">&nbsp;</span></p>\n<p><span ...",
      "score": 4.3,
      "applicability": [
        {
          "payer_ids": [
            "HPQRS",
            "KMQTZ",
            "UYORK"
          ],
          "payer_names": [
            "Aetna",
            "UnitedHealthcare",
            "Humana"
          ],
          "lobs": [
            "medicare_advantage"
          ],
          "state": "AL"
        },
        {
          "payer_ids": [
            "MNFSB"
          ],
          "payer_names": [
            "Medicare Alabama Part B"
          ],
          "lobs": [
            "medicare_part_b"
          ],
          "state": "AL"
        },
        {
          "payer_ids": [
            "QDNGA"
          ],
          "payer_names": [
            "Medicare Alabama Part A"
          ],
          "lobs": [
            "medicare_part_a"
          ],
          "state": "AL"
        },
        "... (18 more)"
      ],
      "code_groups": null
    },
    {
      "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.2,
      "applicability": [
        {
          "payer_ids": [
            "KRPCH"
          ],
          "payer_names": [
            "Blue Cross Blue Shield of Michigan"
          ],
          "lobs": [
            "commercial",
            "medicare_advantage"
          ],
          "state": "MI"
        }
      ],
      "code_groups": null
    },
    {
      "policy_id": "centene/CP.VP.07/2025-08-01",
      "policy_number": "CP.VP.07",
      "title": "Blepharoplasty, Ptosis and Canthoplasty",
      "effective_from_date": "2025-08-01",
      "effective_to_date": null,
      "file_url": "https://www.pshpgeorgia.com/content/dam/centene/peachstate/pdfs/FINAL_CP.VP.07_R.pdf",
      "file_type": "pdf",
      "listing_url": "https://www.pshpgeorgia.com/providers/resources/clinical-payment-policies.html",
      "summary": "This clinical policy defines medical-necessity criteria for functional upper eyelid blepharoplasty, brow ptosis repair, blepharoptosis repair, and canthoplasty (canthus reconstruction) performed to relieve visual-field obstruction from eyelid or brow malposition. Covered treatment requires documente...",
      "score": 4.1,
      "applicability": [
        {
          "payer_ids": [
            "IMJGY"
          ],
          "payer_names": [
            "Centene (Medical)"
          ],
          "lobs": [
            "medicaid"
          ],
          "state": "GA"
        }
      ],
      "code_groups": null
    }
  ],
  "limit": 3,
  "offset": 0,
  "has_more": false
}

Result: dedicated blepharoplasty policies rank first, ordered by relevance across publishers. The applicability field shows which payers, lines of business, and states each policy applies to.

Use Case 3: Query Historical Policy Versions

Scenario: Check what policies were active on a specific date, or retrieve all policy versions. Option A: Query policies active on a specific past date

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"
          ]
        }
      ]
    },
    "effective_date": {
      "end": "2024-06-15"
    }
  }
}'

Response:

{
  "data": [
    {
      "policy_id": "medicare/lcd/34411/2021-05-20",
      "policy_number": "34411",
      "title": "Blepharoplasty, Eyelid Surgery, and Brow Lift",
      "effective_from_date": "2021-05-20",
      "effective_to_date": null,
      "file_url": "https://www.cms.gov/medicare-coverage-database/view/lcd.aspx?lcdid=34411",
      "file_type": "md",
      "listing_url": "https://downloads.cms.gov/medicare-coverage-database/downloads/exports/current_lcd.zip",
      "summary": "<p>Blepharoplasty, blepharoptosis repair, and brow lift are surgeries that may be performed to improve function or provided strictly for cosmetic reasons. Medicare considers surgeries performed to improve function as reasonable and necessary. Surgeries performed solely for cosmetic reasons are not c...",
      "score": 4.3,
      "applicability": null,
      "code_groups": null
    },
    {
      "policy_id": "centene/CP.VP.07/2022-01-01",
      "policy_number": "CP.VP.07",
      "title": "Blepharoplasty-Ptosis-Repair-and-Canthoplasty",
      "effective_from_date": "2022-01-01",
      "effective_to_date": "2025-08-01",
      "file_url": "https://www.ambetterhealth.com/content/dam/centene/policies/vision-policies/CP.VP.07-Blepharoplasty-Ptosis-Repair-and-Canthoplasty.pdf",
      "file_type": "pdf",
      "listing_url": "https://www.homestatehealth.com/providers/tools-resources/clinical-payment-policies.html",
      "summary": "This clinical policy addresses medical-necessity criteria for functional upper-eyelid blepharoplasty, blepharoptosis (ptosis) repair, brow ptosis repair, and canthoplasty in health plans affiliated with Centene Corporation. Coverage focuses on eyelid or brow encroachment causing visual-axis or super...",
      "score": 4.2,
      "applicability": null,
      "code_groups": null
    },
    {
      "policy_id": "medicare/lcd/34028/2021-03-21",
      "policy_number": "34028",
      "title": "Blepharoplasty, Blepharoptosis Repair and Surgical Procedures of the Brow",
      "effective_from_date": "2021-03-21",
      "effective_to_date": null,
      "file_url": "https://www.cms.gov/medicare-coverage-database/view/lcd.aspx?lcdid=34028",
      "file_type": "md",
      "listing_url": "https://downloads.cms.gov/medicare-coverage-database/downloads/exports/current_lcd.zip",
      "summary": "<p>Compliance with the provisions in this policy may be monitored and addressed through post payment data analysis and subsequent medical review audits.</p>\n<p><strong>History/Background and/or General Information</strong></p>\n<p>Blepharoplasty may be performed for functional, reconstructive or cosm...",
      "score": 4.1,
      "applicability": null,
      "code_groups": null
    }
  ],
  "limit": 20,
  "offset": 0,
  "has_more": false
}

Option B: Get all policy versions (including historical)

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"
          ]
        }
      ]
    }
  }
}'

Response:

{
  "data": [
    {
      "policy_id": "regence/M-SUR12_05/2026-03-01",
      "policy_number": "M-SUR12_05",
      "title": "Blepharoplasty, Eyelid Surgery, and Brow Lift",
      "effective_from_date": "2026-03-01",
      "effective_to_date": null,
      "file_url": "https://beonbrand.getbynder.com/asset/a7f0f68c-4530-46b0-866d-08042a212516/Blepharoplasty-Eyelid-Surgery-and-Brow-Lift.pdf",
      "file_type": "pdf",
      "listing_url": "https://www.regence.com/provider/library/policies-guidelines/medical-policy/ma-medical-policy",
      "summary": "This Medicare Advantage medical policy addresses blepharoplasty, eyelid surgery, blepharoptosis repair, and brow lift procedures, with emphasis on determining medical necessity when excess eyelid or brow tissue causes functional visual-field impairment. Blepharoplasty removes or repairs excess upper...",
      "score": 4.3,
      "applicability": null,
      "code_groups": null
    },
    {
      "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.2,
      "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.1,
      "applicability": null,
      "code_groups": null
    }
  ],
  "limit": 20,
  "offset": 0,
  "has_more": false
}

Result: By omitting date filters, you can see all versions of a policy, useful for tracking policy changes over time.

By default (omitting date filters), all policy versions are returned. Use effective_date and retired filters to narrow by date range or active status.

​Authentication

​Example Use Cases

​Use Case 1: Check Coverage for a Procedure

​Use Case 2: Search Policies by Topic

​Use Case 3: Query Historical Policy Versions

Authentication

Example Use Cases

Use Case 1: Check Coverage for a Procedure

Use Case 2: Search Policies by Topic

Use Case 3: Query Historical Policy Versions