Skip to main content
POST
/
v1
/
policies
/
filter
List Policies
curl --request POST \
  --url https://api-sandbox.penelope.health/v1/policies/filter \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "policies": {
    "q": "blepharoplasty",
    "code_refs": [
      {
        "code_system": "CPTCode",
        "codes": [
          "<string>"
        ],
        "relationship": [
          "COVERS",
          "DOES_NOT_COVER",
          "REFERENCES"
        ]
      }
    ],
    "plan_ids": [
      "KMQTZ_commercial_US"
    ],
    "payer_ids": [
      "KMQTZ"
    ],
    "plan_types": [
      "commercial"
    ],
    "states": [
      "CA",
      "NY"
    ],
    "country_wide": true,
    "effective_date": {
      "start": "2025-01-01",
      "end": "2025-06-15"
    },
    "retired": false
  },
  "sort": "node_id_asc",
  "limit": 20,
  "offset": 0,
  "include_applicability": false,
  "include_code_groups": false
}
'
{
  "data": [
    {
      "node_id": "uhc/US/MP.002.28/2026-01-01",
      "policy_number": "MP.002.28",
      "title": "Brow Ptosis and Eyelid Repair",
      "effective_from_date": "2026-01-01",
      "file_url": "https://www.uhcprovider.com/content/dam/provider/docs/public/policies/comm-medical-drug/brow-ptosis-and-eyelid-repair.pdf",
      "listing_url": "https://www.uhcprovider.com/en/policies-protocols/comm-medical-drug-policies/comm-medical-drug-policies.html",
      "summary": "This policy covers blepharoplasty and brow lift procedures when medically necessary for functional impairment...",
      "score": 4.26
    },
    {
      "node_id": "uhc/US/MP.002.28/2026-01-01",
      "policy_number": "MP.002.28",
      "title": "Brow Ptosis and Eyelid Repair",
      "effective_from_date": "2026-01-01",
      "file_url": "https://www.uhcprovider.com/content/dam/provider/docs/public/policies/comm-medical-drug/brow-ptosis-and-eyelid-repair.pdf",
      "listing_url": "https://www.uhcprovider.com/en/policies-protocols/comm-medical-drug-policies/comm-medical-drug-policies.html",
      "summary": "This policy covers blepharoplasty and brow lift procedures when medically necessary for functional impairment...",
      "score": 4.26
    }
  ],
  "limit": 20,
  "offset": 0,
  "has_more": false
}

Authorizations

​
x-api-key
string
header
required

Body

application/json

POST body for /v1/policies/filter.

​
policies
PolicyFilter · object

Policy filters. All fields optional, combined with AND.

​
sort
enum<string>
default:node_id_asc

Sort order. Use 'relevance' with full-text search (q).

Available options:
node_id_asc,
node_id_desc,
title_asc,
title_desc,
policy_number_asc,
policy_number_desc,
relevance
Example:

"node_id_asc"

​
limit
integer
default:20

Maximum number of results to return

Required range: 1 <= x <= 100
Example:

20

​
offset
integer
default:0

Number of results to skip for pagination

Required range: x >= 0
Example:

0

​
include_applicability
boolean
default:false

Include payer/plan/geography applicability for each policy

Example:

true

​
include_code_groups
boolean
default:false

Include code groups (grouped by code system, relationship, and category)

Example:

true

Response

Successful Response

​
data
PolicyResult · object[]
required

Array of result objects

​
limit
integer
required

Maximum number of results requested

Example:

20

​
offset
integer
required

Number of results skipped for pagination

Example:

0

​
has_more
boolean
required

True if more results exist beyond this page

Example:

false