Get Clinical Questions

get_clinical_questions takes a pharmacy claim tuple, pins down the line of business and indication, and returns the payer’s clinical question set — each question carrying a structured citation back to the underlying policy. Pass the resolved questions and the user’s answers as clinical_answers on Fill Prior Authorization.

Parameters

Name	Type	Required	Description
`bin`	string	yes	Pharmacy claim BIN (6 digits).
`state`	string	yes	Two-letter state code for the member (e.g. `"CA"`).
`drug_name`	string	yes	Drug brand (e.g. `"wegovy"`). Use Search Drugs if the caller only has a free-text string.
`icd_code`	string	yes	ICD-10 diagnosis code (e.g. `"E66.01"`).
`pcn`	string	no	Processor control number. Tiebreaker for shared-processor BINs.
`group_id`	string	no	Group ID. Tiebreaker for shared-processor BINs.
`member_id`	string	no	Member ID. The leading alpha prefix often disambiguates LOBs on shared BIN/PCN pairs (e.g. BIN `003858` / PCN `A4` hosts both ESI Commercial and Humana Part D).

Example

Python
TypeScript

from simplex import (
    ClinicalQuestion,
    ClinicalQuestionCitation,
    ClinicalQuestionsRouting,
    GetClinicalQuestionsResponse,
    SimplexClient,
    SimplexError,
)

client = SimplexClient()

try:
    response: GetClinicalQuestionsResponse = client.get_clinical_questions(
        bin="003858",
        state="CA",
        drug_name="wegovy",
        icd_code="E66.01",
        pcn="A4",
        member_id="4XS1234567",
    )

    print("matched:", response.get("matched"))
    print("coverage_status:", response.get("coverage_status"))
    print("lob_id:", response.get("lob_id"))

    routing: ClinicalQuestionsRouting = response.get("routing") or {}
    print(f"PBM: {routing.get('pbm_name')}")
    print(f"LOB: {routing.get('line_of_business')}")
    print(f"Plan/Group: {routing.get('plan_name_or_group')}")
    print(f"Confidence: {routing.get('confidence')}")

    questions: list[ClinicalQuestion] = response.get("questions") or []
    for i, q in enumerate(questions, 1):
        req = "required" if q.get("required") else "optional"
        print(f"{i}. [{q.get('input_type')}, {req}] {q.get('prompt')}")
        citation: ClinicalQuestionCitation | None = q.get("citation")
        if citation:
            print(
                f"   ↳ {citation.get('policy_id')} "
                f"§{citation.get('section')} "
                f"({citation.get('effective_date')})"
            )
except SimplexError as e:
    print(f"Simplex error: {e}")

import { SimplexClient, SimplexError } from "simplex-ts";

const client = new SimplexClient();

try {
  const response = await client.getClinicalQuestions({
    bin: "003858",
    state: "CA",
    drugName: "wegovy",
    icdCode: "E66.01",
    pcn: "A4",
    memberId: "4XS1234567",
  });

  console.log("matched:", response.matched);
  console.log("coverage_status:", response.coverageStatus);
  console.log("lob_id:", response.lobId);

  const { routing } = response;
  console.log(`PBM: ${routing?.pbmName}`);
  console.log(`LOB: ${routing?.lineOfBusiness}`);
  console.log(`Plan/Group: ${routing?.planNameOrGroup}`);
  console.log(`Confidence: ${routing?.confidence}`);

  (response.questions ?? []).forEach((q, i) => {
    const req = q.required ? "required" : "optional";
    console.log(`${i + 1}. [${q.inputType}, ${req}] ${q.prompt}`);
    if (q.citation) {
      console.log(
        `   ↳ ${q.citation.policyId} §${q.citation.section} ` +
          `(${q.citation.effectiveDate})`
      );
    }
  });
} catch (e) {
  if (e instanceof SimplexError) {
    console.error(`Simplex error: ${e.message}`);
  }
}

Response

Field	Type	Description
`matched`	boolean	Whether the tuple resolved to a specific LOB/policy.
`coverage_status`	string	Coverage verdict for the drug under the resolved plan (e.g. `"covered_with_pa"`, `"not_covered"`).
`lob_id`	string	Internal identifier for the resolved line of business.
`rationale`	string	Human-readable explanation of how the claim tuple was routed.
`routing`	object	`pbm_name`, `line_of_business`, `plan_name_or_group`, `confidence`.
`questions`	array	Clinical questions the payer requires for this drug + indication.
`sources`	array	Policy documents consulted, with `source_name` and `fetch_timestamp`.

Question shape

Each entry in questions has:

Field	Type	Description
`prompt`	string	The question text, as written in payer policy.
`input_type`	string	`"boolean"`, `"text"`, `"number"`, `"date"`, or `"choice"`.
`required`	boolean	Whether the payer treats this answer as mandatory.
`citation`	object	`policy_id`, `section`, `effective_date`, `url`, `verbatim_quote` — show to reviewers as the source.

{
  "matched": true,
  "coverage_status": "covered_with_pa",
  "lob_id": "esi_commercial_std",
  "routing": {
    "pbm_name": "Express Scripts",
    "line_of_business": "Commercial",
    "plan_name_or_group": "ESI Commercial Standard Formulary",
    "confidence": "high"
  },
  "questions": [
    {
      "prompt": "Does the patient have a BMI ≥ 30 kg/m²?",
      "input_type": "boolean",
      "required": true,
      "citation": {
        "policy_id": "ESI-OBES-2024-03",
        "section": "Coverage Criteria §2.a",
        "effective_date": "2024-03-01"
      }
    }
  ]
}

Next step

Combine the patient/prescriber/drug data with the user’s answers to these questions and call Fill Prior Authorization.

​Parameters

​Example

​Response

​Question shape

​Next step

Parameters

Example

Response

Question shape

Next step