> ## Documentation Index
> Fetch the complete documentation index at: https://docs.penelope.health/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> A step-by-step guide to making your first Penelope API calls

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 [mattijs@penelope.health](mailto:mattijs@penelope.health))
* 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.

```bash theme={null}
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](/api-reference/authorization) docs for error handling and security best practices.

<Tip>
  Store your API key as an environment variable to avoid exposing it in code:

  ```bash theme={null}
  export PENELOPE_API_KEY="your_api_key_here"
  ```
</Tip>

## 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.

```bash theme={null}
curl -X GET "https://api-sandbox.penelope.health/v1/lobs" \
  -H "x-api-key: $PENELOPE_API_KEY"
```

**Response:**

```json theme={null}
{
  "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.

<Card title="List LOBs API" icon="list" href="/api-reference/list-lobs">
  View all filtering options and response fields
</Card>

## 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.

```bash theme={null}
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:**

```json theme={null}
{
  "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.

<Tip>
  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.
</Tip>

### 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

```bash theme={null}
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:**

```json theme={null}
{
  "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
}
```

<Card title="List Policies API" icon="file-medical" href="/api-reference/list-policies">
  Full documentation for code-based policy queries
</Card>

## 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.

```bash theme={null}
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:**

```json theme={null}
{
  "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.

<Card title="List Policies API" icon="magnifying-glass" href="/api-reference/list-policies">
  Use the `q` parameter for full-text search across policy titles and summaries
</Card>

## 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.

```bash theme={null}
curl -X GET "https://api-sandbox.penelope.health/v1/policies/uhc/MP.002/2026-01-01" \
  -H "x-api-key: $PENELOPE_API_KEY"
```

**Response:**

```json theme={null}
{
  "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.

<Card title="Get Policy API" icon="file-lines" href="/api-reference/get-policy">
  Retrieve a single policy's criteria text, code groups, and applicability by `policy_id`
</Card>

## 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`.

```bash theme={null}
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:**

```json theme={null}
{
  "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:

```bash theme={null}
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:**

```json theme={null}
{
  "url": "https://s3.example.com/presigned-url",
  "content_type": "text/markdown",
  "filename": "bcbsfl_01-90900-01_2025-07-15.md"
}
```

<Warning>
  The presigned URL expires after **1 hour**. Download the file promptly or request a fresh URL.
</Warning>

<Card title="Download Policy API" icon="download" href="/api-reference/get-policy-download-url">
  Get temporary download links for policy documents
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Key Concepts" icon="book" href="/documentation/key_concepts">
    Understand the data model and relationships
  </Card>

  <Card title="Data Coverage" icon="database" href="/documentation/data_coverage">
    See which payers and plans are covered
  </Card>

  <Card title="Examples" icon="code" href="/documentation/examples">
    More examples
  </Card>

  <Card title="API Reference" icon="rectangle-terminal" href="/api-reference/list-payers">
    Complete API documentation
  </Card>
</CardGroup>