API Reference

## DRG Grouper API Reference

POST https://api.revenuecycle.works/api/drg/group
Content-Type: application/json
X-API-Key: your_key                  // omit to use the unauthenticated tier

Machine-readable spec: https://api.revenuecycle.works/v3/api-docs

### Grouper version selection
Match the version to the patient's discharge date fiscal year. Send bare digits —
"v440" is rejected with a 400.
  "440" — FY2027 (discharges on/after Oct 1 2026)      ← current
  "431" — FY2026 mid-year (Apr 1 2026 – Sep 30 2026)
  "430" — FY2026 (Oct 1 2025 – Mar 31 2026)
  "421" — FY2025 mid-year  |  "420" — FY2025
  "411" — FY2024 mid-year  |  "410" — FY2024
  "401" — FY2023 mid-year  |  "400" — FY2023
x.1 versions add new codes mid-year but share DRG definitions and weights with x.0.

### Request body (JSON)
{
  "grouperVersion": "440",             // required — bare digits, see table above
  "principalDiagnosis": {              // required
    "code": "I21.3",                   // ICD-10-CM; periods are stripped automatically
    "poa": "Y"                         // optional, defaults to "BLANK"
  },
  "sex": "MALE",                       // required — "MALE"|"FEMALE"|"UNKNOWN"
  "dischargeStatus": "HOME_SELFCARE_ROUTINE",  // required — exact constant, see below
  "ageInYears": 68,                    // always send — omitting it means age 0, which
                                       //   routes the claim through neonatal logic
  "admissionDiagnosis": "I21.3",       // optional — plain string, not an object
  "secondaryDiagnoses": [              // optional — same shape as principalDiagnosis
    {"code": "J9601", "poa": "Y"}
  ],
  "procedures": ["0271356"],           // optional — ICD-10-PCS strings
  "ageDaysAdmit": 0,                   // optional — neonatal (MDC 15) logic only
  "ageDaysDischarge": 0                // optional — neonatal (MDC 15) logic only
}

### POA (Present on Admission) indicators
"Y" = present on admission     "N" = not present on admission
"W" = clinically undetermined  "U" = documentation insufficient
"E" = exempt                   "ONE" = unreported/exempt
"BLANK" = not provided (default)  "INVALID" = unrecognised value
The field name is "poa" — "presentOnAdmission" is rejected with a 400.

### Common dischargeStatus values (UB-04 code → enum)
Must be the exact constant. Shorthand like "HOME" or "ROUTINE" is rejected with a 400.
01 → "HOME_SELFCARE_ROUTINE"       02 → "SHORT_TERM_HOSPITAL"
03 → "SNF"                         06 → "HOME_HEALTH_SERVICE"
07 → "LEFT_AGAINST_MEDICAL_ADVICE" 20 → "DIED"
50 → "HOSPICE_HOME"                62 → "REHAB_FACILITY_REHAB_UNIT"
63 → "LONG_TERM_CARE_HOSPITAL"     65 → "PSYCH_HOSP_UNIT"
Planned-readmission variants: append _W_PLANNED_READMISSION (e.g., 81 → "HOME_SELF_CARE_W_PLANNED_READMISSION").
Full list: 01-07, 20-21, 30, 43, 50-51, 61-66, 69-70, 81-95, plus "NONE".

### Response (200 OK)
{
  "finalDrg": "321",                  // MS-DRG to use for reimbursement
                                      //   "999" = ungroupable, "998" = error DRG
                                      //   (998 comes back with return code "OK")
  "finalBaseDrg": "321",              // DRG family before the severity split
  "finalMdc": "5",                    // Major Diagnostic Category 1-25; "0" = ungroupable
  "finalSeverity": "MCC",             // "MCC"|"CC"|"NON_CC"|"NONE"
  "finalDrgSdxSeverity": "MCC",       // highest severity from any secondary diagnosis
  "finalMedSurgType": "SURGICAL",     // "MEDICAL"|"SURGICAL"|"NONE"
  "finalGrouperReturnCode": "OK",     // CHECK THIS — see error handling below
  "hacStatus": "NOT_APPLICABLE",      // "NOT_APPLICABLE"|"FINAL_DRG_NO_CHANGE"
                                      //   |"FINAL_DRG_CHANGES"|"FINAL_DRG_UNGROUPABLE"
  "numHacCategoriesSatisfied": 0,
  "initialDrg": "321",                // initial* = the same six fields before HAC processing
  "diagnosisValidation": {},          // code → bool; false = not in this version, ignored
  "diagnosisSeverityFlags": {},       // code → "MCC"|"CC"|"NEITHER"|"MCC_EXCLUDED"
                                      //   |"CC_EXCLUDED"|"MCC_EXCLUDED_BY_DRG_LOGIC"
                                      //   |"CC_EXCLUDED_BY_DRG_LOGIC"
  "diagnosisAffectsDrg": {},          // code → bool
  "diagnosisAffectsDrgDetail": {},    // code → "INITIAL"|"FINAL"|"BOTH"|"NONE"
  "diagnosisPoaStatus": {},           // code → "POA_NOT_CHECKED"|"POA_NOT_RECOGNIZED"
                                      //   |"POA_RECOGNIZED_NOT_POA"|"POA_RECOGNIZED_YES_POA"
                                      //   |"HOSPITAL_EXEMPT"|"BLANK_DX_NOT_CONSIDERED"
  "procedureValidation": {},          // code → bool
  "procedureAffectsDrg": {},          // code → bool
  "procedureAffectsDrgDetail": {},    // code → "INITIAL"|"FINAL"|"BOTH"|"NONE"
  "procedureIsOperatingRoom": {},     // code → bool; OR procedures drive SURGICAL DRGs
  "diagnosisHacCategories": {}        // code → ["HAC-12: Surgical Site Infection (FINAL_DRG_CHANGES)"]
}

### Error handling — read this before trusting a result
A grouper rejection returns HTTP 200, not an error status. An unrecognised principal
diagnosis comes back as 200 with finalDrg "999", finalMdc "0", finalSeverity "NONE"
and finalGrouperReturnCode "INVALID_PDX".

Checking finalGrouperReturnCode == "OK" is necessary but NOT sufficient. Reject the
error DRGs by number as well:
  "999" — claim could not be grouped; arrives with a non-OK return code
  "998" — error DRG that arrives with finalGrouperReturnCode "OK" and a real finalMdc.
          A male patient with an obstetric principal diagnosis returns finalDrg "998",
          finalMdc "14" and "OK", so a return-code check alone lets it through.
Treat a result as usable only when finalGrouperReturnCode == "OK" AND finalDrg is
neither "998" nor "999".

finalGrouperReturnCode values:
  "OK" — clean assignment
  "INVALID_PDX" — principal diagnosis not recognised
  "DX_CANNOT_BE_PDX" — code cannot be principal (e.g. a manifestation code)
  "INVALID_SEX" — sex conflicts with a diagnosis or procedure
  "INVALID_DISCHARGE_STATUS" — discharge status not recognised by the grouper
  "HAC_MISSING_ONE_POA", "HAC_STATUS_INVALID_POA_N_OR_U",
  "HAC_STATUS_INVALID_POA_INVALID_OR_1",
  "HAC_STATUS_INVALID_MULT_HACS_POA_NOT_Y_W" — POA problems on a HAC diagnosis

HTTP errors return {"status", "error", "message", "details", "timestamp"}:
  400 — malformed request or invalid enum value; "details" names the offending field
  401 — X-API-Key did not match an active account
  403 — key is valid but the account is deactivated
  404 — no DRG output could be generated
  429 — rate limit or monthly allowance exhausted; wait Retry-After seconds
  500 — server error

### Quick-start workflow
1. Pick grouperVersion from the discharge date fiscal year
2. POST the payload (periods in ICD-10 codes are fine — they are stripped)
3. Check finalGrouperReturnCode == "OK" before using the result
4. Read finalDrg + finalMdc for the assignment
5. Use diagnosisAffectsDrgDetail / procedureAffectsDrgDetail to see which codes drove it
6. Use diagnosisSeverityFlags to explain why a CC or MCC did not raise severity