---
name: nhcx-preauth
description: Add NHCX pre-authorisation to a hospital information system or a standalone claims desk. Link the admission, capture the dossier, ask the auth-requirements ruling, send the pre-auth (12), answer a PMJAY query (19, 131), raise an enhancement (13), cancel (PC01) and ask for a predetermination, reading every answer (20, 21, 22, 23, 24, PC02), held to the pinned bundles. Starts by checking whether the app already sends pre-auths or any of these legs, and whether the coverage and plan it depends on exist, then builds, extends or reuses only what is missing. Self-contained; needs no other skill installed. Use for pre-authorisation, enhancement, pre-auth query answers, cancelling a pre-auth, auth requirements, predetermination, NHCX use cases B3, B8 cancel, B9, D2 and D4 to D8, flow steps F5 to F9e.
---

# NHCX pre-authorisation: from the admission to the payer's decision

This skill carries the episode from an eligible, quoted case to an approved pre-authorisation. It links the admission, captures the dossier, asks the payer to rule on the quoted set, sends the pre-auth, reads the acknowledgement and the decision, answers a PMJAY query in-band, raises an enhancement, withdraws a pre-auth, and asks for a quote. It is the heaviest skill and the one PMJAY refuses most.

Read `core/LADDER.md` first. It holds the ladder every NHCX skill walks: the definition of compliant, the stages, the workspace, how to run a stage, and the rules. This folder carries everything it needs and runs on its own; the other six NHCX skills are separate folders, and none of them has to be installed. Paths starting `core/`, `stages/`, `references/`, `fhir/`, `flow/`, `ui/`, `templates/` or `scripts/` are relative to this folder. Paths starting `nhcx-package/` are in the NHCX package, which `scripts/fetch-package.sh` fetches into the target project beside `nhcx-build/`; `references/material.md` names the package file of every pin by its label.

## What this skill covers

| | |
| --- | --- |
| Flow steps | F5 Link or capture the admission, F6 The dossier, F8 Validate the set, F9 Send the pre-authorisation, F9a The payer answers, F9b Answer a query (a `resubmit` payer only), F9c Enhancement, F9d Cancel, F9e Predetermination |
| Tabs | Validate (tab 4); Pre-authorisation (tab 5, opens once `eligible`) |
| Wire | Auth requirements: `v1/coverageeligibility/check`, purpose `auth-requirements` with items, workflow id = the case number, asked and never awaited. `v1/preauth/submit` with workflow 12 (pre-auth), 19 (query answer, PMJAY), 13 (enhancement), 131 (enhancement query answer), and 12 with `use predetermination`. `v1/task/submit` with workflow PC01 (cancel). Answers: 20, then 21, 22, 23, 24, 231 or 241; PC02 |
| Next actions | "Send the pre-authorisation", "Send a fresh pre-authorisation", "Answer the query" (a `resubmit` payer), "Send the enhancement (n added)", "With the payer; ask where it stands" (the label; the enquiry behind it is the reprocess use case's) |
| Use cases | B3 and its enhancement row, B8 cancel, B9, D2, D4, D5, D6, D7, D8 |
| Modules | 7.6, whole; 7.7, the pre-auth legs (12, 13, 19, 131, predetermination); 7.8, the pre-auth, enhancement and predetermination answers; 7.9, cancel and PC02 |
| Pins | `coverage/authrequirements`, `preauth/request`, `preauth/enhancement`, `preauth/queryupdate`, `preauth/cancel`: `nhcx-package/fhir/B1/auth-requirements.json`, `nhcx-package/fhir/B3/preauth-{request,enhancement,queryupdate,cancel}.json` |
| Payer fixtures | `nhcx-package/fhir/C5/*` (20, 21, 22, 23, 24, generic and PMJAY), `nhcx-package/fhir/C10/C10-cancelled-*` (PC02), `nhcx-package/fhir/C11/*` (predetermination); the auth-requirements rulings `nhcx-package/fhir/C3/C3-response-generic.json` and `C3-response-pmjay.json`; the live PMJAY shapes in `nhcx-package/fhir/D4`, `D6`, `D7`, `D8` |
| Tables | `claim_auth`, `claim_auth_item`, `claim_auth_requirement`, `claim_preauth`, `claim_predetermination`, `claim_form_answer`, `claim_document`, `claim_diagnosis`, `claim_care_team`, `claim_item`; `claim.patient_id`, `claim.encounter_id` |
| FHIR | `fhir/FHIR.md` sections 2 (auth requirements), 4, 5 and 6 (cancel); `references/fhir-knowledge.md` sections 3, 5, 6, 7 and 8 |

Not here: the query of a `communication` payer (a generic payer), which arrives as a CommunicationRequest and belongs to the communication use case (`nhcx-communication`); status enquiries, which belong to the reprocess use case (`nhcx-reprocess`, F13).

## Needs and hands on

Needs: an eligible episode and the coverage builder (the coverage use case); a plan ready, lines quoted, forms and requirements known (the insurance use case). Stage 0 checks for them below, whichever way the app got them.

Hands on: a pre-auth `approved` or `partial` with `preauth_ref` (the payer's number), `claim_ref` (the number the claim goes under), the approved amount and the item verdicts; the dossier (admission, diagnoses, a care team with HPINs, documents under their codes, answered forms) that the claim builds on; the pre-auth bundle as sent (`request_json`), which a communication reply lifts entries from. After a PC02, a fresh claim number on the episode.

## Capability check

Stage 0 (`stages/0-capability-check.md`) gives every capability below a verdict: search for the markers, run the check, record what was observed.

### Own

| Id | What | Look for | Present when (observed) |
| --- | --- | --- | --- |
| `preauth.admission-link` | F5: link the eligible case to a current inpatient stay (integrate), or capture it (standalone) | `encounter_id` on the episode; a match on the ABHA the payer returned | Linking an `eligible` case to a current IPD stay whose ABHA matches, digits only, stores `patient_id` and `encounter_id`; linking before `eligible`, or to a stay that is not a current IPD admission, is refused |
| `preauth.dossier` | F6: admission and provisional discharge dates, ICD-10 diagnoses, the treating doctor with an HPIN, package or non-package, documents under the plan's codes (else `ODN`), forms answered | `save_preauth`, a diagnosis table, a care team table, documents with `code` and `stage`, form answers | Saving refuses a missing admission date, a discharge before the admission, no diagnosis, a doctor without an HPIN, and a package case with no line; an upload other than pdf, jpg, jpeg or png is refused; a file attached against a requirement carries its code |
| `preauth.auth-requirements` | F8: the ruling on the quoted set, fingerprinted, asked and never awaited | `auth-requirements`, `authorizationSupporting`, a fingerprint of the quoted set | 7.6's Validate section whole: the builder fed the pin's data produces `coverage/authrequirements` with an integer quantity; an unchanged set sends once and a changed quantity sends again; the reader, fed `nhcx-package/fhir/C3/C3-response-generic.json` and `C3-response-pmjay.json`, yields items and requirements with `stage` and `at_preauth`; a submit proceeds with the ruling still `checking` |
| `preauth.claim-bundle` | 7.7's builder, for the pre-auth legs: one pure function | `preauthorization`, `supportingInfo`, `Item/`, `SupportingInformation/`, `https://hpr.abdm.gov.in`, `programCode`, `ADDD` | The `preauth/request`, `preauth/enhancement` and `preauth/queryupdate` pins pass (single-item pins compared without `factor`); every reference resolves; every item, procedure and supportingInfo entry has an id, and the sequences run from 1 without a gap; every Practitioner has an HPIN; tiers appear only as modifiers; no literal `MAND\d+`, `MG\d+` or `/questionnaire/` in the code |
| `preauth.send` | F9, F9c: `submit_preauth` and the choice of send kind | `v1/preauth/submit`, workflow ids `12`, `13`, `19`, `131`, `121` | With the 7.1 stub: a fresh case gives 12; after a rejection 12, never 121; lines added after approval give 13 with every line old and new; every F9 guard refuses before any HTTP call; the three ids, `submission_kind` and `workflow_id` are stored, and `thread_correlation_id` is untouched until the payer answers |
| `preauth.response-reader` | F9a: 7.8 on the pre-auth thread | `ClaimResponse`, `preAuthRef`, `verdict_status`, `outcome` | `verdict_status` gives `submitting` on the 20, `approved` on the 21, `rejected` on the 23 and `queried` on the 24; a 20 then a 21 leaves `approved` with `preauth_ref` never empty; an enhancement 20 without `preAuthRef` keeps the parent's; `total[]` is read by category; a PMJAY query fills `query_note` verbatim |
| `preauth.query-answer` | F9b for a `resubmit` payer: 19, or 131 after an enhancement query | `queryupdate`, `CQD`, `NMI` | The `preauth/queryupdate` pin passes; the reply rides on `NMI/CQD` on a new correlation id; an empty reply is refused before sending; a `communication` payer's query is sent to the inbox instead |
| `preauth.cancel` | F9d: Task `cancel`, workflow PC01; PC02 read | `PC01`, `PC02`, `"cancel"`, `intimationNumber`, `claimNumber` | The `preauth/cancel` pin passes as it is; a PC02 sets the pre-auth `cancelled` and gives the episode a fresh claim number while the old one stays on the leg; a ProtocolResponse on the cancel thread leaves the pre-auth as it was; a cancel of a `rejected` pre-auth, a second cancel, and a cancel after a claim was raised are refused (7.9 Validate, rows 1 for the cancel pin, 2, 4 and 5) |
| `preauth.predetermination` | F9e: the F9 bundle with `use predetermination`, on its own row | `predetermination` | A quote creates its own row (`asking`, then `answered`) with the eligible amount, and the pre-auth row is untouched |
| `preauth.screens` | The Validate and Pre-authorisation tabs | the link card, the dossier form, the submit card, the decision card | The decision card renders the decision, `preAuthRef`, approved amount, eligible amount and item verdicts verbatim from the stored answer; a pre-auth sent and not answered reads as waiting, never approved or rejected; the reply box shows only for a `resubmit` payer |

### Foundation

All six capabilities in `core/FOUNDATION.md`. `foundation.storage` is partial until this skill's tables exist; `foundation.state` is partial until `case_stage` has the `preauth` and `enhancement` branches and `next_actions` the labels above.

### Prerequisites

The coverage use case (`nhcx-coverage`) and the insurance use case (`nhcx-insurance`) own these. The checks are here, so neither skill need be installed.

| Capability | Why | Look for | Present when (observed) |
| --- | --- | --- | --- |
| `coverage.episode`, `coverage.check-leg`, `coverage.response-reader` | F5 and F9 hold `eligible` | an episode table with `claim_no`, `member_id`, `policy_code`, `payer_code`; a send on `v1/coverageeligibility/check`; `inforce` read | An episode opened from a policy row, checked with a stubbed client (workflow id = the claim number), and fed the answers in `nhcx-package/fhir/C3`, settles `eligible` |
| `coverage.request-builder` | The auth-requirements check is the coverage builder with items. Extend it; do not write a second | `CoverageEligibilityRequest`, `"purpose"` | Fed each pin's own data, it produces `coverage/{discovery,validation,benefits}` byte for byte; if it cannot take `items`, it is partial for this skill and 7.6 extends it |
| `insurance.plan-leg`, `insurance.plan-parser`, `insurance.lines` | Items, prices, tiers, documents and forms come from the plan; F9 needs at least one line | a plan table with benefits and forms; a line table with `parent_code` | `nhcx-package/fhir/C4/C4-response-pmjay.json` applied to an episode leaves a plan `ready` with rated benefits, requirements and forms; a line added from it takes the plan's rate, and a tier carries `parent_code` |

### Host facts

The encounter (admission time, ward, bed, admitting doctor, status); diagnoses (ICD-10 with a display, or a mapping to it); the practitioner table with HPR id, licence and qualification; the document store, a code and stage tag on a file, the accepted content types.

## The ladder, for this skill

| Stage | What is specific here |
| --- | --- |
| 0 | The tables above. |
| 1 | Confirm the shared page, or write it if this skill runs first on the app. Own rows: B3, B8 cancel, B9, D2, D4 to D8. Predetermination is commonly `later`. |
| 2 | Risks: one live pre-auth per beneficiary per hospital (PAYR-1238); one request at a time per case (PAYR-1322); a fresh 12 after a rejection (121 is PAYR-1214); a PMJAY query answer on a new correlation id; a missing HPIN (PAYR-1083); an enhancement adding a second conservative package (PAYR-1245). |
| 3 | The host facts above. |
| 4 | Source maps for the auth-requirements bundle, the Claim bundle's pre-auth legs and the cancel Task; the ClaimResponse and PC02 destinations; the HPIN's source; `preAuthRef` from the ClaimResponse. If this skill maps first, every table's home too. |
| 5 | The Validate and Pre-authorisation tabs; actions F5, F6, F8, F9, F9b (resubmit payer), F9c, F9d, F9e. |
| 6 | 7.6; the parts of 7.7, 7.8 and 7.9 above; the foundation modules stage 0 found absent or partial. |
| 7 | In that order. The builder stays one function with `leg` and `flow` arguments: the claim legs extend it later. |
| 8 | 7.6 whole; the rows of 7.7, 7.8 and 7.9 that name the pre-auth legs. |
| 9 | Five pin comparisons; reader tests on 20, 21, 22, 23, 24, PC02 and the ruling; matrix rows B3, B3 enhancement, B8 cancel, B9, D2, D4 to D8; send-kind selection after every prior state; the cross-cutting rows on the pre-auth thread (a door refusal of an enhancement leaves the pre-auth approved). |
| 10 | Rung 1. Rung 3 walks B3 and B8 cancel against a generic payer. Rung 4 walks D4, D6, D7 and D8; sweep live pre-auths first. |
| 11 | This skill's section. |

## Rules for these legs

- Never hard-code a document code, a package code, a questionnaire url or a summary code. Take them from the ruling, else the plan.
- Element ids on every indexed list (`Item/n`, `Procedure/n`, `SupportingInformation/n`) and a `sequence` on every supportingInfo entry, numbered once after the list is assembled (PAYR-1019, PAYR-1027).
- The consent form rides every pre-auth (PAYR-1256), and each guideline form rides its package (PAYR-1254).
- One item per procedure or implant; tiers ride as modifiers; `factor` 1, 0.5, 0.25 by cost rank on PMJAY; `total` is the sum of the nets.
- `LM100` never rides a pre-auth (PAYR-1270).
- The auth-requirements check is asked, never awaited, and never asked twice for one set.
- Never close a thread on the first reply: the 20 (`queued`) comes first and the decision after, on one correlation id. Never read `outcome` alone.
- Keep `preauth_ref`; never overwrite it with an empty value.
- A cancel retires the claim number. The cancel action is hidden once a claim has been raised.
- Read the payer's refusal before touching the code: half of them are scheme rules (`references/flow-knowledge.md` section 5).

## Done when

- Every gate in this skill's block of `nhcx-build/STATE.md` is closed with evidence.
- The five pins pass their comparisons.
- The compliance points in `core/LADDER.md` hold for F5 to F9e.