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": "bcbsar/1997026/2026-09-01",
      "policy_number": "1997026",
      "title": "Blepharoplasty/Blepharoptosis",
      "effective_from_date": "2026-09-01",
      "file_url": "https://secure.arkansasbluecross.com/members/report.aspx?policyNumber=1997026&viewIntro=yes",
      "file_type": "html",
      "listing_url": "https://secure.arkansasbluecross.com/providers/coverage_policy.aspx",
      "summary": "Arkansas Blue Cross and Blue Shield Policy 1997026 addresses medically necessary versus cosmetic eyelid surgery, focusing on upper eyelid blepharoplasty, lower eyelid blepharoplasty, and blepharoptosis (ptosis, drooping eyelid) repair. Coverage is primarily outpatient surgical care; no specific age ...",
      "score": 4.2,
      "applicability": [
        {
          "payer_ids": [
            "GESBC"
          ],
          "payer_names": [
            "Arkansas Blue Cross and Blue Shield"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid"
          ],
          "state": "AR"
        }
      ]
    },
    {
      "policy_id": "bcbsar/1997026/2025-09-01",
      "policy_number": "1997026",
      "title": "Blepharoplasty/Blepharoptosis",
      "effective_from_date": "2025-09-01",
      "effective_to_date": "2026-09-01",
      "file_url": "https://secure.arkansasbluecross.com/members/report.aspx?policyNumber=1997026&viewIntro=yes",
      "file_type": "html",
      "listing_url": "https://secure.arkansasbluecross.com/providers/coverage_policy.aspx",
      "summary": "Arkansas Blue Cross and Blue Shield Surgery policy 1997026 addresses medically necessary eyelid surgery: upper eyelid blepharoplasty, lower eyelid blepharoplasty, and blepharoptosis (ptosis) repair. Current coverage requires a recommended InterQual determination; historical criteria specify function...",
      "score": 4.1,
      "applicability": [
        {
          "payer_ids": [
            "GESBC"
          ],
          "payer_names": [
            "Arkansas Blue Cross and Blue Shield"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid"
          ],
          "state": "AR"
        }
      ]
    }
  ],
  "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

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": "bcbsar/1997026/2026-09-01",
      "policy_number": "1997026",
      "title": "Blepharoplasty/Blepharoptosis",
      "effective_from_date": "2026-09-01",
      "file_url": "https://secure.arkansasbluecross.com/members/report.aspx?policyNumber=1997026&viewIntro=yes",
      "file_type": "html",
      "listing_url": "https://secure.arkansasbluecross.com/providers/coverage_policy.aspx",
      "summary": "Arkansas Blue Cross and Blue Shield Policy 1997026 addresses medically necessary versus cosmetic eyelid surgery, focusing on upper eyelid blepharoplasty, lower eyelid blepharoplasty, and blepharoptosis (ptosis, drooping eyelid) repair. Coverage is primarily outpatient surgical care; no specific age ...",
      "score": 4.2,
      "applicability": [
        {
          "payer_ids": [
            "GESBC"
          ],
          "payer_names": [
            "Arkansas Blue Cross and Blue Shield"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid"
          ],
          "state": "AR"
        }
      ]
    },
    {
      "policy_id": "bcbsar/1997026/2025-09-01",
      "policy_number": "1997026",
      "title": "Blepharoplasty/Blepharoptosis",
      "effective_from_date": "2025-09-01",
      "effective_to_date": "2026-09-01",
      "file_url": "https://secure.arkansasbluecross.com/members/report.aspx?policyNumber=1997026&viewIntro=yes",
      "file_type": "html",
      "listing_url": "https://secure.arkansasbluecross.com/providers/coverage_policy.aspx",
      "summary": "Arkansas Blue Cross and Blue Shield Surgery policy 1997026 addresses medically necessary eyelid surgery: upper eyelid blepharoplasty, lower eyelid blepharoplasty, and blepharoptosis (ptosis) repair. Current coverage requires a recommended InterQual determination; historical criteria specify function...",
      "score": 4.1,
      "applicability": [
        {
          "payer_ids": [
            "GESBC"
          ],
          "payer_names": [
            "Arkansas Blue Cross and Blue Shield"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid"
          ],
          "state": "AR"
        }
      ]
    }
  ],
  "limit": 3,
  "offset": 0,
  "has_more": true
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

x-api-key

string

header

required

Body

application/json

POST body for /v1/policies/filter.

policies

PolicyFilter · object | null

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

sort

enum<string>

default:relevance

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"

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 each policy's payer/LOB/geography applicability (regardless of when they applied).

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

Show child attributes

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