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

Pre-auth DRG Coder

Preview

The Pre-auth DRG Coder is being released. This page describes the contract it is built to; details may still change before release.

The Pre-auth DRG Coder calculates the AR-DRGs of an inpatient prior authorization while Najeeb processes and reviews it. You keep using the same endpoints, and ask for DRG coding with one flag. Najeeb returns:

  • the claimed DRG: the DRG of the whole request, compared with the DRG the provider billed
  • the approved DRG: the DRG of the approved procedures only, recalculated whenever the decisions change, and compared with the claimed DRG
  • the provider DRG and the settled DRG you record after review

See The Four DRGs for how they relate.

Before you start

Read DRG Coder & Validator first. This page uses its shared objects (provider_drg, settled_drg, drg_info, the DRG result and issues), its DRG mode and its data rules.

How It Works​

  1. Your system sends the prior authorization with drg_enabled: true, provider_drg and drg_info.
  2. Najeeb creates it as usual. DRG never rejects or delays a prior authorization.
  3. The claimed DRG is calculated alongside the AI review. It never blocks or changes the AI processing.
  4. The approved DRG is calculated when the AI decision is saved, and again whenever item decisions change.
  5. Both DRGs, the provider DRG and the settled DRG are in Get Prior Authorization and the PRE_AUTH_RESULT webhook.
Not using DRG? Your integration keeps working

A prior authorization sent without drg_enabled: true is processed exactly as before. The only change you will see is the new root issues list (and issues on each item), which repeats information already in notes and request_alerts. No existing key is removed or changed.

When DRG Coding Runs​

ConditionIf not met
drg_enabled is trueNo DRG coding. No drg key in the response
claim_sub_type is IN_PATIENTNo DRG coding, and no drg key. AR-DRG classifies admitted episodes only
The Pre-auth DRG Coder is enabled for your accountThe prior authorization is processed as usual; the drg results have status: ERROR with issue E_DRG_014

provider_drg is stored and returned whenever you send it, even without drg_enabled.

Create Prior Authorization​

New Parameters​

Optional root-level parameters on Create Prior Authorization:

ParameterTypeRequiredDescriptionAccepted Values
drg_enabledbooleanNoCalculate the DRGs of this requesttrue, false (default). null is false
provider_drgobjectNoThe DRG the provider billedSee DRG Reference Object
drg_infoobjectNoGrouping inputsSee DRG Info Object

Prior Authorization Fields Used for Grouping​

FieldUsed asNotes
member_dobDate of birthAge is calculated at admission
member_genderSexMALE, FEMALE
encounter_start_dateAdmission dateNeeded for DRG coding. See the note below
encounter_end_dateSeparation dateNeeded for DRG coding. For a request sent before discharge, send the expected discharge date
diagnoses[]Principal and additional diagnosesExactly one PRIMARY. ICD-10-AM codes
items[].nphies_codeProceduresClaimed DRG: every item. Approved DRG: only items ACCEPTED or PARTIALLY_ACCEPTED. See Items that are not procedures
supporting_info[]Admission weight, ventilation hoursOnly when drg_info doesn't have them. See the names to use
Encounter dates

encounter_start_date and encounter_end_date stay optional, even with drg_enabled: true. Without them, the prior authorization is still created and processed, but the DRGs cannot be calculated: drg.claimed.status is ERROR with issue E_DRG_003. Najeeb does not fall back to period_start_date or treatment_date.

Length of stay

encounter_length_of_stay is free text and is not used for grouping. Najeeb calculates the length of stay from the encounter dates. To send a number, use drg_info.length_of_stay.

Items that are not procedures​

items usually mix procedures with drugs, devices and other services. Najeeb uses the SBS V3 procedure codes and leaves the others out:

Item codeWhat happensIssue
SBS V3 procedure codeUsed for grouping—
Shaped like an SBS code (#####-##-##) but not in SBS V3Left out of groupingINTERVENTION_NOT_MAPPED (WARNING)
Any other code (drug, device, consumable)Left out of groupingINTERVENTION_SKIPPED (INFO)

Quantity never affects grouping. A partially accepted procedure counts as performed in the approved DRG.

Provider DRG on an item​

Many providers bill the DRG as a service line instead of sending provider_drg. Najeeb accepts both.

How a DRG line is recognised:

  • its service_code or nphies_code is an AR-DRG V9.0 code, or
  • its service_description or nphies_description is exactly a DRG description, or
  • its service_type or nphies_type is DRG

Spacing, dashes, dots, letter case and a DRG or AR-DRG prefix are ignored, so F10A, f10-a and DRG F10A are all recognised.

What you sendProvider DRG usedIssue
provider_drg onlyprovider_drg—
One DRG line, no provider_drgThe line's code (source: ITEM)PROVIDER_DRG_FROM_ITEM (INFO)
Several DRG lines with different codesThe first line's codePROVIDER_DRG_MULTIPLE_ITEMS (WARNING)
provider_drg and a DRG line that differprovider_drgPROVIDER_DRG_CONFLICT (WARNING)
A line typed DRG whose code is not a DRGStored as sent, validity: INVALIDPROVIDER_DRG_UNKNOWN (WARNING)

A DRG line is never grouped as a procedure. It stays in the prior authorization and is processed as usual.

Invalid provider DRG​

A provider DRG that is not a valid AR-DRG V9.0 code never rejects the prior authorization:

  • It is stored as sent, with validity: INVALID.
  • It gets a PROVIDER_DRG_INVALID issue.
  • The DRGs are still calculated, without a provider comparison.

What happens to the items depends on the DRG mode:

ModeItems
SHADOWUnchanged. Issue DRG_REJECTION_SHADOW (INFO)
PRODUCTIONEvery item gets NPHIES reason AD-3-4 "Incorrect DRG calculated", and the issue DRG_REJECTION_APPLIED. This rejection is kept when the AI decision arrives. If it lands after the result was pushed, the PRE_AUTH_RESULT webhook is sent again. Reviewers can override it.

A valid provider DRG that differs from Najeeb's claimed DRG is a mismatch. It is reported in issues only, in both modes.

Example Request​

Only the fields that matter for DRG coding are shown. Send the rest of the body as usual.

{
"transaction_id": "550e8400-e29b-41d4-a716-446655440000",
"authorization_number": "AU-20260221-0042",
"claim_type": "INSTITUTIONAL",
"claim_sub_type": "IN_PATIENT",
"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": [
{
"erp_item_id": "ITEM-001",
"nphies_code": "38306-00-00",
"service_code": "CARD-0042",
"service_description": "Percutaneous insertion of 1 transluminal stent into single coronary artery"
},
{
"erp_item_id": "ITEM-002",
"nphies_code": "6281100012345",
"service_code": "PH-CLOP-75",
"service_description": "Clopidogrel 75 mg tablets"
}
],
"drg_enabled": true,
"provider_drg": {
"drg_version": "9",
"drg_code": "F10B",
"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. Every key is optional, and null is read as not sent.

Earlier field names

drg_info.provider_drg_code and drg_info.provider_drg_weight are still accepted as aliases of provider_drg. provider_drg wins when both are sent.

Update Prior Authorization: Settled DRG​

Record the DRG the payer and provider settled on with the optional settled_drg on Update Prior Authorization (PATCH /approval-request/update/:transaction_id). It can also be set by a reviewer in the Najeeb portal.

{
"status": "PARTIALLY_ACCEPTED",
"erp_reviewer_id": "REV-17",
"settled_drg": {
"drg_version": "9",
"drg_code": "F60A",
"drg_weight": 0.8731
}
}
RuleDetail
Validationdrg_code must be a valid AR-DRG V9.0 code; otherwise 422 E_DRG_020
Clearing"settled_drg": null clears it; leaving the key out keeps it
RecalculationSetting it alone does not recalculate anything. If the same update changes item decisions, the approved DRG is recalculated
WeightStored and returned, not checked: Najeeb has no DRG weights loaded yet

Result​

Where the DRG data appears​

In Get Prior Authorization and the data of the PRE_AUTH_RESULT webhook:

KeyPresentContent
issuesAlways, for every prior authorizationRequest-level issues. See Request Issues
items[].issues (items_decisions[].issues in the webhook)AlwaysIssues about that item
provider_drgWhen a provider DRG was sent or foundDRG Reference Object, with source and validity
settled_drgWhen setDRG Reference Object, with settled_at
drgWhen sent with drg_enabled: true and inpatientmode, claimed and approved
drg fieldDescription
modeSHADOW or PRODUCTION
claimedThe current claimed DRG result. See DRG Result Object
approvedThe current approved DRG result, or null until the first decision

Only the current calculations are returned. Earlier ones stay available with Get DRG Result, using their drg_request_id. notes and request_alerts are unchanged; provider-DRG warnings are also added to request_alerts as DRG: <message>.

Example​

The provider billed F10B, and Najeeb's claimed DRG is also F10B. The AI review then rejected the stent (ITEM-001), so the approved DRG is F60A, the medical DRG for the same admission without the procedure. The diagnoses and items arrays inside each result are shortened.

"issues": [
{
"level": "INFO",
"code": "APPROVED_DRG_CHANGED",
"message": "The approved DRG F60A differs from the claimed DRG F10B: procedure 38306-00-00, which drove grouping, was not approved."
}
],
"provider_drg": {
"drg_version": "9",
"drg_code": "F10B",
"drg_weight": null,
"source": "REQUEST",
"validity": "VALID"
},
"settled_drg": null,
"drg": {
"mode": "SHADOW",
"claimed": {
"drg_request_id": 2048,
"kind": "CLAIMED",
"is_current": true,
"mode": "SHADOW",
"calculated_at": "2026-02-21T08:16:02+03:00",
"trigger": "CREATE",
"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": "F10B", "drg_weight": null },
"settled_drg": null,
"compared_with": "PROVIDER",
"compared_drg_code": "F10B",
"matching": true,
"matching_reason": "MATCH",
"matching_split_reason": null,
"matching_test": null,
"matching_message": "Provider DRG F10B matches Najeeb's DRG.",
"values_used": { "age_years": 63, "age_days": null, "length_of_stay": 3, "same_day_flag": false, "admission_weight": null }
},
"diagnoses": [],
"items": [
{ "erp_item_id": "ITEM-001", "nphies_code": "38306-00-00", "achi_code": "38306-00", "mapping_equivalence": 1, "valid": true, "used_for_grouping": true },
{ "erp_item_id": "ITEM-002", "nphies_code": "6281100012345", "achi_code": null, "mapping_equivalence": null, "valid": false, "used_for_grouping": false }
],
"issues": [
{ "level": "INFO", "code": "PROVIDER_DRG_MATCH", "field": "provider_drg.drg_code", "value": "F10B", "message": "Provider DRG F10B matches Najeeb's DRG." },
{ "level": "INFO", "code": "INTERVENTION_SKIPPED", "field": "items[1].nphies_code", "value": "6281100012345", "message": "6281100012345 is not an SBS procedure code (for example a drug or device) and was left out of grouping." }
]
},
"approved": {
"drg_request_id": 2051,
"kind": "APPROVED",
"is_current": true,
"mode": "SHADOW",
"calculated_at": "2026-02-21T08:19:40+03:00",
"trigger": "AI_DECISION",
"status": "GROUPED",
"drg_version": "9",
"drg_result": {
"najeeb_drg_code": "F60A",
"najeeb_drg_description": "Circulatory Dsrd, Adm for AMI W/O Invas Card Inves Proc",
"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": 2,
"complexity_raw": 1.84,
"provider_drg": { "drg_version": "9", "drg_code": "F10B", "drg_weight": null },
"settled_drg": null,
"compared_with": "CLAIMED",
"compared_drg_code": "F10B",
"matching": false,
"matching_reason": "INTERVENTION_MISSING",
"matching_split_reason": null,
"matching_test": null,
"matching_message": "The claimed DRG F10B is surgical, but no approved procedure qualifies for one, so the approved DRG is F60A (Circulatory Dsrd, Adm for AMI W/O Invas Card Inves Proc), a medical DRG. Procedures not approved: 38306-00-00.",
"values_used": { "age_years": 63, "age_days": null, "length_of_stay": 3, "same_day_flag": false, "admission_weight": null }
},
"diagnoses": [],
"items": [
{ "erp_item_id": "ITEM-002", "nphies_code": "6281100012345", "achi_code": null, "mapping_equivalence": null, "valid": false, "used_for_grouping": false }
],
"issues": [
{ "level": "INFO", "code": "CLAIMED_DRG_INTERVENTION_MISSING", "message": "The claimed DRG F10B is surgical, but no approved procedure qualifies for one, so the approved DRG is F60A (Circulatory Dsrd, Adm for AMI W/O Invas Card Inves Proc), a medical DRG. Procedures not approved: 38306-00-00." }
]
}
}

When each DRG is calculated​

EventClaimed DRGApproved DRGtrigger
CreateYes, alongside the AI reviewNo: no decisions yetCREATE
AI decision savedNoYesAI_DECISION
An automated decision changes itemsNoYesAUTOMATION
A reviewer changes item decisions in the portalNoYesREVIEWER_UPDATE
Your Update Prior Authorization changes item decisionsNoYesINTEGRATION_UPDATE
Only settled_drg changesNoNo—
Create with retry: true (accepted)YesYes, when decisions existRETRY
ReopenNoRecalculated at the next decision—

"Item decisions change" means the set of approved items is different afterwards. Each new calculation becomes current, and the previous one is kept as history.

When grouping fails​

A DRG problem never blocks the prior authorization or its AI review. The affected result reports the problem:

"claimed": {
"drg_request_id": 2049,
"kind": "CLAIMED",
"is_current": true,
"mode": "SHADOW",
"trigger": "CREATE",
"status": "ERROR",
"drg_version": "9",
"drg_result": null,
"diagnoses": [],
"items": [],
"issues": [
{
"level": "ERROR",
"code": "E_DRG_003",
"field": "encounter_end_date",
"value": null,
"message": "encounter_start_date and encounter_end_date are required when drg_enabled is true and claim_sub_type is IN_PATIENT"
}
]
}

When the claimed DRG failed, the approved DRG is still calculated, without a comparison (CLAIMED_DRG_NOT_AVAILABLE). After a temporary failure such as E_DRG_016, send the request again with retry: true.

Errors​

DRG never rejects a prior authorization, except for malformed input:

Error CodeHTTP StatusDescription
E_BAD_REQUEST_400400drg_enabled, provider_drg or drg_info is malformed (wrong type or out of range); see details. An invalid DRG code is not malformed: see Invalid provider DRG
E_DRG_020422Update: settled_drg.drg_code is not a valid AR-DRG V9.0 code

Every other DRG problem is reported in the affected result's issues as an ERROR issue, with status: ERROR:

Issue codeDescription
E_DRG_001The AR-DRG version is not enabled
E_DRG_002There is not exactly one PRIMARY diagnosis
E_DRG_003An encounter date is missing
E_DRG_004encounter_end_date is before encounter_start_date
E_DRG_005drg_info.leave_days is not less than the stay length
E_DRG_007drg_info.mechanical_ventilation_hours is more than the stay in hours
E_DRG_008The grouper rejected one or more diagnosis codes as not valid ICD-10-AM. Najeeb is alerted
E_DRG_009drg_info.same_day_flag contradicts the encounter dates
E_DRG_010provider_drg.drg_weight was sent without drg_code
E_DRG_011member_dob is after encounter_start_date
E_DRG_014The Pre-auth DRG Coder is not enabled for your account
E_DRG_016The DRG service was unavailable. Send the request again with retry: true
E_DRG_017The DRG service could not process the request. Contact Najeeb support with the drg_request_id