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/plans

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 plan ID

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
}

Step 2: Check if plan 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": [
      {
        "code_system": "CPTCode",
        "codes": [
          "15823"
        ],
        "relationship": [
          "COVERS"
        ]
      }
    ],
    "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": 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": "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/0084/2025-03-19",
      "policy_number": "0084",
      "title": "Eyelid Surgery",
      "effective_from_date": "2025-03-19",
      "effective_to_date": null,
      "file_url": "https://www.aetna.com/cpb/medical/data/1_99/0084.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 0084) defines medical necessity criteria for eyelid surgery including blepharoplasty, blepharoptosis (ptosis) repair, brow ptosis repair, ectropion/entropion repair, tarsal strip and canthoplasty procedures, and addresses intralesional and combinational inter...",
      "score": null,
      "applicability": null,
      "code_groups": null
    }
  ],
  "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 plan types 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"
  },
  "sort": "relevance",
  "limit": 3,
  "include_applicability": true
}'

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.30522271302239,
      "applicability": [
        {
          "payer_ids": [
            "OLQXL"
          ],
          "payer_names": [
            "Anthem Blue Cross Blue Shield of New York"
          ],
          "plan_types": [
            "commercial",
            "exchange",
            "medicaid",
            "medicare_advantage"
          ],
          "states": [
            "NY"
          ],
          "country_wide": false
        }
      ],
      "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.298693857443478,
      "applicability": [
        {
          "payer_ids": [
            "AOQAR"
          ],
          "payer_names": [
            "Anthem Blue Cross Blue Shield of Indiana"
          ],
          "plan_types": [
            "commercial",
            "exchange",
            "medicaid",
            "medicare_advantage"
          ],
          "states": [
            "IN"
          ],
          "country_wide": false
        },
        {
          "payer_ids": [
            "BHNXS"
          ],
          "payer_names": [
            "Anthem Blue Cross Blue Shield Ohio"
          ],
          "plan_types": [
            "commercial",
            "exchange",
            "medicaid",
            "medicare_advantage"
          ],
          "states": [
            "OH"
          ],
          "country_wide": false
        },
        {
          "payer_ids": [
            "DRWRY"
          ],
          "payer_names": [
            "Anthem Blue Cross Blue Shield of Connecticut"
          ],
          "plan_types": [
            "commercial",
            "exchange",
            "medicaid",
            "medicare_advantage"
          ],
          "states": [
            "CT"
          ],
          "country_wide": false
        },
        "... (8 more)"
      ],
      "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.262526242515746,
      "applicability": [
        {
          "payer_ids": [
            "DGOYK"
          ],
          "payer_names": [
            "Anthem Blue Cross Blue Shield of Virginia"
          ],
          "plan_types": [
            "commercial",
            "exchange",
            "medicaid",
            "medicare_advantage"
          ],
          "states": [
            "VA"
          ],
          "country_wide": false
        }
      ],
      "code_groups": null
    }
  ],
  "limit": 3,
  "offset": 0,
  "has_more": false
}

Result: Multiple Anthem regional policies cover blepharoplasty with similar criteria. The applicability field shows which payers (11 for abcbs), plan types, and states each policy applies to. Note that country_wide=false policies always have a non-null states array.

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

Response:

{
  "data": [
    {
      "node_id": "medicare/lcd/US/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",
      "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": null,
      "applicability": null,
      "code_groups": null
    },
    {
      "node_id": "medicare/lcd/US/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",
      "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": null,
      "applicability": null,
      "code_groups": null
    },
    {
      "node_id": "medicare/lcd/US/35004/2021-03-21",
      "policy_number": "35004",
      "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=35004",
      "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. <br /><br /><strong>History/Background and/or General Information</strong> <br /><br />Blepharoplasty may be performed for functional, reconstructi...",
      "score": null,
      "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": [
      {
        "code_system": "CPTCode",
        "codes": [
          "15823"
        ]
      }
    ]
  }
}'

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": 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": "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/0084/2025-03-19",
      "policy_number": "0084",
      "title": "Eyelid Surgery",
      "effective_from_date": "2025-03-19",
      "effective_to_date": null,
      "file_url": "https://www.aetna.com/cpb/medical/data/1_99/0084.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 0084) defines medical necessity criteria for eyelid surgery including blepharoplasty, blepharoptosis (ptosis) repair, brow ptosis repair, ectropion/entropion repair, tarsal strip and canthoplasty procedures, and addresses intralesional and combinational inter...",
      "score": null,
      "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.

Penelope API

​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