{"openapi":"3.0.1","info":{"title":"DRG Grouper API","description":"## MS-DRG Grouper REST API\n\nCalculate Medicare Severity Diagnosis Related Group (MS-DRG) codes from diagnosis and procedure codes.\n\n### Features\n- **DRG Grouping**: Calculate DRG codes based on ICD-10 codes\n- **Multiple Versions**: Supports grouper versions 400 (v40.0) through 440 (v44.0)\n- **Severity Levels**: Automatic CC/MCC detection\n- **HAC Detection**: Hospital Acquired Conditions identification\n- **POA Support**: Present on Admission indicators\n\n### Authentication\nInclude your API key in the `X-API-Key` header. Requests are subject to\nper-IP rate limiting and may return `429` until a valid key is supplied;\nauthenticated requests are not rate limited and count against your plan's\nmonthly call allowance. Contact support@revenuecycle.works to obtain a key.\n\n### Plans and pricing\nSee https://revenuecycle.works for current plans, or contact\nsupport@revenuecycle.works for volume pricing.\n\n### Support\nFor questions or support, contact: support@revenuecycle.works\n","contact":{"name":"Revenue Cycle API Support","url":"https://revenuecycle.works","email":"support@revenuecycle.works"},"license":{"name":"Proprietary","url":"https://revenuecycle.works/terms"},"version":"v440"},"servers":[{"url":"https://api.revenuecycle.works","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"DRG Grouping","description":"MS-DRG grouper calculations for Medicare reimbursement"}],"paths":{"/api/drg/group":{"post":{"tags":["DRG Grouping"],"summary":"Calculate MS-DRG grouping","description":"Calculates Medicare Severity Diagnosis Related Group (MS-DRG) codes based on diagnosis and procedure codes.\n\nThis endpoint accepts ICD-10 diagnosis codes, ICD-10 procedure codes, and patient demographics to determine\nthe appropriate DRG assignment, which is used for Medicare reimbursement calculations.\n\n**Supported Grouper Versions:** `400`, `401`, `410`, `411`, `420`, `421`, `430`, `431`, `440`\n(bare digits - a `v` prefix such as `v440` is rejected with a 400)\n\n**Key Features:**\n- Validates diagnosis and procedure codes\n- Calculates severity levels (CC/MCC)\n- Identifies Hospital Acquired Conditions (HACs)\n- Returns detailed validation results\n- Supports Present on Admission (POA) indicators\n","operationId":"groupDrg","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrgRequest"}}},"required":true},"responses":{"200":{"description":"Successfully calculated DRG grouping","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrgResponse"}}}},"403":{"description":"The API key is valid but the account has been deactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"The supplied X-API-Key did not match an active account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error during DRG calculation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Invalid request data (invalid codes, missing required fields, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded, or the account's monthly call allowance is exhausted. The Retry-After header gives the number of seconds to wait; RateLimit-Reset carries the same value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No DRG output could be generated for the given inputs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"Diagnosis":{"required":["code"],"type":"object","properties":{"code":{"type":"string","description":"ICD-10-CM diagnosis code. Periods are stripped automatically, so 'I50.9' and 'I509' are equivalent.","example":"I50.9"},"poa":{"type":"string","description":"Present-on-admission indicator. Defaults to BLANK when omitted. Note the field name is 'poa' - 'presentOnAdmission' is rejected with a 400 rather than silently ignored.","example":"Y","default":"BLANK","enum":["Y","N","U","W","ONE","E","BLANK","INVALID"]}},"description":"A diagnosis code and its present-on-admission indicator."},"DrgRequest":{"required":["dischargeStatus","grouperVersion","principalDiagnosis","sex"],"type":"object","properties":{"grouperVersion":{"type":"string","description":"MS-DRG grouper version as bare digits. Note: NOT prefixed with 'v' - '440' is valid, 'v440' is rejected with a 400.","example":"440","enum":["400","401","410","411","420","421","430","431","440"]},"admissionDiagnosis":{"type":"string","description":"Admission diagnosis ICD-10-CM code. Periods are stripped automatically, so 'I50.9' and 'I509' are equivalent.","example":"I50.9"},"principalDiagnosis":{"$ref":"#/components/schemas/Diagnosis"},"secondaryDiagnoses":{"type":"array","description":"Secondary diagnoses. Up to the grouper's per-claim limit.","items":{"$ref":"#/components/schemas/Diagnosis"}},"procedures":{"type":"array","description":"ICD-10-PCS procedure codes.","items":{"type":"string","description":"ICD-10-PCS procedure code. Periods are stripped automatically.","example":"5A1955Z"}},"ageInYears":{"type":"integer","description":"Patient age in years at discharge. Technically optional, but omitting it yields 0, which routes the claim through neonatal logic and will change the assigned DRG. Always send it for adult claims.","format":"int32","example":65},"ageDaysAdmit":{"type":"integer","description":"Age in days at admission. Used by neonatal (MDC 15) logic.","format":"int32","example":0},"ageDaysDischarge":{"type":"integer","description":"Age in days at discharge. Used by neonatal (MDC 15) logic.","format":"int32","example":0},"sex":{"type":"string","description":"Patient sex.","example":"MALE","enum":["MALE","FEMALE","UNKNOWN"]},"dischargeStatus":{"type":"string","description":"Discharge status / disposition. Must be one of the grouper's exact constants - common shorthand like 'ROUTINE' or 'HOME' is rejected with a 400. A routine discharge to home is HOME_SELFCARE_ROUTINE.","example":"HOME_SELFCARE_ROUTINE","enum":["NONE","HOME_SELFCARE_ROUTINE","SHORT_TERM_HOSPITAL","SNF","CUST_SUPP_CARE","CANC_CHILD_HOSP","HOME_HEALTH_SERVICE","LEFT_AGAINST_MEDICAL_ADVICE","DIED","COURT_LAW_ENFRC","STILL_A_PATIENT","FEDERAL_HOSPITAL","HOSPICE_HOME","HOSPICE_MEDICAL_FACILITY","SWING_BED","REHAB_FACILITY_REHAB_UNIT","LONG_TERM_CARE_HOSPITAL","NURSING_FACILITY_MEDICAID_CERTIFIED","PSYCH_HOSP_UNIT","CRIT_ACC_HOSP","DESIGNATED_DISASTER_ALTERNATIVE_CARE_SITE","OTH_INSTITUTION","HOME_SELF_CARE_W_PLANNED_READMISSION","SHORT_TERM_HOSPITAL_W_PLANNED_READMISSION","SNF_W_PLANNED_READMISSION","CUST_SUPP_CARE_W_PLANNED_READMISSION","CANC_CHILD_HOSP_W_PLANNED_READMISSION","HOME_HEALTH_SERVICE_W_PLANNED_READMISSION","COURT_LAW_ENFRC_W_PLANNED_READMISSION","FEDERAL_HOSPITAL_W_PLANNED_READMISSION","SWING_BED_W_PLANNED_READMISSION","REHAB_FACILITY_UNIT_W_PLANNED_READMISSION","LTCH_W_PLANNED_READMISSION","NURSG_FAC_MEDICAID_CERT_W_PLANNED_READMISSION","PSYCH_HOSP_UNIT_W_PLANNED_READMISSION","CRIT_ACC_HOSP_W_PLANNED_READMISSION","OTH_INSTITUTION_W_PLANNED_READMISSION"]}},"description":"DRG grouping request containing diagnosis codes, procedure codes, and patient information"},"DrgResponse":{"type":"object","properties":{"finalDrg":{"type":"string","description":"Assigned MS-DRG after HAC processing. This is the DRG to use for reimbursement.","example":"293"},"finalBaseDrg":{"type":"string","description":"Base DRG after HAC processing - the DRG family before the severity split. DRGs 291/292/293 share base DRG 291.","example":"291"},"finalMdc":{"type":"string","description":"Major Diagnostic Category after HAC processing. Broad body system or condition grouping, 1-25.","example":"5"},"finalSeverity":{"type":"string","description":"Severity level of the assigned DRG after HAC processing.","example":"NON_CC","enum":["MCC","CC","NON_CC","NONE"]},"finalDrgSdxSeverity":{"type":"string","description":"Highest severity contributed by any secondary diagnosis after HAC processing. May exceed finalSeverity when DRG logic excludes the contributing code.","example":"NON_CC","enum":["MCC","CC","NON_CC","NONE"]},"finalMedSurgType":{"type":"string","description":"Whether the final DRG is medical or surgical. SURGICAL means an OR procedure drove the assignment.","example":"MEDICAL","enum":["MEDICAL","SURGICAL","NONE"]},"initialDrg":{"type":"string","description":"Assigned MS-DRG before HAC processing. Equals finalDrg unless hacStatus is FINAL_DRG_CHANGES.","example":"293"},"initialBaseDrg":{"type":"string","description":"Base DRG before HAC processing.","example":"291"},"initialMdc":{"type":"string","description":"Major Diagnostic Category before HAC processing.","example":"5"},"initialSeverity":{"type":"string","description":"Severity level before HAC processing.","example":"NON_CC","enum":["MCC","CC","NON_CC","NONE"]},"initialDrgSdxSeverity":{"type":"string","description":"Highest secondary-diagnosis severity before HAC processing.","example":"NON_CC","enum":["MCC","CC","NON_CC","NONE"]},"initialMedSurgType":{"type":"string","description":"Medical or surgical classification before HAC processing.","example":"MEDICAL","enum":["MEDICAL","SURGICAL","NONE"]},"finalGrouperReturnCode":{"type":"string","description":"Grouper status for the final pass. OK means a clean assignment; any other value indicates the grouper rejected or could not fully process an input, and the DRG should not be trusted without review.","example":"OK","enum":["OK","DX_CANNOT_BE_PDX","INVALID_SEX","INVALID_DISCHARGE_STATUS","INVALID_PDX","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"]},"initialGrouperReturnCode":{"type":"string","description":"Grouper status for the initial (pre-HAC) pass. Same value set as finalGrouperReturnCode.","example":"OK","enum":["OK","DX_CANNOT_BE_PDX","INVALID_SEX","INVALID_DISCHARGE_STATUS","INVALID_PDX","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"]},"hacStatus":{"type":"string","description":"Effect of Hospital Acquired Condition processing. NOT_APPLICABLE means no HAC logic applied; FINAL_DRG_NO_CHANGE means HACs were present but did not change the DRG; FINAL_DRG_CHANGES means the DRG was downgraded because a condition was hospital-acquired.","example":"NOT_APPLICABLE","enum":["NOT_APPLICABLE","FINAL_DRG_NO_CHANGE","FINAL_DRG_CHANGES","FINAL_DRG_UNGROUPABLE"]},"numHacCategoriesSatisfied":{"type":"integer","description":"Count of distinct HAC categories satisfied by the claim.","format":"int32","example":0},"diagnosisValidation":{"type":"object","additionalProperties":{"type":"boolean","description":"Per-diagnosis: whether the grouper recognised the code. Keyed by submitted code with periods stripped. False means the code was not found in this grouper version and was ignored during assignment.","example":false},"description":"Per-diagnosis: whether the grouper recognised the code. Keyed by submitted code with periods stripped. False means the code was not found in this grouper version and was ignored during assignment.","example":{"I509":true,"E119":true}},"procedureValidation":{"type":"object","additionalProperties":{"type":"boolean","description":"Per-procedure: whether the grouper recognised the code. False means the code was ignored - note this happens for valid ICD-10-PCS codes that simply are not in this grouper version's procedure table.","example":false},"description":"Per-procedure: whether the grouper recognised the code. False means the code was ignored - note this happens for valid ICD-10-PCS codes that simply are not in this grouper version's procedure table.","example":{"02100Z9":true}},"diagnosisSeverityFlags":{"type":"object","additionalProperties":{"type":"string","description":"Per-diagnosis severity classification actually used. The *_EXCLUDED values mean the code carries that severity in general but was excluded for this claim - either by DRG-specific logic or by the principal diagnosis exclusion list. This is the field that explains why a CC or MCC did not raise the severity. Values: MCC, CC, NEITHER, MCC_EXCLUDED, CC_EXCLUDED, MCC_EXCLUDED_BY_DRG_LOGIC, CC_EXCLUDED_BY_DRG_LOGIC.","example":"{\"I509\":\"NEITHER\",\"J9601\":\"MCC\"}"},"description":"Per-diagnosis severity classification actually used. The *_EXCLUDED values mean the code carries that severity in general but was excluded for this claim - either by DRG-specific logic or by the principal diagnosis exclusion list. This is the field that explains why a CC or MCC did not raise the severity. Values: MCC, CC, NEITHER, MCC_EXCLUDED, CC_EXCLUDED, MCC_EXCLUDED_BY_DRG_LOGIC, CC_EXCLUDED_BY_DRG_LOGIC.","example":{"I509":"NEITHER","J9601":"MCC"}},"diagnosisAffectsDrg":{"type":"object","additionalProperties":{"type":"boolean","description":"Per-diagnosis: whether the code influenced either grouping pass. Convenience boolean - true whenever diagnosisAffectsDrgDetail is not NONE.","example":false},"description":"Per-diagnosis: whether the code influenced either grouping pass. Convenience boolean - true whenever diagnosisAffectsDrgDetail is not NONE.","example":{"I509":true,"E119":false}},"diagnosisPoaStatus":{"type":"object","additionalProperties":{"type":"string","description":"Per-diagnosis present-on-admission evaluation. POA_NOT_CHECKED is the common case and simply means the grouper had no reason to examine POA for that code - it does not indicate an error. Values: POA_NOT_CHECKED, POA_NOT_RECOGNIZED, POA_RECOGNIZED_NOT_POA, POA_RECOGNIZED_YES_POA, HOSPITAL_EXEMPT, BLANK_DX_NOT_CONSIDERED.","example":"{\"I509\":\"POA_NOT_CHECKED\",\"J9601\":\"POA_NOT_CHECKED\"}"},"description":"Per-diagnosis present-on-admission evaluation. POA_NOT_CHECKED is the common case and simply means the grouper had no reason to examine POA for that code - it does not indicate an error. Values: POA_NOT_CHECKED, POA_NOT_RECOGNIZED, POA_RECOGNIZED_NOT_POA, POA_RECOGNIZED_YES_POA, HOSPITAL_EXEMPT, BLANK_DX_NOT_CONSIDERED.","example":{"I509":"POA_NOT_CHECKED","J9601":"POA_NOT_CHECKED"}},"procedureAffectsDrg":{"type":"object","additionalProperties":{"type":"boolean","description":"Per-procedure: whether the code influenced either grouping pass. True whenever procedureAffectsDrgDetail is not NONE.","example":false},"description":"Per-procedure: whether the code influenced either grouping pass. True whenever procedureAffectsDrgDetail is not NONE.","example":{"02100Z9":true}},"diagnosisAffectsDrgDetail":{"type":"object","additionalProperties":{"type":"string","description":"Per-diagnosis grouping impact, unreduced. INITIAL affected only the pre-HAC pass, FINAL only the post-HAC pass, BOTH affected both, NONE had no effect. Use this rather than diagnosisAffectsDrg when you need to explain which pass a code influenced. Values: INITIAL, FINAL, BOTH, NONE.","example":"{\"I509\":\"BOTH\",\"E119\":\"NONE\"}"},"description":"Per-diagnosis grouping impact, unreduced. INITIAL affected only the pre-HAC pass, FINAL only the post-HAC pass, BOTH affected both, NONE had no effect. Use this rather than diagnosisAffectsDrg when you need to explain which pass a code influenced. Values: INITIAL, FINAL, BOTH, NONE.","example":{"I509":"BOTH","E119":"NONE"}},"procedureAffectsDrgDetail":{"type":"object","additionalProperties":{"type":"string","description":"Per-procedure grouping impact, unreduced. Same value set as diagnosisAffectsDrgDetail.","example":"{\"02100Z9\":\"BOTH\"}"},"description":"Per-procedure grouping impact, unreduced. Same value set as diagnosisAffectsDrgDetail.","example":{"02100Z9":"BOTH"}},"procedureIsOperatingRoom":{"type":"object","additionalProperties":{"type":"boolean","description":"Per-procedure: whether the code is an operating-room procedure. OR procedures are what push a claim to a SURGICAL DRG.","example":false},"description":"Per-procedure: whether the code is an operating-room procedure. OR procedures are what push a claim to a SURGICAL DRG.","example":{"02100Z9":true}},"diagnosisHacCategories":{"type":"object","additionalProperties":{"type":"array","description":"Per-diagnosis HAC categories satisfied. Only diagnoses that triggered at least one HAC appear. Each entry is formatted \"<list>-<number>: <description> (<status>)\".","example":{"T8131XA":["HAC-12: Surgical Site Infection (FINAL_DRG_CHANGES)"]},"items":{"type":"string","description":"Per-diagnosis HAC categories satisfied. Only diagnoses that triggered at least one HAC appear. Each entry is formatted \"<list>-<number>: <description> (<status>)\".","example":"{\"T8131XA\":[\"HAC-12: Surgical Site Infection (FINAL_DRG_CHANGES)\"]}"}},"description":"Per-diagnosis HAC categories satisfied. Only diagnoses that triggered at least one HAC appear. Each entry is formatted \"<list>-<number>: <description> (<status>)\".","example":{"T8131XA":["HAC-12: Surgical Site Infection (FINAL_DRG_CHANGES)"]}}},"description":"MS-DRG grouping result, before and after HAC processing."},"ErrorResponse":{"type":"object","properties":{"status":{"type":"integer","format":"int32"},"error":{"type":"string"},"message":{"type":"string"},"details":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","description":"API key for authentication. Contact support to obtain a key.","name":"X-API-Key","in":"header"}}}}