Match Suggestion (no-write)
Run the canonical four-tier patient matcher against caller-supplied identifiers and return the verdict. Never persists. Used by the file detail page to lock or pre-fill its patient picker, and by future eligibility / prior-auth extraction surfaces. Identifiers are normalized with the same forgiving parsers the upsert endpoint uses, so callers can pass raw values from extracted document data.
Authorizations
Body
Identifiers the matcher will resolve to a patient.
Forgiving on the wire — same parse_*_safe normalizers the upsert
endpoint runs, so a partly-formatted phone or a free-text DOB still
matches. Pass raw values from extracted document data, form fields,
or eligibility payloads — the service normalizes before calling the
matcher. Empty/missing fields are skipped (matcher tiers gate on
presence, so unsupplied identifiers just narrow the tier set).
External-id pair. Tier 1 of the matcher when supplied.
DOB in any of: YYYY-MM-DD, YYYYMMDD, MM/DD/YYYY, MM-DD-YYYY, MM/DD/YY. Unparseable values are ignored.
Response
Successful Response
Matcher verdict + optional slim patient. Never includes side-effect data.
How the caller should render the picker: hard = lock to the matched patient (DB-enforced uniqueness leaves exactly one valid choice); soft = pre-fill with override; none = free.
hard, soft, none Which matcher tier resolved the patient (external_id, demographics, phone_fuzzy_name, email_fuzzy_name). Null when kind is none.
external_id, demographics, phone_fuzzy_name, email_fuzzy_name The matched patient when kind is hard or soft; null otherwise.

