# Authentication Source: https://docs.penelope.health/api-reference/authorization ### API Key Authentication Penelope uses API key authentication for secure access to the API. Each request must include your API key in the `x-api-key` header. #### Obtaining Your API Key Contact the Penelope team to receive your unique API key. Your key will be securely stored and validated. #### Making Authenticated Requests Include your API key in the `x-api-key` header for all API requests: **Example Request**: ```bash theme={null} curl -X GET https://api.penelope.health/v1/lobs \ -H "x-api-key: your_api_key_here" ``` **Example with a Request Body**: ```bash theme={null} curl -X POST "https://api.penelope.health/v1/policies/filter" \ -H "x-api-key: your_api_key_here" \ -H "Content-Type: application/json" \ -d '{"policies": {"q": "diabetes"}, "limit": 10}' ``` #### Error Responses **403 Forbidden** - Missing `x-api-key` header: ```json theme={null} { "detail": "Not authenticated" } ``` **401 Unauthorized** - Invalid API key: ```json theme={null} { "detail": "Invalid API key" } ``` #### Security Best Practices * **Never expose your API key** in client-side code, public repositories, or logs * Store API keys as environment variables or in secure configuration management systems * **HTTPS required**: All requests must use HTTPS in production * Contact the Penelope team immediately if your API key is compromised # Get Policy Source: https://docs.penelope.health/api-reference/get-policy /api-reference/openapi.json get /v1/policies/{policy_id} Get a single policy by policy_id with its applicability, code groups, and criteria text. # Get Policy Download Url Source: https://docs.penelope.health/api-reference/get-policy-download-url /api-reference/openapi.json get /v1/policies/{policy_id}/download-url Get a presigned URL to download the policy file. The URL is short-lived (~15 minutes) — request it just before use, don't cache it. # Health Check Source: https://docs.penelope.health/api-reference/health-check /api-reference/openapi.json get /health Health check endpoint. # List LOBs Source: https://docs.penelope.health/api-reference/list-lobs /api-reference/openapi.json get /v1/lobs List lines of business with optional filtering. Filter by LOB categories, payer IDs, and/or states. # List Payers Source: https://docs.penelope.health/api-reference/list-payers /api-reference/openapi.json get /v1/payers List insurance payers with optional LOB filtering. Returns every payer with at least one policy, past or present. `lobs` narrows to payers whose policies cover one of those LOB categories. # List Policies Source: https://docs.penelope.health/api-reference/list-policies /api-reference/openapi.json post /v1/policies/filter List medical policies with structured filters. Supports filtering by medical codes, payers, LOBs, LOB categories, states, effective dates, and full-text search (q). Results default to relevance order: ranked against q when given, otherwise against the descriptions of the filtered codes (first 20) — non-matching policies are still returned, sorted last. With neither q nor codes, results come back in policy-id order. Payer/LOB/state filters use current applicability by default, the request's effective_date window when supplied, or all-time applicability with retired=true (a retired policy has no current applicability, so filtering it by today would match nothing). Set include_applicability=true to include every LOB each policy was ever linked to, and include_code_groups=true for associated codes. # Notable Input Types Source: https://docs.penelope.health/api-reference/notable_input_types ### State Codes Reference Full list of valid US state codes for the `states` field in line-of-business responses: **Standard States** (2-letter codes): AL, AK, AZ, AR, CA, CO, CT, DE, FL, GA, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY **District & Territories**: DC, PR, GU, VI, AS, CNMI **Medicare Contractor Subdivisions**: * NF (Northern California) * SF (Southern California) * DN (Downstate New York) * QN (Queens, New York) * UN (Upstate New York) * EM (Eastern Missouri) * WM (Western Missouri) ### Line of Business Reference | Line of Business | Description | Coverage | | -------------------- | ------------------------------------ | ----------------------------------------------- | | `commercial` | Private employer-sponsored insurance | Employer groups, individuals | | `medicare_part_a` | Medicare hospital insurance | Inpatient hospital, skilled nursing, hospice | | `medicare_part_b` | Medicare medical insurance | Outpatient, physician services, preventive care | | `medicare_advantage` | Medicare managed care (Part C) | Combined A+B benefits through private insurers | | `medicaid` | State-federal public insurance | Low-income individuals and families | | `individual_aca` | ACA marketplace plans | Individual and small group coverage | ### Medical Code System Reference | System | Description | Format | Example | | -------------- | ----------------------------------- | ---------------------------------- | ---------------- | | CPT | Current Procedural Terminology | 5-digit numeric or 4-digit + F/T/U | `19318`, `0001F` | | HCPCS Level 1 | Same as CPT | Same as CPT | `99213` | | HCPCS Level 2 | Non-physician services and supplies | 1 letter + 4 digits | `J1234`, `A0425` | | CPT Modifier | Procedure modifiers | 2-character | `50`, `59`, `LT` | | HCPCS Modifier | Service modifiers | 2-character | `HW`, `F1` | | ICD-10-CM | Diagnosis codes | Alphanumeric, 3-7 characters | `E11.9`, `N62` | | ICD-10-PCS | Procedure codes (inpatient) | 7-character alphanumeric | `DB26HZZ` | ### Date & Retirement Filters The policy filter provides two complementary date filters: #### `effective_date` — date range overlap Returns policies in effect during a given window — those whose effective period overlaps it. Uses an `EffectiveDateFilter` object: | Field | Type | Description | | ------- | ------ | -------------------------------------------------------------------------- | | `start` | `date` | Window start (inclusive) — policies in effect on or after this date. | | `end` | `date` | Window end (inclusive) — policies that take effect on or before this date. | #### `retired` — active vs. retired Filters on the policy's own effective period, over all time: | Value | Description | | ------- | ------------------------------------------------------- | | `false` | Not retired — including policies that take effect later | | `true` | Retired policies only (end date in the past) | | omitted | All policies | **Common patterns:** | Goal | Filter | | ------------------------------------------------------ | ---------------------------------------------------------------- | | Policies that have not retired, upcoming ones included | `"retired": false` | | Retired policies | `"retired": true` | | Policies effective on a specific date | `"effective_date": {"start": "2025-06-15", "end": "2025-06-15"}` | | Policies effective after a date | `"effective_date": {"start": "2025-01-01"}` | | Policies effective before a date | `"effective_date": {"end": "2025-01-01"}` | Note: `effective_to_date` being null in responses means the policy is currently active; non-null means it retired on that date — either superseded by a newer version, or closed with no successor. # Ready Check Source: https://docs.penelope.health/api-reference/ready-check /api-reference/openapi.json get /ready Readiness check. Returns 200 if DB is accessible, 503 otherwise. # Technical Notes Source: https://docs.penelope.health/api-reference/technical_notes ### Base URL Production: `https://api.penelope.health` Sandbox: `https://api-sandbox.penelope.health` ### Pagination All list endpoints return **20 results** by default, configurable up to **100** via the `limit` parameter. In the sandbox environment, endpoints return a fixed set of results with **no pagination** — `limit` and `offset` parameters are ignored. All endpoints return a maximum of **20 results**, except the [List Payers](/api-reference/list-payers) endpoint. ### Date & Time Formats * **Dates**: ISO 8601 date format (`YYYY-MM-DD`) * Example: `2025-01-07` * **Timestamps**: ISO 8601 datetime format with UTC timezone (`YYYY-MM-DDTHH:MM:SSZ`) * Example: `2025-01-07T14:32:15Z` ### Rate Limits Sandbox endpoints are rate-limited to **100 requests per minute** per API key. When exceeded, the API returns a `429 Too Many Requests` response with a `Retry-After` header. # Data Coverage Source: https://docs.penelope.health/documentation/data_coverage Penelope provides comprehensive coverage data from major US health insurers and Medicare: ### Data Sources * **Insurance Payers**: such as UnitedHealthcare, Cigna, Aetna, Anthem, Humana, Blue Cross Blue Shield of Michigan, Blue Shield of California, CareFirst, Florida Blue... * **Medicare**: CMS National Coverage Determinations (NCDs), Local Coverage Determinations (LCDs), and Local Coverage Articles (LCAs) For a full list of our payers, call the [List Payers](/api-reference/list-payers) endpoint, and [List LOBs](/api-reference/list-lobs) for the lines of business under each payer. ### Coverage Statistics #### Medical Coding Systems * **CPT Codes** (Current Procedural Terminology): \~10,000 procedure codes * **CPT Modifiers**: \~200 procedure modifiers * **HCPCS Level 2 Codes**: \~6,500 alphanumeric codes for services and supplies * **HCPCS Modifiers**: \~50 service modifiers * **ICD-10-CM Codes** (Diagnosis): \~72,000 diagnosis codes with hierarchical structure * **ICD-10-PCS Codes** (Procedures): \~78,000 inpatient procedure codes #### Insurance Coverage Data * **Insurance Payers**: the payers as per our [List Payers](/api-reference/list-payers) endpoint, plus Medicare * **Lines of Business**: Hundreds of lines of business across commercial, Medicare, Medicaid, and exchange markets * **Coverage Policies**: Thousands of policies across both medical and pharmacy benefits. Topics we cover include: * **Medical benefit**: infusion drugs and biologics, surgical procedures, radiology and advanced imaging, laboratory and genetic testing, and pain management * **Pharmacy benefit**: GLP-1 receptor agonists for type 2 diabetes and weight loss, behavioral health such as ADHD medications, and other specialty drugs * **Pharmacy Formularies**: Drug prior-authorization requirements by plan and formulary * **Medicare Contractors**: 20+ Medicare Administrative Contractors (MACs) with state jurisdictions ### Update Frequency * **Medicare data**: Updated quarterly with CMS releases * **Commercial policies**: Monitored continuously, updated as payers publish revisions * **Medical codes**: Updated annually (CPT/HCPCS) or as CMS releases updates (ICD-10-CM) # Examples Source: https://docs.penelope.health/documentation/examples ## Authentication All API requests require an API key passed in the `x-api-key` header: ```bash theme={null} 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` ```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 } ``` **Step 2**: Check if the line of business covers CPT 15823 ```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" ] } ] }, "lob_ids": [ "HPQRS_commercial_US_" ] } }' ``` **Response:** ```json theme={null} { "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. ```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", "retired": false }, "sort": "relevance", "limit": 3, "include_applicability": true }' ``` **Response:** ```json theme={null} { "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": "

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.

\n

 

\n

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": "

Compliance with the provisions in this policy may be monitored and addressed through post payment data analysis and subsequent medical review audits.

\n

History/Background and/or General Information

\n

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) ```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" ] } ] } } }' ``` **Response:** ```json theme={null} { "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. *** # Getting Started Source: https://docs.penelope.health/documentation/getting_started Find a medical policy and retrieve its medical-necessity criteria 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 [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 through the `x-api-key` header. Store your API key in an environment variable before you make a request: ```bash theme={null} export PENELOPE_API_KEY="your_api_key_here" ``` ```bash theme={null} 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](/api-reference/authorization) 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](#discover-payer-and-line-of-business-values) below. ```bash theme={null} 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. 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. ```bash theme={null} 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. 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`. ```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 } ``` 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. 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. ```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": "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": "

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.

\n

 

\n

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`. ```bash theme={null} 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: ```bash theme={null} 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. Get temporary download links for policy documents ## Next Steps Understand the data model and relationships See which payers and plans are covered More examples Complete API documentation # Welcome to Penelope Source: https://docs.penelope.health/documentation/introduction At Penelope, we believe that there is translation gap between providers (doctors, physician practices, hospitals) and payers (insurance companies). The revenue cycle is fundamentally an exercise in converting patient notes into payer reimbursement. Denials, where they occur, are increasingly caused by payers 'speaking a different language' from one another. The codes and modifiers one payer accepts, may arbitrarily differ from another, even for the same procedure. Our mission is to translate what billers say into what payers want. Our first tool, to do this, is to use payer policies to their fullest extent. ## Overview The Penelope API provides programmatic access to our proprietary coverage dataset containing: * **Medical coverage policies** from major US payers (UnitedHealthcare, Cigna, Aetna, Humana, Anthem) and CMS Medicare (NCDs, LCDs) * **Lines of business** across commercial, individual exchange markets, Medicare, Medicare Advantage and Medicaid. * **Medical codes** including CPT procedure codes, HCPCS codes, and ICD-10-CM diagnosis codes * **Relationships** between policies and codes (coverage, exclusions, references) ### What You Can Do * **Verify coverage**: Check if a specific CPT code is covered by a line of business * **Research policies**: Search policies by medical codes or keywords * **Compare plans**: Find which plans cover specific procedures or diagnoses ### Quick Start Ready to make your first API call? Follow our [Getting Started guide](/documentation/getting_started) to: 1. Authenticate with your API key 2. List available lines of business 3. Query policies by medical codes 4. Search policies by keywords 5. Download policy documents # Key Concepts Source: https://docs.penelope.health/documentation/key_concepts ## Insurance Structure ``` Payer (Insurance Company) └─ OFFERS → Line of Business (Product) Medical Policy (Coverage Rules) ├─ APPLIES_TO → Line of Business (one policy → many LOBs) ├─ COVERS → Medical Code (Approved) ├─ DOES_NOT_COVER → Medical Code (Excluded) └─ REFERENCES → Medical Code (Mentioned) ``` * **Payer**: Insurance company or organization (e.g., UnitedHealthcare, Cigna) * **Line of Business**: Specific insurance product offered by a payer * **Line of Business Categories**: * `commercial`: Private employer-sponsored insurance * `medicare_part_a`: Medicare hospital insurance * `medicare_part_b`: Medicare medical insurance * `medicare_advantage`: Medicare managed care (Part C) * `medicaid`: State-federal public insurance * `individual_aca`: Affordable Care Act marketplace plans ## Medical Codes US healthcare uses standardized coding systems to identify procedures, services, and diagnoses: * **CPT (Current Procedural Terminology)**: 5-digit numeric codes for medical procedures and services * Use case: The primary standard for physician billing and reimbursement * Example: `19318` = Breast reduction * Maintained by American Medical Association (AMA) * **HCPCS Level II (Healthcare Common Procedure Coding System)**: Alphanumeric codes for non-physician services, supplies and drugs not covered by CPT. * Use case: Ambulances, DME (medical equipment) and drugs. * Example: `J1234` (Drug injection), `E0607` (Blood glucose monitor) * **ICD-10-CM (International Classification of Diseases, 10th Revision, Clinical Modification)**: Diagnosis codes describing a patient's condition or disease. * Use case: Establishes medical necessity of a procedure. * Example: `E11.9` (Type 2 diabetes mellitus without complications) ## Coverage Policies Medical coverage policies provide guidance on whether a payer's plan will reimburse a particular procedure. They can be seen as 'rulebooks'. A typical medical coverage policy includes two key sections: 1. Medical necessity criteria: These are the clinical conditions required for a procedure to be deemed reasonable. * Example: 'A blepharoplasty is deemed medically necessary ONLY IF upper visual field loss is present AND botulinum toxin injections trialled first are unsuccessful. 2. Coding logic: These are lists of procedural and diagnostic codes which are related to the policy. * These are CPT codes, HCPCS codes and ICD-10-CM codes. ### Policy-Code Relationships The Penelope API models three types of relationships between policies and medical codes: * **COVERS**: Policy explicitly covers this code * The code is approved for reimbursement under the policy * Indicates the procedure/service is covered for reimbursement if it is medically necessary * **DOES\_NOT\_COVER**: Policy explicitly excludes this code * The code is denied or considered not medically necessary * May indicate experimental, investigational, or cosmetic procedures * **REFERENCES**: Code is mentioned in the policy without explicit coverage decision * Useful for understanding policy scope. ## Medicare Framework Medicare policies (NCD, LCD, and LCA) represent the gold standard of US medical coverage. They are issued by the federal government and adhere to a strict hierarchy of authority. ### NCD (National Coverage Determination) * Issuer: CMS (Federal Centers for Medicare & Medicaid Services). * Scope: Nationwide. * Authority: Binding for all Medicare plans, including Medicare Advantage (Part C). * Function: NCDs set the baseline. If an NCD says "Covered," no local contractor or MA plan can deny it based on medical necessity, provided that the clinical criteria are met. ### LCD (Local Coverage Determination) * Issuer: MACs (Medicare Administrative Contractors). * Scope: Regional (specific states/jurisdictions). * Authority: Applies in the absence of an NCD. * Function: LCDs fill the gaps left by NCDs. They provide the detailed 'Medical Necessity' logic for procedures that don't have a national ruling. ### LCA (Local Coverage Article) * Issuer: MACs (attached to an LCD). * Function: The technical implementation guide. * Why it matters: While the LCD contains the text, the LCA contains the tables of CPT and ICD-10 codes. Both go hand in hand. **Note on Medicare Advantage (Part C).** Medicare Advantage plans (managed by private payers like Humana or UHC) are legally required to furnish, at minimum, the same benefits as Original Medicare. This means they must adhere to NCDs and LCDs. They cannot apply internal criteria that are more restrictive than the NCD/LCD applicable to the beneficiary's region. # Support & Resources Source: https://docs.penelope.health/documentation/support_and_resources ### Uptime * **API Status**: Monitor service health at `/health` endpoint ### Support For any of the below, please contact us at [mattijs@penelope.health](mailto:mattijs@penelope.health) * **Implementation Issues**: Report issues with the API or the data * **Documentation Issues**: Report inaccuracies or request clarifications * **Feature Requests**: Suggest new endpoints or data sources * **Anything** really, just let us know!