Fix validation issues
Outcome
Charges sitting at NEEDS_FIX are diagnosed, fixed (upstream where
possible, in-app where necessary), re-validated, and they advance to
VALIDATED ready for billing.
Prerequisites
| Scope | What it lets you do |
|---|---|
billing.charge.read | View the worklist |
billing.charge.write | Edit a charge inline |
billing.charge.revalidate | Re-run the validator without editing |
The validator's job
The platform's validation pipeline runs after mapping. Its rule set is configured per tenant; common rules:
| Rule kind | Example |
|---|---|
member_match | The MRN on the inbound resolves to exactly one member. |
coverage_required | The member has active coverage on the DOS. |
auth_required | A program-flagged service has an active authorization. |
service_taxonomy | The procedure code is mapped to a recognized service. |
unit_range | Units fall within the procedure's MUE band. |
place_of_service | POS is allowed for this procedure. |
provider_credential | The rendering provider has the credential the program demands. |
A failing rule writes an issue on the charge with three fields:
| Field | What it tells you |
|---|---|
code | The rule that failed (e.g. auth_required). |
message | One-line explanation. |
field | The data field at fault, when known. |
The fix flow
Common patterns and the fix
| Issue | Pattern | Fix |
|---|---|---|
member_match | The inbound MRN doesn't match a member | Search for the member (Member detail); attach via Resolve member. |
coverage_required | Member exists, but coverage is null on DOS | Refresh eligibility — see 2.4. If still null, member is uncovered; tag for clinical review. |
auth_required | No auth covers this DOS / units | Attach an existing auth or request a new one — see 2.5. |
unit_range | Units exceed MUE | Confirm the units the EMR sent. Often a unit-of-measure mismatch (per-15-min vs per-hour). Edit if confident. |
service_taxonomy | Procedure code unknown | Likely a stale code-set version; route to admin to refresh /admin/code-sets. |
provider_credential | Rendering provider missing credential | Provider record needs the credential added (Tenant Manual → Members & Providers). |
Steps
Filter to
NEEDS_FIX. Open/charges?status=NEEDS_FIX. Sort by oldest first.Open a row. The inline drawer's Issues section lists every failing rule with the field at fault.
Decide where the truth lives:
Re-validate. Click
Re-validate. If issues clear the charge flips toVALIDATED; if they don't the new issue list points to what's still wrong.
Bulk re-validate
Selecting many NEEDS_FIX rows and clicking Bulk re-validate re-runs
the validator without editing — useful after:
- A code-set refresh.
- An admin updates a validation rule (e.g. raises an MUE).
- Eligibility cache refreshes for a payer.
The platform processes them with the same rule set; you don't have to walk one-by-one.
Validation
| Check | Expected |
|---|---|
| Editing a field clears the related issue | Yes after re-validate. |
| Re-validate is idempotent | Yes — multiple runs don't compound state. |
| Bulk re-validate emits one audit row per charge | Yes; visible on each charge's history. |
| Tags persist across re-validation | Yes. |
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Re-validate doesn't clear an issue | Underlying data still fails the rule | Re-read the issue; the field hint usually points at the right place. |
| Edit field is read-only | Either you lack billing.charge.write or the charge is BILLED | Reverse the claim first. |
| New issue appears after edit | A rule we didn't fail before now fails (e.g. you changed the procedure code and tripped service_taxonomy) | Re-read; the new issue is real. |
Charge keeps flipping back to NEEDS_FIX | Upstream re-ingestion overwrites your fix | Coordinate with EMR team; either change at source or hold the charge while you bill. |
Where to next
- 2.4 — Confirm eligibility for the coverage-stale case.
- 2.5 — Attach or request auth for the auth-missing case.
- 2.6 — Edit or correct a charge for the honest in-app fix.