Getting Started - Penelope

Find the policy for a payer, line of business, and medical code, then retrieve its medical-necessity criteria. This quickstart uses UnitedHealthcare commercial policy criteria for HCPCS code J0490 (belimumab) as an example.

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 through the x-api-key header. Store your API key in an environment variable before you make a request:

export PENELOPE_API_KEY="your_api_key_here"

curl -sS "https://api-sandbox.penelope.health/health" \
  -H "x-api-key: $PENELOPE_API_KEY"

If your key is valid, you receive a 200 response. See Authentication for error handling and security guidance.

Step 2: Find Matching Policies

Filter by the payer’s Stedi payer ID, line-of-business category, and medical code. This workflow assumes you know the payer ID and LOB category for the patient.

If you do not know these values, see Discover Payer and Line-of-Business Values below.

curl -sS -X POST "https://api-sandbox.penelope.health/v1/policies/filter" \
  -H "x-api-key: $PENELOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policies": {
      "payer_ids": ["KMQTZ"],
      "lobs": ["commercial"],
      "code_refs": {
        "refs": [
          {
            "code_system": "HCPCS",
            "codes": ["J0490"],
            "relationship": ["COVERS", "REFERENCES"]
          }
        ]
      }
    },
    "include_code_groups": true,
    "limit": 10
  }'

Search both COVERS and REFERENCES. A relevant policy can explicitly cover the code or mention it without making a coverage decision in the code list. Including both relationships prevents a relevant policy from being excluded. Results are relevance-ranked by default. Review each result’s title, summary, and code groups. Copy the complete policy_id from the result that best matches the service and patient context.

List Policies API

See every policy filter and response field

Step 3: Get the Policy Criteria

Pass the selected policy_id to the Get Policy endpoint. A policy_id contains the source, canonical policy ID, and effective date, so copy the complete value into the URL.

curl -sS "https://api-sandbox.penelope.health/v1/policies/uhc/E0046/2025-12-01" \
  -H "x-api-key: $PENELOPE_API_KEY"

The response automatically includes criteria_text: the policy’s medical-necessity criteria as LLM-ready markdown. Evaluate this text against the patient’s medical notes to identify documentation gaps.

Get Policy API

Retrieve criteria text, code groups, and applicability for one policy

Additional Ways to Find a Policy

Discover Payer and Line-of-Business Values

Use List LOBs when you need to find a payer’s Stedi payer ID, LOB category, or a specific 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
}

Use payer_id and lob for the Step 2 filters. Use lob_id when you need to restrict a policy search to one specific line of business.

List LOBs API

View all filtering options and response fields

Search Policies by Keyword

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": "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": null,
      "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": 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": "2026-09-01",
      "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.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. Pass it to the Get Policy endpoint from Step 3 to retrieve the policy criteria.

List Policies API

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

Optional: Download the 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 -sS "https://api-sandbox.penelope.health/v1/policies/uhc/E0046/2025-12-01/download-url" \
  -H "x-api-key: $PENELOPE_API_KEY"

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

curl -sS "https://api-sandbox.penelope.health/v1/policies/uhc/E0046/2025-12-01/download-url?variant=text" \
  -H "x-api-key: $PENELOPE_API_KEY"

The presigned URL is short-lived. 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: Find Matching Policies

List Policies API

​Step 3: Get the Policy Criteria

Get Policy API

​Additional Ways to Find a Policy

​Discover Payer and Line-of-Business Values

List LOBs API

​Search Policies by Keyword

List Policies API

​Optional: Download the Policy Files

Download Policy API

​Next Steps

Key Concepts

Data Coverage

Examples

API Reference

Prerequisites

Step 1: Authenticate

Step 2: Find Matching Policies

Step 3: Get the Policy Criteria

Additional Ways to Find a Policy

Discover Payer and Line-of-Business Values

Search Policies by Keyword

Optional: Download the Policy Files

Next Steps