Stand-alone DRG Coder
This API is being released. This page describes the contract it is built to; details may still change before release.
The Stand-alone DRG Coder groups one inpatient episode on demand and returns the AR-DRG in the same response. It does one of two things:
| You send | Najeeb does |
|---|---|
| The episode only | Groups it: returns Najeeb's DRG |
The episode and provider_drg (or a DRG service line) | Groups it and compares the result with the provider DRG, explaining any difference |
Use it to code an episode before or outside a prior authorization or claim, to check a DRG your coders assigned, or as a tool for an AI agent trying out codings. Every request is stored and can be retrieved with Get DRG Result, whether or not it is linked to anything.
Read DRG Coder & Validator first. It defines the shared objects (provider_drg, drg_info, the DRG result and issues), the DRG mode, and the rules for dates, length of stay and admission weight.
Base URL
https://api.{client_namespace}.najeeb.ai/v4.0/health
Authentication
Requests are authenticated with an API key in the access-key header. The Stand-alone DRG Coder must be enabled for your account; otherwise requests are rejected with 403 (E_DRG_014).
access-key: YOUR_API_KEY
Endpoints
1. Group an Episode
POST /drg/group
Request Body Parameters
| Parameter | Type | Required | Description | Accepted Values |
|---|---|---|---|---|
remote_reference | string | No | Your own ID for this DRG request. Makes the request idempotent: see Idempotency | String, 1–255 characters. Unique across your DRG requests |
transaction_id | string | No | Links the result to a prior authorization: the transaction_id you created it with. Not unique: a prior authorization can be coded more than once | String, 1–255 characters. Must match an existing prior authorization |
claim_reference | object | No | Links the result to a batch claim | See Claim Reference Object. Works once the batch has reached PENDING_AUDIT. Unknown claim: 404 E_DRG_021 |
member_dob * | string | Yes | Patient's date of birth. On or before encounter_start_date | Full ISO-8601 DateTime |
member_gender * | Enum | Yes | Patient's gender | MALE, FEMALE |
encounter_start_date * | string | Yes | Admission date and time | Full ISO-8601 DateTime |
encounter_end_date * | string | Yes | Separation (discharge) date and time. On or after encounter_start_date | Full ISO-8601 DateTime |
diagnoses * | array | Yes | Episode diagnoses. Exactly one PRIMARY | 1–30 items. See Diagnosis Object |
items | array | No | Procedures performed. Can be empty for a medical episode | 0–30 items. See Item Object |
provider_drg | object | No | The DRG to compare with. Send it to group and compare | See DRG Reference Object |
drg_info | object | No | Grouping inputs | See DRG Info Object |
supporting_info | array | No | Admission weight and ventilation hours, when not in drg_info | See the names to use |
remote_reference, transaction_id or claim_reference?remote_referenceidentifies this DRG request in your system. Sending it again returns the stored result.transaction_idorclaim_referencepoints at a prior authorization or claim Najeeb already has. Send at most one of them: both together are rejected with409E_DRG_022.
A linked result is always kind: STANDALONE and is_current: false. It is stored with the prior authorization or claim, but never replaces their own claimed or approved DRG.
The Stand-alone DRG Coder always groups an inpatient episode, so both encounter dates are required. In the prior authorization APIs they are optional.
Diagnosis Object
| Parameter | Type | Required | Description | Accepted Values |
|---|---|---|---|---|
type * | Enum | Yes | Diagnosis type | PRIMARY, SECONDARY (lowercase also accepted) |
code * | string | Yes | ICD-10-AM code, with or without the dot | For example I21.4 or I214 |
name | string | No | Description. Not used for grouping | Max 255 characters |
Item Object
| Parameter | Type | Required | Description | Accepted Values |
|---|---|---|---|---|
nphies_code * | string | Yes | SBS V3 procedure code | For example 38306-00-00. Must exist in SBS V3 (E_DRG_013 otherwise) |
service_code | string | No | Provider's service code. A DRG code here is read as the provider DRG | Max 255 characters |
service_description | string | No | Provider's description. Not used for grouping | Max 255 characters |
nphies_description | string | No | NPHIES description of the procedure. Not used for grouping | Max 255 characters |
erp_item_id | string | No | Your item ID, returned with the item | Max 255 characters |
treatment_date | string | No | Not used for grouping | Full ISO-8601 DateTime |
Provider DRG Object
| Parameter | Type | Required | Description | Accepted Values |
|---|---|---|---|---|
drg_code | string | Yes, when the object is sent | The DRG the provider billed. Kept as sent, even when invalid | String, up to 16 characters, e.g. F10A |
drg_version | string | No | AR-DRG version. It is also the version used for grouping: an unsupported version ends the request with E_DRG_001 | String, up to 8 characters. Default 9 |
drg_weight | number | No | Relative weight of the billed DRG. Optional | 0–100, up to 4 decimals |
Claim Reference Object
| Parameter | Type | Required | Description | Accepted Values |
|---|---|---|---|---|
batch_erp_id * | string | Yes | The batch_erp_id of the batch | String, 1–255 characters |
claim_id * | string | Yes | The claim's claim_id in that batch | String, 1–255 characters |
Example Request
Group and compare: the provider billed F10A.
- cURL
- JavaScript
- Python
curl -X POST "https://api.{client_namespace}.najeeb.ai/v4.0/health/drg/group" \
-H "access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"remote_reference": "ENC-2026-000731",
"transaction_id": "550e8400-e29b-41d4-a716-446655440000",
"member_dob": "1962-03-10T00:00:00+03:00",
"member_gender": "MALE",
"encounter_start_date": "2026-02-21T08:15:00+03:00",
"encounter_end_date": "2026-02-24T13:00:00+03:00",
"diagnoses": [
{ "type": "PRIMARY", "code": "I21.4", "name": "Acute subendocardial myocardial infarction" },
{ "type": "SECONDARY", "code": "E11.9" },
{ "type": "SECONDARY", "code": "I10" }
],
"items": [
{ "nphies_code": "38306-00-00", "service_code": "CARD-0042", "erp_item_id": "ITEM-001" }
],
"provider_drg": {
"drg_version": "9",
"drg_code": "F10A",
"drg_weight": null
},
"drg_info": {
"separation_mode": "09",
"leave_days": 0,
"length_of_stay": 3,
"same_day_flag": false,
"admission_weight": null,
"mechanical_ventilation_hours": 0
}
}'
const response = await fetch('https://api.{client_namespace}.najeeb.ai/v4.0/health/drg/group', {
method: 'POST',
headers: {
'access-key': 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
remote_reference: 'ENC-2026-000731',
transaction_id: '550e8400-e29b-41d4-a716-446655440000',
member_dob: '1962-03-10T00:00:00+03:00',
member_gender: 'MALE',
encounter_start_date: '2026-02-21T08:15:00+03:00',
encounter_end_date: '2026-02-24T13:00:00+03:00',
diagnoses: [
{ type: 'PRIMARY', code: 'I21.4', name: 'Acute subendocardial myocardial infarction' },
{ type: 'SECONDARY', code: 'E11.9' },
{ type: 'SECONDARY', code: 'I10' },
],
items: [{ nphies_code: '38306-00-00', service_code: 'CARD-0042', erp_item_id: 'ITEM-001' }],
provider_drg: { drg_version: '9', drg_code: 'F10A', drg_weight: null },
drg_info: {
separation_mode: '09',
leave_days: 0,
length_of_stay: 3,
same_day_flag: false,
admission_weight: null,
mechanical_ventilation_hours: 0,
},
}),
});
const result = await response.json();
import requests
response = requests.post(
'https://api.{client_namespace}.najeeb.ai/v4.0/health/drg/group',
headers={'access-key': 'YOUR_API_KEY', 'Content-Type': 'application/json'},
json={
'remote_reference': 'ENC-2026-000731',
'transaction_id': '550e8400-e29b-41d4-a716-446655440000',
'member_dob': '1962-03-10T00:00:00+03:00',
'member_gender': 'MALE',
'encounter_start_date': '2026-02-21T08:15:00+03:00',
'encounter_end_date': '2026-02-24T13:00:00+03:00',
'diagnoses': [
{'type': 'PRIMARY', 'code': 'I21.4', 'name': 'Acute subendocardial myocardial infarction'},
{'type': 'SECONDARY', 'code': 'E11.9'},
{'type': 'SECONDARY', 'code': 'I10'},
],
'items': [{'nphies_code': '38306-00-00', 'service_code': 'CARD-0042', 'erp_item_id': 'ITEM-001'}],
'provider_drg': {'drg_version': '9', 'drg_code': 'F10A', 'drg_weight': None},
'drg_info': {
'separation_mode': '09',
'leave_days': 0,
'length_of_stay': 3,
'same_day_flag': False,
'admission_weight': None,
'mechanical_ventilation_hours': 0,
},
},
)
result = response.json()
drg_info shows every key. admission_weight is null because it is used only for patients under 1 year old, and drg_weight is null because it is optional during shadow billing. To group only, leave provider_drg out.
Success Response (200 OK)
A request that is grouped returns 200, including an episode that could not be assigned a real DRG (status = UNGROUPABLE).
| Field | Type | Description |
|---|---|---|
remote_reference | string | Your remote_reference, or null |
transaction_id | string | The linked prior authorization, or null |
claim_reference | object | The linked claim, or null |
kind | Enum | STANDALONE for every result of this API |
is_current | boolean | Always false for a stand-alone result: it is never the current calculation of a prior authorization or claim |
mode | Enum | SHADOW or PRODUCTION. Reference only in SHADOW |
calculated_at | string | When the DRG was calculated (ISO 8601) |
trigger | string | MANUAL for this API |
replayed | boolean | true when this is the stored result of an earlier request with the same remote_reference |
| … | Every field of the DRG Result Object, with kind: STANDALONE and is_current: false | |
code | number | HTTP status code |
message | string | Result message |
{
"drg_request_id": 1024,
"remote_reference": "ENC-2026-000731",
"transaction_id": "550e8400-e29b-41d4-a716-446655440000",
"claim_reference": null,
"replayed": false,
"kind": "STANDALONE",
"is_current": false,
"mode": "SHADOW",
"calculated_at": "2026-02-21T10:42:03+03:00",
"trigger": "MANUAL",
"status": "GROUPED",
"drg_version": "9",
"drg_result": {
"najeeb_drg_code": "F10B",
"najeeb_drg_description": "Interventional Coronary Procedures, Admitted for AMI, Minor Complexity",
"najeeb_drg_weight": null,
"mdc_code": "05",
"mdc_description": "Diseases & Disorders of the Circulatory System",
"grouper_status": "00",
"grouper_status_description": "Normal grouping",
"ungroupable": false,
"complexity": 1,
"complexity_raw": 1,
"provider_drg": { "drg_version": "9", "drg_code": "F10A", "drg_weight": null, "source": "REQUEST", "validity": "VALID" },
"settled_drg": null,
"compared_with": "PROVIDER",
"compared_drg_code": "F10A",
"matching": false,
"matching_reason": "DIFFERENT_SPLIT",
"matching_split_reason": "COMPLEXITY",
"matching_test": "complexity score >= 4",
"matching_message": "F10A needs a complexity score of 4 or more; this episode scores 1, so Najeeb assigned F10B (Interventional Coronary Procedures, Admitted for AMI, Minor Complexity). Additional diagnoses that raised the score: none. Did not raise it: E11.9, I10. A complication or comorbidity may be missing from the diagnoses sent, or sent with an invalid code.",
"values_used": {
"age_years": 63,
"age_days": null,
"length_of_stay": 3,
"same_day_flag": false,
"admission_weight": null
}
},
"diagnoses": [
{ "code": "I21.4", "type": "PRIMARY", "name": "Acute subendocardial myocardial infarction", "valid": true, "used_for_grouping": true },
{ "code": "E11.9", "type": "SECONDARY", "name": "Type 2 diabetes mellitus without complication", "valid": true, "used_for_grouping": false },
{ "code": "I10", "type": "SECONDARY", "name": "Essential (primary) hypertension", "valid": true, "used_for_grouping": false }
],
"items": [
{ "erp_item_id": "ITEM-001", "nphies_code": "38306-00-00", "achi_code": "38306-00", "mapping_equivalence": 1, "valid": true, "used_for_grouping": true }
],
"issues": [
{
"level": "WARNING",
"code": "PROVIDER_DRG_COMPLEXITY_HIGHER",
"field": "provider_drg.drg_code",
"value": "F10A",
"message": "F10A needs a complexity score of 4 or more; this episode scores 1, so Najeeb assigned F10B (Interventional Coronary Procedures, Admitted for AMI, Minor Complexity). Additional diagnoses that raised the score: none. Did not raise it: E11.9, I10. A complication or comorbidity may be missing from the diagnoses sent, or sent with an invalid code."
}
],
"code": 200,
"message": "DRG grouped successfully"
}
For every kind of mismatch message, see Provider DRG Issues.
Invalid provider DRG
A provider_drg.drg_code that is not a valid AR-DRG V9.0 DRG never fails the request:
- Najeeb still groups the episode, without a comparison.
drg_result.provider_drg.validityisINVALID, andissuesgetsPROVIDER_DRG_INVALID.- In
PRODUCTIONmode, a linked prior authorization or claim gets theAD-3-4rejection through its own processing, not through this API. See DRG Mode.
Idempotency with remote_reference
| You send | Najeeb returns |
|---|---|
A new remote_reference | The request is grouped and stored. replayed is false |
A remote_reference already used, with any request body | 200 with the stored result and the same drg_request_id. The episode is not grouped again and the new body is ignored. replayed is true. Use a new remote_reference to group a different episode |
No remote_reference | The request is always grouped as a new request |
2. Get DRG Result
GET /drg/get-one/:drg_request_id
GET /drg/get-one?remote_reference=ENC-2026-000731
Returns a stored result in the format of Group an Episode. This works for every calculation, including the claimed and approved DRGs of a prior authorization or claim, using the drg_request_id they carry. Requests that failed are stored too, and are returned with their ErrorCode and issues.
curl "https://api.{client_namespace}.najeeb.ai/v4.0/health/drg/get-one/1024" \
-H "access-key: YOUR_API_KEY"
Error Responses
{
"ErrorCode": "E_DRG_002",
"message": "Exactly one PRIMARY diagnosis is required; 2 were sent",
"details": [{ "drg_request_id": 1031 }],
"issues": [
{
"level": "ERROR",
"code": "E_DRG_002",
"field": "diagnoses",
"value": null,
"message": "Exactly one PRIMARY diagnosis is required; 2 were sent"
}
]
}
| Error Code | HTTP Status | Description |
|---|---|---|
E_BAD_REQUEST_400 | 400 | Request validation failed — see details. Includes more than 30 diagnoses or procedures, and a malformed provider_drg |
E_DRG_001 | 422 | drg_version is not an enabled AR-DRG version |
E_DRG_002 | 422 | There is not exactly one PRIMARY diagnosis |
E_DRG_004 | 422 | encounter_end_date is before encounter_start_date |
E_DRG_005 | 422 | leave_days is not less than the stay length |
E_DRG_007 | 422 | mechanical_ventilation_hours is more than the stay in hours |
E_DRG_008 | 422 | The grouper rejected one or more diagnosis codes as not valid ICD-10-AM. details lists them. Najeeb is alerted |
E_DRG_009 | 422 | same_day_flag contradicts the encounter dates |
E_DRG_010 | 422 | provider_drg.drg_weight was sent without drg_code |
E_DRG_011 | 422 | member_dob is after encounter_start_date |
E_DRG_013 | 422 | One or more items[].nphies_code are not SBS V3 codes. details lists them |
E_DRG_014 | 403 | The Stand-alone DRG Coder is not enabled for your account |
E_DRG_015 | 404 | drg_request_id or remote_reference not found |
E_DRG_016 | 503 | The DRG service is temporarily unavailable. Retry later |
E_DRG_017 | 502 | The DRG service could not process the request. Contact Najeeb support with the drg_request_id |
E_DRG_019 | 404 | No prior authorization has this transaction_id |
E_DRG_021 | 404 | claim_reference matches no claim of a processed batch |
E_DRG_022 | 409 | Both transaction_id and claim_reference were sent |
401 Unauthorized | 401 | Missing or invalid access-key |
An invalid provider DRG is not an error: see Invalid provider DRG.