Fill Prior Authorization

fill_pa resolves the correct prior-authorization form for a (bin, pcn, state) tuple, stamps patient / prescriber / drug / clinical-answer data onto the template, merges any attached documents (e.g. chart notes) into a single fax-ready PDF, and uploads it to S3. The response includes a short-lived signed URL. Drug metadata (strength, quantity, day supply, route of administration) is assembled server-side from the drug_slug — callers should not pass it directly. Use Search Drugs to resolve a slug. The clinical_questions payload is the decision-tree answer set collected from the UI that renders Get Clinical Questions. It can be a flat {question_id: value} dict or the wrapped export shape {"answers": {...}, "resolved": [...]}. Chart-note attachments are required when the clinical answers imply them (Q1 weight-loss subprompt, Q4 chart notes submitted). If the backend rejects the request for a missing attachment it returns HTTP 400; the SDK raises WorkflowError.

Parameters

Name	Type	Required	Description
`bin`	string	yes	Pharmacy claim BIN (6 digits).
`pcn`	string	yes	Processor control number from the patient’s insurance card.
`state`	string	yes	Two-letter USPS state code where the prescription will be filled.
`member_id`	string	yes	Cardholder ID (302-C2).
`drug_slug`	string	yes	Canonical drug identifier from Search Drugs (e.g. `"wegovy_4mg_tablets"`).
`icd10_diagnosis`	string	yes	ICD-10 diagnosis code (e.g. `"E66.9"`).
`patient`	object	yes	Patient demographics. See PatientInfo.
`prescriber`	object	yes	Prescriber information. See PrescriberInfo.
`group`	string	no	NCPDP Group ID (301-C1). Optional.
`form_specific_questions`	object	no	Form-specific answers (e.g. `prescription_date`). Shape is form-dependent.
`clinical_questions`	object or array	no	Decision-tree answers from the PA UI.
`documents`	array	no	Files to merge into the filled PDF. Each entry may be a path string or a `(filename, bytes)` tuple.

PatientInfo

Field	Type	Description
`first_name`	string	Patient first name.
`last_name`	string	Patient last name.
`dob`	string	Date of birth as `MM/DD/YYYY` or `YYYY-MM-DD`.
`id`	string	Member / cardholder ID.
`address`	string	Street address (line 1).
`city`	string	City.
`state`	string	Two-letter USPS state code.
`zip`	string	5-digit ZIP.
`home_phone`	string	Home phone number.
`gender`	string	`"M"` or `"F"`.

PrescriberInfo

Field	Type	Description
`first_name`	string	Prescriber first name.
`last_name`	string	Prescriber last name.
`npi`	string	National Provider Identifier (10 digits).
`address`	string	Office address (line 1).
`city`	string	City.
`state`	string	Two-letter USPS state code.
`zip`	string	5-digit ZIP.
`office_phone`	string	Office phone number.

Example

Python

from simplex import (
    CaremarkGlobalPaFormQuestions,
    ClinicalAnswers,
    FillPaResponse,
    PatientInfo,
    PrescriberInfo,
    SimplexClient,
    SimplexError,
)

client = SimplexClient()

PATIENT: PatientInfo = {
    "first_name": "Jordan",
    "last_name": "WHITAKER",
    "dob": "1987-08-22",
    "id": "PSHP8839241076",
    "address": "4412 SE STEELE ST",
    "city": "PORTLAND",
    "state": "OR",
    "zip": "97206",
    "home_phone": "5035550142",
    "gender": "F",
}

PRESCRIBER: PrescriberInfo = {
    "first_name": "Evelyn",
    "last_name": "Harper",
    "npi": "1427389056",
    "address": "2130 NW Lovejoy St, Suite 400",
    "city": "Portland",
    "state": "OR",
    "zip": "97210",
    "office_phone": "5035550318",
}

FORM_SPECIFIC_QUESTIONS: CaremarkGlobalPaFormQuestions = {
    "prescription_date": "04/24/2026",
}

# Wrapped {answers, resolved} payload from the clinical-question UI.
# `answers` drives form-fill decisions; `resolved` is preserved for audit.
CLINICAL_ANSWERS: ClinicalAnswers = {
    "answers": {
        "indication_selector": "wm_adult_injection",
        "wm_adult_injection_phase": "initiation",
        "wm_adult_init_age_18_or_older": "18",
        "wm_adult_init_diet_and_activity": "yes",
        "wm_adult_init_6mo_wm_program": "yes",
        "wm_adult_init_bmi_branch": "bmi_ge_30",
        "wm_adult_init_bmi_value": "30",
    },
    "resolved": [
        {
            "question_id": "indication_selector",
            "prompt": "Which indication is this prior authorization for?",
            "answer_value": "wm_adult_injection",
            "answer_label": "Weight management (Adult) — Wegovy Injection",
        },
        {
            "question_id": "wm_adult_init_bmi_value",
            "prompt": "What is the patient's baseline BMI (kg/m²)?",
            "answer_value": "30",
            "answer_label": "30 kg/m²",
        },
    ],
}

# 1. Resolve drug_slug.
match = client.search_drugs("wegovy 2.4mg auto-injectors")["matches"][0]

# 2. Fill the PA.
try:
    response: FillPaResponse = client.fill_pa(
        bin="004336",
        pcn="ADV",
        state="OR",
        member_id="PSHP8839241076",
        drug_slug=match["slug"],
        icd10_diagnosis="E66.9",
        patient=PATIENT,
        prescriber=PRESCRIBER,
        form_specific_questions=FORM_SPECIFIC_QUESTIONS,
        clinical_questions=CLINICAL_ANSWERS,
        documents=["chart_notes.pdf"],
    )
    print(response["signed_url"])
except SimplexError as e:
    print(f"error: {e}")

Response

{
  "succeeded": true,
  "form_id": "a2d18bab-8e4e-4873-b558-b65958b48400",
  "signed_url": "https://s3.us-west-1.amazonaws.com/simplex-prior-auth-submissions/a2d18bab-.../preview.pdf?...",
  "expires_at": "2026-04-25T06:15:18.958231+00:00"
}

Field	Description
`succeeded`	`true` when the form was filled and uploaded.
`form_id`	UUID for the submission. Also appears in the signed URL.
`signed_url`	Short-lived HTTPS URL where the filled PDF can be downloaded. Valid for ~24 hours.
`expires_at`	ISO-8601 timestamp when `signed_url` expires.

​Parameters

​PatientInfo

​PrescriberInfo

​Example

​Response

Parameters

PatientInfo

PrescriberInfo

Example

Response