POST /v1/group

DRG Grouper API

MS-DRG assignment from ICD-10-CM diagnoses, ICD-10-PCS procedures, and patient demographics. The grouper resolves the correct CMS version from the discharge date, runs Medicare Code Editor checks, and returns the DRG with its full context — versioned and reproducible.

Base URL https://api.quantarahealth.com

Try it live

This playground calls a free demo deployment of the real grouping engine — no key required. The demo hosts CMS v43.1, so use discharge dates between 2026-04-01 and 2026-09-30. Responses currently include a warning while full CMS decision-tree parity is completed. Want the real thing? Create a free trial key and call the production API from the interactive reference.

Request body — edit freely

Response

Press “Send request” to call the live demo.

POST /api/group on this site — same engine, demo wrapper.

Authentication

Every request is authenticated with a bearer token in the Authorization header. Tokens are issued during onboarding, are scoped (grouping requires the group:write scope), and come in test and live environments so you can integrate before you go to production.

Header

Authorization: Bearer qh_live_XXXXXXXXXXXXXXXX

Group a single case

POST /v1/group

Submit one inpatient case and receive its MS-DRG. The CMS grouper version is resolved automatically from discharge_date; each response is billed as one unit.

Request body

Field	Type	Description
`discharge_date`	date, required	Discharge date (`YYYY-MM-DD`). Determines the CMS grouper version applied.
`principal_diagnosis`	string, required	ICD-10-CM principal diagnosis. Dots and spacing are normalized — `I21.4` and `I214` are equivalent.
`secondary_diagnoses`	string[]	Up to 24 ICD-10-CM secondary diagnosis codes.
`secondary_diagnosis_poa`	object	Present-on-admission indicator per secondary diagnosis: `Y`, `N`, `U`, `W`, or `1`. Drives HAC severity handling.
`procedures`	string[]	Up to 25 ICD-10-PCS procedure codes.
`age`	integer	Patient age in years, 0–124.
`sex`	string	`M`, `F`, or `U`.
`discharge_status`	string	Two-character UB-04 patient discharge status code, e.g. `01`.

Request

curl https://api.quantarahealth.com/v1/group \
  -H "Authorization: Bearer $QH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "discharge_date": "2026-07-01",
    "principal_diagnosis": "I21.4",
    "secondary_diagnoses": ["E11.9"],
    "secondary_diagnosis_poa": { "E11.9": "Y" },
    "procedures": ["027034Z"],
    "age": 67,
    "sex": "F",
    "discharge_status": "01"
  }'

Response — 200

{
  "request_id": "req_8f3a…",
  "ms_drg": "322",
  "title": "Percutaneous Cardiovascular
    Procedures with Intraluminal
    Device without MCC",
  "mdc": "05",
  "cms_version": "43.1",
  "effective_date_range": {
    "start": "2026-04-01",
    "end": "2026-09-30"
  },
  "mce_edits": [],
  "warnings": [
    "PYTHON_CMS_ALGORITHM_PARTIAL: …"
  ],
  "billable_units": 1
}

Response fields

Field	Type	Description
`request_id`	string	Unique id for this request — quote it in support and audit trails.
`ms_drg`	string	Assigned MS-DRG.
`title`	string	Official DRG title.
`mdc`	string \| null	Major Diagnostic Category.
`cms_version`	string	CMS grouper version that produced the result (e.g. `43.1`).
`effective_date_range`	object	`start` and `end` dates of the applied version's effective window.
`mce_edits`	array	Medicare Code Editor findings: `code`, `description`, and `severity` (`error` or `warning`).
`warnings`	string[]	Non-fatal notices about the grouping result.
`billable_units`	integer	Units metered for this request.

CMS version resolution

The grouper version is selected from the discharge date. Currently supported:

Version	Effective window
`43`	2025-10-01 → 2026-03-31
`43.1`	2026-04-01 → 2026-09-30

Discharge dates outside a supported window return 422 UNSUPPORTED_CMS_VERSION. New CMS releases are added as they take effect.

Group a batch

POST /v1/group/batch

Submit up to 100 cases in one call. Each case takes the same fields as a single request, plus an optional client_case_id (returned unchanged so you can correlate results). All cases in a batch must resolve to the same CMS version — mixed windows return 422 MIXED_CMS_VERSIONS. A batch is billed one unit per case.

Request

curl https://api.quantarahealth.com/v1/group/batch \
  -H "Authorization: Bearer $QH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cases": [
      { "client_case_id": "case-001", "discharge_date": "2026-07-01",
        "principal_diagnosis": "I21.4", "procedures": ["027034Z"] },
      { "client_case_id": "case-002", "discharge_date": "2026-07-02",
        "principal_diagnosis": "J18.9", "age": 81 }
    ]
  }'

Errors

Errors return a JSON body with a stable code, a human-readable message, and the request_id.

Status	Code	Meaning
`401`	—	Missing, invalid, revoked, or expired token.
`403`	`INSUFFICIENT_SCOPE`	Token lacks the `group:write` scope.
`422`	`UNSUPPORTED_CMS_VERSION`	Discharge date falls outside every supported CMS version window.
`422`	`MIXED_CMS_VERSIONS`	Batch cases resolve to different CMS versions.
`422`	—	Validation error: unknown fields, malformed codes, out-of-range values.
`501`	`GROUPER_ENGINE_NOT_INTEGRATED`	The grouping engine is unavailable for this deployment.

Service endpoints

Endpoint	Description
`GET /health`	Liveness: service, version, environment.
`GET /ready`	Readiness, including backing-store checks. Returns `503` when degraded.

Ready to group your first case?

Sandbox tokens are issued during design-partner onboarding — send us a message and you'll be calling /v1/group the same week.

Talk to us