Match Suggestion (no-write)
Run the patient matcher against caller-supplied identifiers and return the verdict. Never persists. The verdict’s kind tells the caller how to render its picker: hard (lock — external-id / name+DOB uniqueness), medium (pre-fill with override — phone/email + name heuristic), soft (pre-fill, confirm — a single same-name patient with no date of birth to confirm), or none. 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); medium = pre-fill with override (contact-channel heuristic); soft = pre-fill with override (name-only suggestion, confirm before use); none = free.
hard, medium, soft, none Which matcher tier resolved the patient (external_id, demographics, phone_fuzzy_name, email_fuzzy_name, name_only). Null when kind is none.
external_id, demographics, phone_fuzzy_name, email_fuzzy_name The matched patient when kind is hard, medium, or soft; null otherwise.

