Skip to main content

Stand-alone DRG Coder

Preview

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 sendNajeeb does
The episode onlyGroups 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.

Before you start

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​

ParameterTypeRequiredDescriptionAccepted Values
remote_referencestringNoYour own ID for this DRG request. Makes the request idempotent: see IdempotencyString, 1–255 characters. Unique across your DRG requests
transaction_idstringNoLinks the result to a prior authorization: the transaction_id you created it with. Not unique: a prior authorization can be coded more than onceString, 1–255 characters. Must match an existing prior authorization
claim_referenceobjectNoLinks the result to a batch claimSee Claim Reference Object. Works once the batch has reached PENDING_AUDIT. Unknown claim: 404 E_DRG_021
member_dob *stringYesPatient's date of birth. On or before encounter_start_dateFull ISO-8601 DateTime
member_gender *EnumYesPatient's genderMALE, FEMALE
encounter_start_date *stringYesAdmission date and timeFull ISO-8601 DateTime
encounter_end_date *stringYesSeparation (discharge) date and time. On or after encounter_start_dateFull ISO-8601 DateTime
diagnoses *arrayYesEpisode diagnoses. Exactly one PRIMARY1–30 items. See Diagnosis Object
itemsarrayNoProcedures performed. Can be empty for a medical episode0–30 items. See Item Object
provider_drgobjectNoThe DRG to compare with. Send it to group and compareSee DRG Reference Object
drg_infoobjectNoGrouping inputsSee DRG Info Object
supporting_infoarrayNoAdmission weight and ventilation hours, when not in drg_infoSee the names to use
remote_reference, transaction_id or claim_reference?
  • remote_reference identifies this DRG request in your system. Sending it again returns the stored result.
  • transaction_id or claim_reference points at a prior authorization or claim Najeeb already has. Send at most one of them: both together are rejected with 409 E_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.

Encounter dates are required here

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​
ParameterTypeRequiredDescriptionAccepted Values
type *EnumYesDiagnosis typePRIMARY, SECONDARY (lowercase also accepted)
code *stringYesICD-10-AM code, with or without the dotFor example I21.4 or I214
namestringNoDescription. Not used for groupingMax 255 characters
Item Object​
ParameterTypeRequiredDescriptionAccepted Values
nphies_code *stringYesSBS V3 procedure codeFor example 38306-00-00. Must exist in SBS V3 (E_DRG_013 otherwise)
service_codestringNoProvider's service code. A DRG code here is read as the provider DRGMax 255 characters
service_descriptionstringNoProvider's description. Not used for groupingMax 255 characters
nphies_descriptionstringNoNPHIES description of the procedure. Not used for groupingMax 255 characters
erp_item_idstringNoYour item ID, returned with the itemMax 255 characters
treatment_datestringNoNot used for groupingFull ISO-8601 DateTime
Provider DRG Object​
ParameterTypeRequiredDescriptionAccepted Values
drg_codestringYes, when the object is sentThe DRG the provider billed. Kept as sent, even when invalidString, up to 16 characters, e.g. F10A
drg_versionstringNoAR-DRG version. It is also the version used for grouping: an unsupported version ends the request with E_DRG_001String, up to 8 characters. Default 9
drg_weightnumberNoRelative weight of the billed DRG. Optional0–100, up to 4 decimals
Claim Reference Object​
ParameterTypeRequiredDescriptionAccepted Values
batch_erp_id *stringYesThe batch_erp_id of the batchString, 1–255 characters
claim_id *stringYesThe claim's claim_id in that batchString, 1–255 characters

Example Request​

Group and compare: the provider billed F10A.

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
}
}'

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).

FieldTypeDescription
remote_referencestringYour remote_reference, or null
transaction_idstringThe linked prior authorization, or null
claim_referenceobjectThe linked claim, or null
kindEnumSTANDALONE for every result of this API
is_currentbooleanAlways false for a stand-alone result: it is never the current calculation of a prior authorization or claim
modeEnumSHADOW or PRODUCTION. Reference only in SHADOW
calculated_atstringWhen the DRG was calculated (ISO 8601)
triggerstringMANUAL for this API
replayedbooleantrue 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
codenumberHTTP status code
messagestringResult 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.validity is INVALID, and issues gets PROVIDER_DRG_INVALID.
  • In PRODUCTION mode, a linked prior authorization or claim gets the AD-3-4 rejection through its own processing, not through this API. See DRG Mode.

Idempotency with remote_reference​

You sendNajeeb returns
A new remote_referenceThe request is grouped and stored. replayed is false
A remote_reference already used, with any request body200 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_referenceThe 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 CodeHTTP StatusDescription
E_BAD_REQUEST_400400Request validation failed — see details. Includes more than 30 diagnoses or procedures, and a malformed provider_drg
E_DRG_001422drg_version is not an enabled AR-DRG version
E_DRG_002422There is not exactly one PRIMARY diagnosis
E_DRG_004422encounter_end_date is before encounter_start_date
E_DRG_005422leave_days is not less than the stay length
E_DRG_007422mechanical_ventilation_hours is more than the stay in hours
E_DRG_008422The grouper rejected one or more diagnosis codes as not valid ICD-10-AM. details lists them. Najeeb is alerted
E_DRG_009422same_day_flag contradicts the encounter dates
E_DRG_010422provider_drg.drg_weight was sent without drg_code
E_DRG_011422member_dob is after encounter_start_date
E_DRG_013422One or more items[].nphies_code are not SBS V3 codes. details lists them
E_DRG_014403The Stand-alone DRG Coder is not enabled for your account
E_DRG_015404drg_request_id or remote_reference not found
E_DRG_016503The DRG service is temporarily unavailable. Retry later
E_DRG_017502The DRG service could not process the request. Contact Najeeb support with the drg_request_id
E_DRG_019404No prior authorization has this transaction_id
E_DRG_021404claim_reference matches no claim of a processed batch
E_DRG_022409Both transaction_id and claim_reference were sent
401 Unauthorized401Missing or invalid access-key

An invalid provider DRG is not an error: see Invalid provider DRG.