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",
      "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": "anthem/abcbs/CG-SURG-03/2026-01-06",
      "policy_number": "CG-SURG-03",
      "title": "CG-SURG-03 Blepharoplasty, Blepharoptosis Repair, and Brow Lift",
      "effective_from_date": "2026-01-06",
      "file_url": "https://anthem.com/medpolicies/abcbs/active/gl_pw_a051144.html",
      "file_type": "html",
      "listing_url": "https://www.anthem.com/medpolicies/abcbs/active/fulllist.json",
      "summary": "This clinical UM guideline (CG-SURG-03) addresses medical necessity criteria for blepharoplasty, blepharoptosis (ptosis) repair, and brow lift procedures of the upper and lower eyelids and forehead when performed for functional/visual-field impairment. It distinguishes medically necessary, reconstru...",
      "score": 4.1,
      "applicability": [
        {
          "payer_ids": [
            "TBEZC"
          ],
          "payer_names": [
            "Anthem Blue Cross Blue Shield of Colorado"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "CO"
        },
        {
          "payer_ids": [
            "DRWRY"
          ],
          "payer_names": [
            "Anthem Blue Cross Blue Shield of Connecticut"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "CT"
        },
        {
          "payer_ids": [
            "VDCLI"
          ],
          "payer_names": [
            "Anthem Blue Cross Blue Shield of Georgia"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "GA"
        },
        {
          "payer_ids": [
            "AOQAR"
          ],
          "payer_names": [
            "Anthem Blue Cross Blue Shield of Indiana"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "IN"
        },
        {
          "payer_ids": [
            "DXTYZ"
          ],
          "payer_names": [
            "Anthem BlueCross BlueShield Kentucky"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "KY"
        },
        {
          "payer_ids": [
            "YJHSX"
          ],
          "payer_names": [
            "Anthem Blue Cross Blue Shield of Maine"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "ME"
        },
        {
          "payer_ids": [
            "XUAZF"
          ],
          "payer_names": [
            "Anthem Blue Cross Blue Shield Missouri"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "MO"
        },
        {
          "payer_ids": [
            "QCFIB"
          ],
          "payer_names": [
            "Anthem Blue Cross and Blue Shield New Hampshire"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "NH"
        },
        {
          "payer_ids": [
            "ERSOT"
          ],
          "payer_names": [
            "Anthem Blue Cross and Blue Shield Nevada"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "NV"
        },
        {
          "payer_ids": [
            "BHNXS"
          ],
          "payer_names": [
            "Anthem Blue Cross Blue Shield Ohio"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "OH"
        },
        {
          "payer_ids": [
            "VLFZU"
          ],
          "payer_names": [
            "Anthem Blue Cross and Blue Shield Wisconsin"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "WI"
        }
      ]
    }
  ],
  "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, or the request’s effective_date window when supplied. Set include_applicability=true to include the same current/date-windowed applicability, 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": "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",
      "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": "anthem/abcbs/CG-SURG-03/2026-01-06",
      "policy_number": "CG-SURG-03",
      "title": "CG-SURG-03 Blepharoplasty, Blepharoptosis Repair, and Brow Lift",
      "effective_from_date": "2026-01-06",
      "file_url": "https://anthem.com/medpolicies/abcbs/active/gl_pw_a051144.html",
      "file_type": "html",
      "listing_url": "https://www.anthem.com/medpolicies/abcbs/active/fulllist.json",
      "summary": "This clinical UM guideline (CG-SURG-03) addresses medical necessity criteria for blepharoplasty, blepharoptosis (ptosis) repair, and brow lift procedures of the upper and lower eyelids and forehead when performed for functional/visual-field impairment. It distinguishes medically necessary, reconstru...",
      "score": 4.1,
      "applicability": [
        {
          "payer_ids": [
            "TBEZC"
          ],
          "payer_names": [
            "Anthem Blue Cross Blue Shield of Colorado"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "CO"
        },
        {
          "payer_ids": [
            "DRWRY"
          ],
          "payer_names": [
            "Anthem Blue Cross Blue Shield of Connecticut"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "CT"
        },
        {
          "payer_ids": [
            "VDCLI"
          ],
          "payer_names": [
            "Anthem Blue Cross Blue Shield of Georgia"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "GA"
        },
        {
          "payer_ids": [
            "AOQAR"
          ],
          "payer_names": [
            "Anthem Blue Cross Blue Shield of Indiana"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "IN"
        },
        {
          "payer_ids": [
            "DXTYZ"
          ],
          "payer_names": [
            "Anthem BlueCross BlueShield Kentucky"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "KY"
        },
        {
          "payer_ids": [
            "YJHSX"
          ],
          "payer_names": [
            "Anthem Blue Cross Blue Shield of Maine"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "ME"
        },
        {
          "payer_ids": [
            "XUAZF"
          ],
          "payer_names": [
            "Anthem Blue Cross Blue Shield Missouri"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "MO"
        },
        {
          "payer_ids": [
            "QCFIB"
          ],
          "payer_names": [
            "Anthem Blue Cross and Blue Shield New Hampshire"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "NH"
        },
        {
          "payer_ids": [
            "ERSOT"
          ],
          "payer_names": [
            "Anthem Blue Cross and Blue Shield Nevada"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "NV"
        },
        {
          "payer_ids": [
            "BHNXS"
          ],
          "payer_names": [
            "Anthem Blue Cross Blue Shield Ohio"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "OH"
        },
        {
          "payer_ids": [
            "VLFZU"
          ],
          "payer_names": [
            "Anthem Blue Cross and Blue Shield Wisconsin"
          ],
          "lobs": [
            "commercial",
            "individual_aca",
            "medicaid",
            "medicare_advantage"
          ],
          "state": "WI"
        }
      ]
    }
  ],
  "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; fields are AND'd together, and within a list field multiple values are OR'd. code_refs.match selects OR ('any', default) vs AND ('all') across 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. Returns current applicability by default, or — when a policies.effective_date window is given — the applicability in effect during that window.

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

List LOBs Get Policy Updates