Tuning Review Alerts
4 min read
Last updated
GuidesDevelopersChangelog
The autocoder attaches review alerts to a claim when something needs human attention. Every alert carries a type, a severity from 1 to 10, and a suggested reviewer role. Your facility configuration decides which alerts stay active, at what severity, and which are suppressed.
Customers do not edit the configuration directly. Your facility configuration controls every option on this page. Contact your Hank representative to change it.
Your facility configuration can suppress specific alerts with the claimValidation.suppressedHreIds list. Each alert in the alert reference carries an id, for example provider_times_inferred_from_case_events. Your representative adds that exact id to the list.
Suppression does not delete the alert. The autocoder downgrades the alert to INFORMATIONAL. The alert still appears in the audit trail, so a reviewer can still read what the autocoder found. The alert no longer carries a HARDSTOP, COMPLIANCE, or FINANCIAL type, so your workflow no longer treats it as a gate.
The list also accepts glob patterns, for example field_validation_missing_*. Prefer exact ids. A broad pattern such as provider_* can suppress a critical alert you meant to keep.
Some alerts come from named rules in your facility configuration. Each rule has an enabled flag. The ob_case_review rule is one example: it raises an alert on every obstetric anesthesia case. Your representative can disable the rule instead of suppressing the alert id.
A disabled rule is silent. No alert record is created. Your configuration file is the audit trail, because it records which rules are active and which are off.
A named rule can carry a configurable severity. Your facility configuration sets that severity on the rule.
The code confidence alerts work differently. Their severities are fixed in the code. The autocoder emits severity 7 for a low confidence CPT code or modifier, and severity 5 for a low confidence diagnosis code. You cannot change these values. Under claimValidation.codeConfidence.severity, the one live key is missingRequiredNote.
Severity does not change what the autocoder found. Severity changes how your workflow ranks the alert. In HANK Claim Maker, a higher severity usually moves an alert from a flag to a review queue.
The autocoder scores its confidence in each code. When a score falls under the configured threshold, the autocoder raises a low confidence alert: surg_cpt_low_confidence, anes_cpt_low_confidence, or icd_low_confidence.
Your facility configuration sets the thresholds under claimValidation.codeConfidence.thresholds. Six threshold keys are live:
surgicalCodes.primaryanesthesiaCodes.primaryicdCodes.primarysurgicalCodes.modifiersanesthesiaCodes.modifierscomponentModifiers, for radiology component modifiers, default 70A higher threshold produces more review alerts. A lower threshold produces fewer.
The keys procedureCodes.*, timeCodes.startTime, and timeCodes.endTime are dead. Nothing reads them. A change there has no effect.
One threshold is shared. The E/M alert eandm_low_confidence_bin reads surgicalCodes.primary, the same key as surgical codes. A change to that key moves both checks. You cannot move one without the other. The severity of that alert is fixed at 6.
Two claim level rules ship enabled and raise a severity 10 HARDSTOP alert:
anes_no_cpt_code fires when the claim carries no primary anesthesia service. Review the case for a cancellation or for procedure only billing.anes_dos_age_warning fires when the date of service is more than one year old. Verify the date before charge entry.Both rules are facility tunable. Your representative can lower a severity or disable a rule if your workflow already covers the same check.
The autocoder scores handwritten notes by legibility. Legible handwriting can score high, and the low confidence alerts do not fire on those codes. Illegible handwriting scores low, so the low confidence alerts fire on those codes.
Some facilities want every handwritten only code reviewed, whatever the legibility. Your facility configuration can enable claimValidation.handwrittenForceConfidence33. The setting is off by default. When it is on, the autocoder sets confidence to 33 on any code whose source notes are all handwritten, so the code always reaches the low confidence alerts.
Do not combine that setting with suppression of the same low confidence alerts. The codes are forced to 33, and the alerts are downgraded to INFORMATIONAL, so your workflow no longer sees them as gates.
Separate handwritten source alerts record where a value came from, for example handwritten_asa_source, handwritten_type_source, handwritten_emergent_source, and handwritten_time_source. Keep these active if your team needs to see which values came off paper. Your facility configuration also sets the handwritten detection sensitivity, which decides how much handwriting marks a document as handwritten.
Discuss any suppression with your compliance lead before you request it. With an alert off, affected cases follow your standard review routing only. No reviewer gets a targeted request to check the item the alert covers.
Review your suppression list at onboarding and again whenever your review staffing changes. Ask your Hank representative for the current list for each facility.
What happens next depends on how your organization consumes HANK CODES. In HANK Claim Maker, a HARDSTOP alert places the claim in the review queue your administrators configured for it. Organizations that consume the coding API directly decide in their own workflow which alerts pause a claim, who reviews them, and when a claim is released.