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",
"lobs": [
"commercial"
]
},
"limit": 3,
"include_applicability": true
}
'import requests
url = "https://api-sandbox.penelope.health/v1/policies/filter"
payload = {
"policies": {
"q": "blepharoplasty",
"lobs": ["commercial"]
},
"limit": 3,
"include_applicability": True
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
policies: {q: 'blepharoplasty', lobs: ['commercial']},
limit: 3,
include_applicability: true
})
};
fetch('https://api-sandbox.penelope.health/v1/policies/filter', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sandbox.penelope.health/v1/policies/filter",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'policies' => [
'q' => 'blepharoplasty',
'lobs' => [
'commercial'
]
],
'limit' => 3,
'include_applicability' => true
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sandbox.penelope.health/v1/policies/filter"
payload := strings.NewReader("{\n \"policies\": {\n \"q\": \"blepharoplasty\",\n \"lobs\": [\n \"commercial\"\n ]\n },\n \"limit\": 3,\n \"include_applicability\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-sandbox.penelope.health/v1/policies/filter")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"policies\": {\n \"q\": \"blepharoplasty\",\n \"lobs\": [\n \"commercial\"\n ]\n },\n \"limit\": 3,\n \"include_applicability\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.penelope.health/v1/policies/filter")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"policies\": {\n \"q\": \"blepharoplasty\",\n \"lobs\": [\n \"commercial\"\n ]\n },\n \"limit\": 3,\n \"include_applicability\": true\n}"
response = http.request(request)
puts response.read_body{
"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",
"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—blepharoplasty and repair of brow ptosis—focusing on restoration of function (visual field preservation, relief of dermatitis, prosthetic fit, and refractory blepharospasm). It defines objective functional...",
"score": 4.3,
"applicability": [
{
"payer_ids": [
"KRPCH"
],
"payer_names": [
"Blue Cross Blue Shield of Michigan"
],
"lobs": [
"commercial",
"medicare_advantage"
],
"state": "MI"
}
]
},
{
"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.2,
"applicability": [
{
"payer_ids": [
"JDGWJ"
],
"payer_names": [
"Blue Shield of California"
],
"lobs": [
"commercial",
"individual_aca",
"medicare_advantage"
],
"state": "CA"
}
]
},
{
"policy_id": "bcbssc/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.medicalpolicy.southcarolinablues.com/web/public/brands/medicalpolicy/external/external-policies/blepharoplasty-upper-and-lower",
"file_type": "html",
"listing_url": "https://www.medicalpolicy.southcarolinablues.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": [
{
"payer_ids": [
"EHMAH"
],
"payer_names": [
"BlueCross BlueShield of South Carolina State Health Plan"
],
"lobs": [
"commercial"
],
"state": "SC"
},
{
"payer_ids": [
"NYNYD",
"QWKFU"
],
"payer_names": [
"BlueCross BlueShield of South Carolina",
"BlueChoice HealthPlan of South Carolina"
],
"lobs": [
"commercial",
"individual_aca"
],
"state": "SC"
},
{
"payer_ids": [
"UDQSF"
],
"payer_names": [
"InStil Health"
],
"lobs": [
"individual_aca"
],
"state": "SC"
}
]
}
],
"limit": 3,
"offset": 0,
"has_more": true
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}API Reference
List Policies
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.
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",
"lobs": [
"commercial"
]
},
"limit": 3,
"include_applicability": true
}
'import requests
url = "https://api-sandbox.penelope.health/v1/policies/filter"
payload = {
"policies": {
"q": "blepharoplasty",
"lobs": ["commercial"]
},
"limit": 3,
"include_applicability": True
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
policies: {q: 'blepharoplasty', lobs: ['commercial']},
limit: 3,
include_applicability: true
})
};
fetch('https://api-sandbox.penelope.health/v1/policies/filter', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sandbox.penelope.health/v1/policies/filter",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'policies' => [
'q' => 'blepharoplasty',
'lobs' => [
'commercial'
]
],
'limit' => 3,
'include_applicability' => true
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sandbox.penelope.health/v1/policies/filter"
payload := strings.NewReader("{\n \"policies\": {\n \"q\": \"blepharoplasty\",\n \"lobs\": [\n \"commercial\"\n ]\n },\n \"limit\": 3,\n \"include_applicability\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-sandbox.penelope.health/v1/policies/filter")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"policies\": {\n \"q\": \"blepharoplasty\",\n \"lobs\": [\n \"commercial\"\n ]\n },\n \"limit\": 3,\n \"include_applicability\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.penelope.health/v1/policies/filter")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"policies\": {\n \"q\": \"blepharoplasty\",\n \"lobs\": [\n \"commercial\"\n ]\n },\n \"limit\": 3,\n \"include_applicability\": true\n}"
response = http.request(request)
puts response.read_body{
"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",
"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—blepharoplasty and repair of brow ptosis—focusing on restoration of function (visual field preservation, relief of dermatitis, prosthetic fit, and refractory blepharospasm). It defines objective functional...",
"score": 4.3,
"applicability": [
{
"payer_ids": [
"KRPCH"
],
"payer_names": [
"Blue Cross Blue Shield of Michigan"
],
"lobs": [
"commercial",
"medicare_advantage"
],
"state": "MI"
}
]
},
{
"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.2,
"applicability": [
{
"payer_ids": [
"JDGWJ"
],
"payer_names": [
"Blue Shield of California"
],
"lobs": [
"commercial",
"individual_aca",
"medicare_advantage"
],
"state": "CA"
}
]
},
{
"policy_id": "bcbssc/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.medicalpolicy.southcarolinablues.com/web/public/brands/medicalpolicy/external/external-policies/blepharoplasty-upper-and-lower",
"file_type": "html",
"listing_url": "https://www.medicalpolicy.southcarolinablues.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": [
{
"payer_ids": [
"EHMAH"
],
"payer_names": [
"BlueCross BlueShield of South Carolina State Health Plan"
],
"lobs": [
"commercial"
],
"state": "SC"
},
{
"payer_ids": [
"NYNYD",
"QWKFU"
],
"payer_names": [
"BlueCross BlueShield of South Carolina",
"BlueChoice HealthPlan of South Carolina"
],
"lobs": [
"commercial",
"individual_aca"
],
"state": "SC"
},
{
"payer_ids": [
"UDQSF"
],
"payer_names": [
"InStil Health"
],
"lobs": [
"individual_aca"
],
"state": "SC"
}
]
}
],
"limit": 3,
"offset": 0,
"has_more": true
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Authorizations
Body
application/json
POST body for /v1/policies/filter.
Policy filters. All fields optional; a policy must satisfy every field given, and within a list field matching any one value is enough. code_refs.match sets whether a policy must match any ref (default) or all refs.
Show child attributes
Show child attributes
Sort order. Defaults to relevance: ranked against q when given, otherwise against the descriptions of the filtered codes; with neither, policy-id order.
Available options:
policy_id_asc, policy_id_desc, title_asc, title_desc, policy_number_asc, policy_number_desc, relevance Example:
"relevance"
Maximum number of results to return
Required range:
1 <= x <= 100Example:
20
Number of results to skip for pagination
Required range:
x >= 0Example:
0
Include each policy's payer/LOB/geography applicability (regardless of when they applied).
Example:
true
Include code groups (grouped by code system, relationship, and category)
Example:
true
Response
Successful Response