API Reference

The DRG Grouper API provides programmatic access to Medicare Severity-Diagnosis Related Group (MS-DRG) calculation based on patient demographics and ICD-10 codes.

Introduction

Our API accepts patient information including diagnoses, procedures, age, sex, and discharge status, then returns the calculated MS-DRG along with validation results and Hospital-Acquired Condition (HAC) logic.

Base URL: https://api.revenuecycle.works/api/drg

Authentication

API authentication is optional but recommended. Include your API key in the request header:

X-API-Key: your_api_key_here

💡 Try before you buy! Test the API without a key (10 requests/min limit) before requesting API access.

Rate Limits

Without API key: 10 requests per minute
With API key: Custom rate limits based on your needs - contact us to discuss.

curl https://api.revenuecycle.works/api/drg/group \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json"

The Group Endpoint

The primary endpoint for calculating MS-DRG assignments. Submit patient demographics, diagnoses, and procedures to receive the appropriate DRG classification, severity level, and detailed validation results.

POST https://api.revenuecycle.works/api/drg/group

Content-Type: application/json

This endpoint processes inpatient hospital claims and returns:

Final MS-DRG assignment (e.g., "359")
Major Diagnostic Category (MDC)
Severity level (MCC, CC, or No CC/MCC)
Medical vs. Surgical classification
Code validation results for all diagnoses and procedures
Hospital-Acquired Condition (HAC) status

Request

Headers

Parameter	Description
X-API-Key optional	Your API key for authentication (omit for testing with 10 req/min limit)
Content-Type	`application/json`

Body Parameters

Parameter	Description
grouperVersion required string	MS-DRG version: `"400"`, `"401"`, `"410"`, `"411"`, `"420"`, or `"430"` (latest, FY2026) See effective dates in Enum Reference →
principalDiagnosis required object	Primary diagnosis object with two properties: • `code` - ICD-10-CM code without periods (e.g., `"I2510"` not `"I25.10"`) • `poa` - Present on Admission indicator
ageInYears required integer	Patient age in years (0-120)
sex required string	Sex enum value: `"MALE"`, `"FEMALE"`, or `"UNKNOWN"`
dischargeStatus required string	Discharge status enum value. Common values: `"HOME_SELFCARE_ROUTINE"`, `"SNF"`, `"HOME_HEALTH_SERVICE"`, `"DIED"`, `"HOSPICE_HOME"` See all 43 codes in Enum Reference below
admissionDiagnosis optional string	Admission diagnosis ICD-10-CM code without periods (e.g., `"C022"`). Unlike principalDiagnosis, this is just a string, not an object.
secondaryDiagnoses optional array	Array of diagnosis objects, each with: • `code` - ICD-10-CM code without periods (e.g., `"I2510"` not `"I25.10"`) • `poa` - Present on Admission indicator
procedures optional array	Array of ICD-10-PCS procedure code strings (7 characters) (e.g., `"0CYS0Z0"`)

Enum Values Reference

Grouper Versions & Effective Dates

Version	Effective Dates	API Value
V40.0	10/01/2022 - 03/31/2023	`"400"`
V40.1	04/01/2023 - 09/30/2023	`"401"`
V41.0	10/01/2023 - 03/31/2024	`"410"`
V41.1	04/01/2024 - 09/30/2024	`"411"`
V42.0	10/01/2024 - 09/30/2025	`"420"`
V43.0	10/01/2025 - 09/30/2026	`"430"` ← latest

Present on Admission (POA) Indicators

Code	API Enum Value	Description
Y	`"Y"`	Yes, condition was present at admission
N	`"N"`	No, condition was not present at admission
U	`"U"`	Unknown/documentation insufficient
W	`"W"`	Clinically undetermined
1	`"ONE"`	Exempt from POA reporting
empty string ""	`"BLANK"`	Exempt from POA reporting (omitted/not provided)

Sex Values

API Enum Value	Description
`"MALE"`	Male patient
`"FEMALE"`	Female patient
`"UNKNOWN"`	Unknown or unspecified sex

Discharge Status Codes (All 43 Values)

Code	API Enum Value
01	`"HOME_SELFCARE_ROUTINE"`
02	`"SHORT_TERM_HOSPITAL"`
03	`"SNF"`
04	`"CUST_SUPP_CARE"`
05	`"CANC_CHILD_HOSP"`
06	`"HOME_HEALTH_SERVICE"`
07	`"LEFT_AGAINST_MEDICAL_ADVICE"`
20	`"DIED"`
21	`"COURT_LAW_ENFRC"`
30	`"STILL_A_PATIENT"`
43	`"FEDERAL_HOSPITAL"`
50	`"HOSPICE_HOME"`
51	`"HOSPICE_MEDICAL_FACILITY"`
61	`"SWING_BED"`
62	`"REHAB_FACILITY_REHAB_UNIT"`
63	`"LONG_TERM_CARE_HOSPITAL"`
64	`"NURSING_FACILITY_MEDICAID_CERTIFIED"`
65	`"PSYCH_HOSP_UNIT"`
66	`"CRIT_ACC_HOSP"`
69	`"DESIGNATED_DISASTER_ALTERNATIVE_CARE_SITE"`
70	`"OTH_INSTITUTION"`
81	`"HOME_SELF_CARE_W_PLANNED_READMISSION"`
82	`"SHORT_TERM_HOSPITAL_W_PLANNED_READMISSION"`
83	`"SNF_W_PLANNED_READMISSION"`
84	`"CUST_SUPP_CARE_W_PLANNED_READMISSION"`
85	`"CANC_CHILD_HOSP_W_PLANNED_READMISSION"`
86	`"HOME_HEALTH_SERVICE_W_PLANNED_READMISSION"`
87	`"COURT_LAW_ENFRC_W_PLANNED_READMISSION"`
88	`"FEDERAL_HOSPITAL_W_PLANNED_READMISSION"`
89	`"SWING_BED_W_PLANNED_READMISSION"`
90	`"REHAB_FACILITY_UNIT_W_PLANNED_READMISSION"`
91	`"LTCH_W_PLANNED_READMISSION"`
92	`"NURSG_FAC_MEDICAID_CERT_W_PLANNED_READMISSION"`
93	`"PSYCH_HOSP_UNIT_W_PLANNED_READMISSION"`
94	`"CRIT_ACC_HOSP_W_PLANNED_READMISSION"`
95	`"OTH_INSTITUTION_W_PLANNED_READMISSION"`

⚠️ Code Formatting: All ICD-10 codes must be submitted without periods. For example, use "I2510" instead of "I25.10".

Example Request

curl -X POST https://api.revenuecycle.works/api/drg/group \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "grouperVersion": "430",
    "admissionDiagnosis": "I213",
    "principalDiagnosis": {
      "code": "I213",
      "poa": "Y"
    },
    "secondaryDiagnoses": [
      {"code": "J9601", "poa": "Y"},
      {"code": "I5021", "poa": "Y"},
      {"code": "J9811", "poa": "Y"},
      {"code": "I255", "poa": "Y"},
      {"code": "F17210", "poa": "Y"},
      {"code": "I959", "poa": "Y"},
      {"code": "R739", "poa": "Y"}
    ],
    "procedures": ["0271356", "02C03Z6", "B2151ZZ", "B2111ZZ", "4A023N7", "3E073PZ"],
    "ageInYears": 68,
    "sex": "MALE",
    "dischargeStatus": "HOME_SELFCARE_ROUTINE"
  }'

Response

Success Response (200)

Returns a JSON object with the calculated DRG and validation information.

💡 Severity Levels: MCC (Major Complication/Comorbidity), CC (Complication/Comorbidity), and No CC/MCC represent the severity of secondary diagnoses that can affect DRG assignment and reimbursement rates.

Field	Description
finalDrg	Final assigned MS-DRG code (3 digits)
finalMdc	Major Diagnostic Category (2 digits)
finalSeverity	Severity level: `"MCC"`, `"CC"`, or `"No CC/MCC"`
finalMedSurgType	`"MEDICAL"` or `"SURGICAL"`
finalGrouperReturnCode	Validation status: `"OK"` or error code
diagnosisValidation	Map of diagnosis codes to validation boolean. `false` indicates invalid code (e.g., contains decimals, unknown code). Invalid codes are excluded from DRG calculation.
diagnosisSeverityFlags	Severity designation per diagnosis code (e.g., `"MCC"`, `"CC"`, `"NONE"`)
procedureValidation	Map of procedure codes to validation boolean. `false` indicates invalid code format or unrecognized code. Invalid procedures are excluded from DRG calculation.
diagnosisAffectsDrg	Map of diagnosis codes to boolean indicating whether the diagnosis affected the final DRG assignment
diagnosisPoaStatus	Map of diagnosis codes to their Present on Admission (POA) status as submitted in the request
procedureAffectsDrg	Map of procedure codes to boolean indicating whether the procedure affected the final DRG assignment
procedureIsOperatingRoom	Map of procedure codes to boolean indicating whether the procedure is classified as an operating room procedure
hacStatus	Hospital-Acquired Condition impact status

Example Response

{
  "finalDrg": "359",
  "finalMdc": "05",
  "finalBaseDrg": "359",
  "finalSeverity": "MCC",
  "finalMedSurgType": "SURGICAL",
  "finalGrouperReturnCode": "OK",
  "diagnosisValidation": {
    "J9811": true,
    "J9601": true,
    "I959": true,
    "I255": true,
    "I213": true,
    "F17210": true,
    "R739": true,
    "I5021": true
  },
  "procedureValidation": {
    "0271356": true,
    "02C03Z6": true,
    "B2151ZZ": true,
    "B2111ZZ": true,
    "4A023N7": true,
    "3E073PZ": true
  },
  "diagnosisSeverityFlags": {
    "J9811": "MCC",
    "J9601": "MCC",
    "I959": "NONE",
    "I255": "NONE",
    "I213": "NONE",
    "F17210": "NONE",
    "R739": "NONE",
    "I5021": "MCC"
  },
  "diagnosisAffectsDrg": {
    "J9811": true,
    "J9601": true,
    "I959": false,
    "I255": false,
    "I213": false,
    "F17210": false,
    "R739": false,
    "I5021": true
  },
  "diagnosisPoaStatus": {
    "J9811": "Y",
    "J9601": "Y",
    "I959": "Y",
    "I255": "Y",
    "I213": "Y",
    "F17210": "Y",
    "R739": "Y",
    "I5021": "Y"
  },
  "procedureAffectsDrg": {
    "0271356": true,
    "02C03Z6": true,
    "B2151ZZ": false,
    "B2111ZZ": false,
    "4A023N7": false,
    "3E073PZ": false
  },
  "procedureIsOperatingRoom": {
    "0271356": true,
    "02C03Z6": true,
    "B2151ZZ": false,
    "B2111ZZ": false,
    "4A023N7": false,
    "3E073PZ": false
  },
  "hacStatus": "NO_HAC_PRESENT"
}

Code Examples

Here's how to make a request in Python and JavaScript:

Python

import requests

response = requests.post(
    "https://api.revenuecycle.works/api/drg/group",
    headers={
        "X-API-Key": "your_api_key_here",
        "Content-Type": "application/json"
    },
    json={
        "grouperVersion": "430",
        "admissionDiagnosis": "I213",
        "principalDiagnosis": {"code": "I213", "poa": "Y"},
        "secondaryDiagnoses": [
            {"code": "J9601", "poa": "Y"},
            {"code": "I5021", "poa": "Y"},
            {"code": "J9811", "poa": "Y"},
            {"code": "I255", "poa": "Y"},
            {"code": "F17210", "poa": "Y"},
            {"code": "I959", "poa": "Y"},
            {"code": "R739", "poa": "Y"}
        ],
        "procedures": ["0271356", "02C03Z6", "B2151ZZ", "B2111ZZ", "4A023N7", "3E073PZ"],
        "ageInYears": 68,
        "sex": "MALE",
        "dischargeStatus": "HOME_SELFCARE_ROUTINE"
    }
)

result = response.json()
print(f"DRG: {result['finalDrg']}")
print(f"MDC: {result['finalMdc']}")
print(f"Severity: {result['finalSeverity']}")

JavaScript

const response = await fetch(
  "https://api.revenuecycle.works/api/drg/group",
  {
    method: "POST",
    headers: {
      "X-API-Key": "your_api_key_here",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      grouperVersion: "430",
      admissionDiagnosis: "I213",
      principalDiagnosis: { code: "I213", poa: "Y" },
      secondaryDiagnoses: [
        { code: "J9601", poa: "Y" },
        { code: "I5021", poa: "Y" },
        { code: "J9811", poa: "Y" },
        { code: "I255", poa: "Y" },
        { code: "F17210", poa: "Y" },
        { code: "I959", poa: "Y" },
        { code: "R739", poa: "Y" }
      ],
      procedures: ["0271356", "02C03Z6", "B2151ZZ", "B2111ZZ", "4A023N7", "3E073PZ"],
      ageInYears: 68,
      sex: "MALE",
      dischargeStatus: "HOME_SELFCARE_ROUTINE"
    })
  }
);

const data = await response.json();
console.log("DRG:", data.finalDrg);
console.log("MDC:", data.finalMdc);
console.log("Severity:", data.finalSeverity);

Errors

HTTP Status Codes

200	Success - DRG calculated successfully
400	Bad Request - Invalid input data
401	Unauthorized - Invalid or missing API key
429	Too Many Requests - Rate limit exceeded
500	Server Error - Contact support

Grouper Return Codes

The finalGrouperReturnCode field indicates validation status:

Return Code	Description
`"OK"`	Success, DRG assigned without errors
`"INVALID_PDX"`	Principal diagnosis code is invalid
`"DX_CANNOT_BE_PDX"`	Code cannot be used as principal diagnosis
`"INVALID_SEX"`	Sex conflicts with diagnosis/procedure
`"HAC_MISSING_ONE_POA"`	HAC condition missing POA indicator

Example Error Response

{
  "finalGrouperReturnCode": "INVALID_PDX",
  "finalDrg": "999",
  "error": "Principal diagnosis code is invalid or cannot be used as primary diagnosis"
}

Need Help?

Questions about integration? Contact our support team or try the free web tool.