إنتقل إلى المحتوى الرئيسي

Claims Batch DRG Validator

Enabled per account

The Claims Batch DRG Validator must be enabled for your account. Without it a batch is processed as usual, without DRG.

The Claims Batch DRG Validator calculates the AR-DRGs of every inpatient claim in a claims batch. It follows the same rules as the Pre-auth DRG Coder. Each inpatient claim gets:

  • a claimed DRG, from all its lines, compared with the DRG the provider billed
  • an approved DRG, from the approved lines only, after Najeeb's AI review, and recalculated if the decisions change later
  • the provider DRG and the settled DRG you record after review
Before you start

Read DRG Coder & Validator first. This page uses its shared objects, DRG mode and data rules.

How It Works​

  1. Upload: upload the batch CSV as usual, with DRG Enabled set to TRUE on the rows of each inpatient claim you want DRG-coded, and the DRG columns on those rows. Put the billed DRG in Provider DRG Code.
  2. AI review: Najeeb processes the batch as usual. Its lines are grouped into claims by claim_id, and the AI reviews them.
  3. DRG calculation: after the AI review, Najeeb calculates the claimed and approved DRGs of every DRG-enabled inpatient claim in bulk.
    • A DRG problem never fails the batch, a claim, or the AI review.
    • It is reported on the claim, and in the batch summary.
  4. Results: read them with Batch Results. Each claim carries its DRG results, the batch result summary carries the totals in drg_summary, and the CLAIM webhook carries both when the batch reaches PENDING_AUDIT.
  5. After review: when a reviewer changes the decisions, the approved DRG is recalculated and compared with the claimed DRG again.

When DRG Coding Runs​

ConditionIf not met
drg_enabled is true on at least one line of the claimThe claim is not grouped. The claim result has no drg key
The claim's claim_sub_type is IN_PATIENTThe claim is not grouped. The claim result has no drg key
DRG for claims is enabled for your accountThe batch is processed without DRG. No claim result has a drg key

drg_enabled is a claim-level column. It is not a batch-level upload field: a drg_enabled sent next to batch_erp_id is ignored.

Single claims

A single claim sent with POST /claim/create follows the same rules. In JSON, the DRG keys have the same shape as in the Pre-auth DRG Coder: drg_enabled, provider_drg { drg_version, drg_code, drg_weight } and drg_info { separation_mode, leave_days, length_of_stay, same_day_flag, admission_weight, mechanical_ventilation_hours }. The result carries the same DRG keys as a batch claim.

Claim Key​

A batch claim is identified by your batch ID and your claim number together:

KeyValue
batch_erp_idThe batch ID you uploaded with
claim_idYour claim number. All lines with the same claim_id in a batch are one claim

Use this pair wherever you refer to a claim: in the results, and to link a stand-alone request (claim_reference). A re-uploaded batch is a new batch with a new batch_erp_id.

Request​

DRG Columns​

All DRG columns are optional and claim-level: send the same value on every row of a claim. They are part of the CSV columns. Use the CSV header, or the key as the header.

CSV HeaderKeyTypeDescriptionAccepted Values
DRG Enableddrg_enabledbooleanCalculate the DRG of this claim. One TRUE row enables the claimTRUE, FALSE (default FALSE). Also Y, N, Yes, No, 1, 0. An empty or unreadable value is FALSE
Provider DRG Versionprovider_drg_versionstringAR-DRG version of the billed DRGDefault 9. Any other version makes the billed DRG invalid
Provider DRG Codeprovider_drg_codestringThe DRG the provider billedString, up to 16 characters, kept as sent
Provider DRG Weightprovider_drg_weightnumberRelative weight of the billed DRG0-100, up to 4 decimals
Separation Modeseparation_modestringMode of separation01 to 09
Leave Daysleave_daysintegerLeave days within the stay0 or more, less than the stay
Length of Staylength_of_stayintegerLength of stay in days1 or more
Same Day Flagsame_day_flagbooleanSame-day episodeTRUE, FALSE
Admission Weight (g)admission_weightintegerAdmission weight in grams, for patients under 1 year100-9999
Ventilation Hoursmechanical_ventilation_hoursintegerHours of mechanical ventilation0 or more, at most the stay in hours
A bad DRG value never fails a row or the batch

A value that cannot be read is ignored and reported as a DRG_INFO_VALUE_IGNORED warning in the claim's issues. When the rows of a claim disagree on a column, the value from the row with the lowest row_id is used and a DRG_INFO_INCONSISTENT warning is returned.

Claim Fields Used for Grouping​

Najeeb builds one episode per claim from the claim-level values of its lowest-row_id line, plus every line of the claim. Nothing else in the claim changes the DRG.

Claim line fieldUsed asNotes
date_of_birthDate of birthAge is calculated at admission
genderSexMALE, FEMALE
admission_dateAdmission dateWhen it is empty, claim_date is used
discharge_dateSeparation dateWhen it is empty, claim_date is used
primary_diagnosis_codePrincipal diagnosisICD-10-AM
secondary_diagnosis_codeAdditional diagnosesPipe-separated, e.g. E11.9 | I10. The principal diagnosis is not counted twice
nphies_service_codeProceduresEvery line of the claim. Only SBS V3 procedure codes are used. See Lines that are not procedures
provider_drg_*, separation_mode, leave_days, length_of_stay, same_day_flag, admission_weight, mechanical_ventilation_hoursBilled DRG and grouping inputsSee DRG Columns

Lines that are not procedures​

A claim's lines usually mix procedures with drugs, devices and other services. Najeeb sends every line's nphies_service_code to the grouper, which uses the SBS V3 procedure codes and leaves the others out:

Line codeWhat happensIssue
SBS V3 procedure codeUsed for groupingnone
Shaped like an SBS code (#####-##-##) but not in SBS V3Left out of grouping. The DRG may be missing a procedureINTERVENTION_NOT_MAPPED (WARNING)
Any other code (drug, device, consumable)Left out of groupingINTERVENTION_SKIPPED (INFO)

A line that is itself a DRG (a service of type DRG) is treated as the billed DRG and kept out of the procedures; the issue PROVIDER_DRG_FROM_ITEM reports it.

Example Rows​

One in-patient claim with two rows, taken from the sample batch CSV. Only the columns that matter for DRG are shown; send the rest of each row as usual.

Claim ID,Item ERP ID,Claim Sub Type,Admission Date,Discharge Date,Date of Birth,Gender,Principal Diagnosis Code,NPHIES Service Code,DRG Enabled,Provider DRG Version,Provider DRG Code,Provider DRG Weight,Length of Stay
CLM-1002,CLM-1002-1,IN_PATIENT,2026-11-03,2026-11-06,1992-08-20,FEMALE,J18.9,83300-00-10,TRUE,9,E62B,1.2,3
CLM-1002,CLM-1002-2,IN_PATIENT,2026-11-03,2026-11-06,1992-08-20,FEMALE,J18.9,7000000123,TRUE,9,E62B,1.2,3

Both rows repeat the claim-level values, including every DRG column.

Results​

Claim Result​

Each claim returned by Get Processed Claims can carry three DRG keys. They are left out, not null, when they do not apply:

KeyPresent when
provider_drgA billed DRG was sent or found. Holds drg_version, drg_code, drg_weight, source (REQUEST or ITEM) and validity (VALID or INVALID)
settled_drgA DRG was agreed after review. Holds drg_version, drg_code, drg_weight and settled_at
drgThe claim is in-patient and was sent with drg_enabled

issues is always returned on the claim, and on every item, whether or not DRG is used.

The drg object holds the mode and two calculations:

FieldTypeDescription
modeEnumSHADOW: DRG results are for reference only. PRODUCTION: an invalid billed DRG rejects every item of the claim with reason AD-3-4
claimedobjectEverything the provider sent, grouped and compared with the billed DRG
approvedobjectThe approved items only, compared with the claimed DRG. null before the decisions

Each calculation has drg_request_id, kind, is_current, mode, calculated_at, trigger, status, drg_version, drg_result, diagnoses, items and issues. The fields are described in DRG Calculation Object, and drg_result in DRG Result Object. In a claimed calculation, drg_result.compared_with is PROVIDER and matching tells whether the billed DRG matches Najeeb's; in an approved one, compared_with is CLAIMED.

DRG Calculation Object​

FieldTypeDescription
drg_request_idnumberNajeeb's ID of this calculation
kindEnumCLAIMED, APPROVED (a stand-alone result is STANDALONE)
is_currentbooleantrue for the calculation the claim currently uses
modeEnumSHADOW or PRODUCTION
calculated_atstringWhen it was calculated (ISO 8601)
triggerstringWhat caused the calculation, e.g. BATCH_CHUNK, CLAIM_REVIEW, REVIEWER_UPDATE
statusEnumGROUPED, UNGROUPABLE, ERROR
drg_versionstringAR-DRG version used
drg_resultobjectThe grouping result and the comparison. null when status is ERROR. See DRG Result Object
diagnosesarrayEach diagnosis with code, type, name, valid, used_for_grouping
itemsarrayEach line used, with erp_item_id, item_id, nphies_code, achi_code, mapping_equivalence, valid, used_for_grouping
issuesarrayIssues of this calculation. See Issue Object

Example of a claim with its DRG results:

{
"batch_erp_id": "BATCH-2026-0301-001",
"claim_id": "CLM-1001",
"status": "PENDING",
"issues": [
{
"level": "INFO",
"code": "INTERVENTION_SKIPPED",
"field": "nphies_service_code",
"value": "6281100012345",
"message": "6281100012345 is not an SBS procedure code (for example a drug or device) and was left out of grouping."
}
],
"provider_drg": { "drg_version": "9", "drg_code": "F10A", "drg_weight": null, "source": "REQUEST", "validity": "VALID" },
"drg": {
"mode": "SHADOW",
"claimed": {
"drg_request_id": 3072,
"kind": "CLAIMED",
"is_current": true,
"mode": "SHADOW",
"calculated_at": "2026-03-01T09:12:00.000Z",
"trigger": "BATCH_CHUNK",
"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 },
"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.",
"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": null, "item_id": 55012, "nphies_code": "38306-00-00", "achi_code": "38306-00", "mapping_equivalence": 1, "valid": true, "used_for_grouping": true },
{ "erp_item_id": null, "item_id": 55013, "nphies_code": "6281100012345", "achi_code": null, "mapping_equivalence": null, "valid": false, "used_for_grouping": false }
],
"issues": []
},
"approved": null
},
"items": []
}

The claim's other fields (claim_sub_type, member_id, items and the rest) are as in the Claim Result Object.

Filtering Claims by DRG​

Get Processed Claims filters on the claim's current claimed DRG, so you can fetch only the claims that need attention:

Query parameterValuesReturns
drg_statusGROUPED, UNGROUPABLE, ERRORClaims whose claimed DRG has this status
drg_matchingMATCHED, NOT_MATCHED, NOT_SENT, INVALIDClaims whose billed DRG compares this way with Najeeb's DRG
GET /batch/result/BATCH-2026-0301-001/claims?drg_matching=NOT_MATCHED

Batch Summary​

The DRG totals are in the root key drg_summary of Get Batch Result Summary, and in the CLAIM webhook sent at PENDING_AUDIT. The key is present only for a batch with at least one DRG-enabled claim. It is not part of the claims endpoint.

FieldTypeDescription
inpatient_claimsnumberDRG-enabled in-patient claims in the batch
groupednumberClaims whose claimed DRG has status GROUPED
ungroupablenumberClaims with status UNGROUPABLE
errorsnumberClaims with status ERROR
provider_drg_matchingnumberClaims whose billed DRG matches Najeeb's DRG
provider_drg_not_matchingnumberClaims whose billed DRG differs from Najeeb's DRG
provider_drg_not_sentnumberClaims with no billed DRG
provider_drg_invalidnumberClaims whose billed DRG is not a valid AR-DRG V9.0 DRG
changed_by_reviewnumberClaims whose approved DRG differs from the claimed DRG
rejection_appliednumberInvalid billed DRGs that rejected items (PRODUCTION mode)
rejection_shadownumberInvalid billed DRGs that would have rejected items (SHADOW mode)
"drg_summary": {
"inpatient_claims": 8200,
"grouped": 8050,
"ungroupable": 90,
"errors": 60,
"provider_drg_matching": 7310,
"provider_drg_not_matching": 690,
"provider_drg_not_sent": 50,
"provider_drg_invalid": 20,
"changed_by_review": 340,
"rejection_applied": 0,
"rejection_shadow": 20
}

Errors​

DRG validation never fails the batch. A DRG column that cannot be read is ignored with a warning, and every other DRG problem is reported per claim: the claim's drg.claimed.status is ERROR and the cause is an ERROR issue in drg.claimed.issues. The codes are the same as in the Pre-auth DRG Coder, plus:

Issue codeDescription
E_DRG_003An in-patient claim has neither admission_date nor claim_date, or neither discharge_date nor claim_date
DRG_INFO_VALUE_IGNOREDA DRG column value could not be read and was ignored (warning)
DRG_INFO_INCONSISTENTThe lines of a claim sent different values for one DRG column (warning)
PROVIDER_DRG_INVALIDThe billed DRG is not a valid AR-DRG V9.0 DRG. In PRODUCTION mode every item of the claim is rejected with reason AD-3-4