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

Claims as a Service / Standard

Najeeb Claims as a Service audits settled claims with Najeeb's AI Engine. Insurance companies in the Kingdom of Saudi Arabia send their claims after adjudication. Najeeb then returns a decision, the approved quantity and amount, and the rejection reasons for every service line, plus DRG results for in-patient claims when DRG is enabled.

Service Description​

Claims reach Najeeb in one of two ways:

Batch (CSV)Single Claim (JSON)
Use it forPeriodic bulk audits, for example a month of settled claimsAuditing one claim at a time, as soon as it is settled
EndpointPOST /batch/file/uploadPOST /claim/create
FormatOne CSV file, one row per service lineOne JSON object per claim, with its lines in items
Your referencebatch_erp_id for the batch, claim_id for each claimclaim_id
NotificationCLAIM webhook on every batch status changeCLAIM_RESULT webhook with the full result
ResultsGET /batch/result/{batch_erp_id} and GET /batch/result/{batch_erp_id}/claimsGET /claim/result/{claim_id}

Both routes validate the same fields, apply the same AI review, and return the same Claim Result Object. Claims have their own endpoints: do not send claims to the Prior Authorization endpoints.

Batches are processed asynchronously. Processing takes from minutes to several hours, depending on the batch size, and the service is built to handle large volumes of items per batch.

Key Features​

  • Batch and single-claim intake: CSV files for bulk audits, JSON for one claim at a time
  • Asynchronous processing: uploads return at once, and results are pushed to your webhook
  • Row-level validation: every line is checked before AI processing, and every error is reported with its row and column
  • AI-powered audit: fraud, waste and abuse detection, and medical and technical claim validation
  • Pre-authorization reconciliation: link a claim to its approval request with authorization_number or transaction_id
  • DRG coding: calculate and validate the AR-DRG of in-patient claims with the Claims Batch DRG Validator
  • KSA compliance: NPHIES service codes and ICD-10 diagnoses

Workflow​

Before the First Upload​

  1. Get your API key and your instance URL from Najeeb. See Authentication.
  2. Register your reference data: the medical providers (by CCHI code) and the policy holders (by ERP ID) that your claims refer to. Claims that refer to an unknown provider or policy holder fail validation.
  3. Register a webhook: use Create Webhook with hook_type CLAIM for batch status updates, and CLAIM_RESULT for single-claim results.

Batch Flow​

After PENDING_AUDIT, the batch moves through the review statuses. Each change is pushed to the CLAIM webhook:

StatusMeaningResults readable
VALIDATINGThe batch was stored and its rows are being validatedNo
FAILEDValidation found errors, or the file had no processable rows. Nothing was processedNo
REJECTEDThe batch was not sent to the AI EngineNo
PROCESSINGAll rows are valid and the AI Engine is auditing the claimsNo
PENDING_AUDITProcessing finished. The results are readyYes
AUDITINGThe batch was opened for auditYes
AUDIT_COMPLETEDThe audit finishedYes
SETTLEDThe batch was settledYes
PAIDThe paid amount was recorded with Set the Paid AmountYes

Single Claim Flow​

A single claim is validated while you wait: an invalid claim is answered with an error at once and nothing is stored. A batch is validated in the background, as shown above.

Integration Guide​

Base URL​

https://api.{client_namespace}.najeeb.ai/v4.0/health

Every endpoint path on this page is relative to this base URL. Requests must use HTTPS.

Authentication​

Every request carries your API key in the access-key header:

access-key: YOUR_API_KEY

See the Authentication Guide.

Identifiers​

Which IDs must match Najeeb, and which are yours

Najeeb never needs real identities. Every person-level identifier can be an anonymized or pseudonymized ID, as long as you use the same value for the same person every time.

FieldKindRule
provider_cchi_idLookupCCHI code of a medical provider registered in Najeeb. An unknown code is a validation error
ph_erp_idLookupERP ID of a policy holder registered in Najeeb. An unknown ID is a validation error
mapped_codeLookupThe service code Najeeb looks the line's service up by
primary_diagnosis_code, secondary_diagnosis_codeLookupICD-10 codes, looked up in Najeeb's diagnosis list
network_codeLookupName of a network registered in Najeeb
authorization_number, transaction_idLookupMust belong to an existing prior authorization in Najeeb. See Linking a Claim to Its Pre-Authorization
member_idStable IDAny stable ID of the member. It can be anonymized. Najeeb uses it to link the member to the policy and, with send_patient_history, to load the member's earlier claims
doctor_id, principal_name_or_idStable IDAny stable ID. Can be anonymized
batch_erp_idYour referenceYour ID of the batch, 1-255 characters. Every batch endpoint uses it
claim_idYour referenceYour ID of the claim. In a batch, the lines that share it form one claim. A single claim's claim_id must be unique in your account
item_erp_idYour referenceYour ID of the service line. It is returned with every validation error and every item result

Your reference IDs only need to be unique within their scope, and any scheme works. Najeeb uses them to group lines into claims, to match results to your records, and to detect fraud, waste and abuse patterns.

1. Batch Upload (CSV)​

1.1 Upload a Batch​

POST /batch/file/upload

Uploads a batch of claims as one CSV file. The call returns as soon as the file is stored. Validation and processing run in the background, and each status change is pushed to the CLAIM webhook.

Request Headers​

HeaderTypeRequiredDescription
access-keystringYesYour API key
Content-TypestringYesmultipart/form-data

Query Parameters​

ParameterTypeRequiredDescriptionAccepted Values
use_price_listbooleanNoPrice each line with the price list configured in Najeeb instead of the sent Unit Pricetrue, false (default false)
send_patient_historybooleanNoInclude each member's earlier claims in the AI audittrue, false (default false)

Form Fields​

FieldTypeRequiredDescriptionAccepted Values
filefileYes, unless file_id is sentThe batch CSV file. See CSV File Format.csv, not empty, at most 1 GB
file_idintegerYes, unless file is sentID of a file already stored in Najeeb, used instead of fileInteger
batch_erp_id *stringYesYour ID of the batch1-255 characters
start_date *dateYesFirst day covered by the batch. Every Claim Date in the file must fall between start_date and end_dateYYYY-MM-DD
end_date *dateYesLast day covered by the batch. Must be after start_dateYYYY-MM-DD
descriptionstringNoFree text stored with the batchString
tagsarrayNoLabels stored with the batchA list, or one comma-separated text, e.g. urgent,review

Example Request​

curl -X POST "https://api.{client_namespace}.najeeb.ai/v4.0/health/batch/file/upload?use_price_list=false&send_patient_history=true" \
-H "access-key: YOUR_API_KEY" \
-F "file=@claims_batch.csv" \
-F "batch_erp_id=BATCH-2026-11-001" \
-F "start_date=2026-11-01" \
-F "end_date=2026-11-30" \
-F "description=November 2026 settled claims" \
-F "tags=november-2026,erp-sync"

Response (201 Created)​

{
"prismaBatchId": 801230,
"message": "batch file uploaded successfully"
}

prismaBatchId is Najeeb's ID of the batch. It is returned as batch_id in the webhook and the results. Use your batch_erp_id for every later call.

Errors​

Error CodeHTTP StatusDescription
E_BAD_REQUEST_400400A form field is invalid; the file is missing, empty or not a .csv; or neither file nor file_id was sent. details lists the problems
E_BATCH_004413The file is larger than 1 GB. Nothing is stored
401 Unauthorized401Missing or invalid access-key

Errors inside the file (a missing value, an unknown code, a wrong enum value) are not returned here. They are reported after upload, through the FAILED webhook and Get Validation Errors.

1.2 CSV File Format​

Sample file

Download the sample batch CSV (two claims, four lines: one out-patient claim and one DRG-enabled in-patient claim) and use it as a starting template.

File Rules​

RuleDetail
One row per service lineEach row is one service line (item). Rows that share a Claim ID form one claim
Claim-level columns repeatClaim-level columns (member, provider, policy, diagnoses, dates, DRG) must carry the same value on every row of the claim
Header rowRequired. It must be within the first 10 lines of the file
Header namesUse the CSV headers listed below, e.g. Claim ID, or the field keys, e.g. claim_id. Header matching ignores letter case, spaces, underscores and hyphens. Column order does not matter
Unknown columnsIgnored
EncodingUTF-8. A byte-order mark (BOM) is allowed
Separator and quotingComma-separated. Put a value in double quotes when it contains a comma, a quote or a line break; write a quote inside a quoted value as two quotes ("")
Empty valuesAn empty cell is "not sent". A required column must not be empty
DatesUse YYYY-MM-DD, e.g. 2026-11-03, or a full ISO 8601 date-time, e.g. 2026-11-03T09:15:00.000Z. Do not use slash dates such as 03/11/2026: they are read month first and can be misread
NumbersPlain numbers with . as the decimal separator, e.g. 1725.50. No thousands separators or currency symbols
BooleansTRUE or FALSE. Y/N, Yes/No and 1/0 are also accepted
Enum valuesUpper-case values from Enums, e.g. IN_PATIENT
Several diagnosesSeparate them with a pipe, e.g. E11.9 | I10. Descriptions follow the same order
SizeAt most 1 GB per file. For very large batches, split the file by period and upload one batch per file

Sample Rows​

The first lines of the sample file, with some columns left out to keep it readable:

Claim ID,Item ERP ID,Claim Type,Claim Sub Type,Claim Date,Admission Date,Discharge Date,Admission Code,Principal Diagnosis Code,Provider CCHI Code,Policy Holder ID,Member ID,Date of Birth,Gender,Mapped Code,Mapped Description,NPHIES Service Code,Service Type,Quantity Claimed,Quantity Approved,Provider Gross Claimed,Unit Price,Gross Approved,Discount,VAT Amount,Net Amount Including VAT Amount,DRG Enabled,Provider DRG Version,Provider DRG Code,Length of Stay
CLM-1001,CLM-1001-1,PROFESSIONAL,OUT_PATIENT,2026-11-01,2026-11-01,2026-11-01,1,J02.9,12345,PH-001,MBR-5001,1990-05-14,MALE,83600-00-10,Consultation general practitioner,83600-00-10,CONSULTATION,1,1,200,200,200,0,30,230,FALSE,,,
CLM-1002,CLM-1002-1,INSTITUTIONAL,IN_PATIENT,2026-11-03,2026-11-03,2026-11-06,1,J18.9,67890,PH-001,MBR-5002,1992-08-20,FEMALE,83300-00-10,Room and board,83300-00-10,AMBULATORY,3,3,1500,500,1500,0,225,1725,TRUE,9,E62B,3
CLM-1002,CLM-1002-2,INSTITUTIONAL,IN_PATIENT,2026-11-03,2026-11-03,2026-11-06,1,J18.9,67890,PH-001,MBR-5002,1992-08-20,FEMALE,7000000123,Ceftriaxone 1 g vial,7000000123,PHARMACEUTICAL,2,2,90,45,90,0,13.5,103.5,TRUE,9,E62B,3

CLM-1002 has two lines. Both repeat the claim-level values, including the DRG columns.

1.3 CSV Columns​

There are 23 required columns, marked *. All other columns are optional: leave them out of the file or leave the cell empty.

The Key is the field name. Use it as an alternative header and to read the results. It is also the field name in the single-claim JSON.

Claim-Level Columns​

Send the same value on every row of the claim.

Claim and Encounter​
CSV HeaderKeyTypeDescriptionAccepted Values
Claim ID *claim_idstringYour ID of the claim. Rows that share it form one claimText, e.g. CLM-1001
Claim Typeclaim_typeenumType of claimClaim Type
Claim Sub Type *claim_sub_typeenumSub-type of claim. DRG is calculated for IN_PATIENT claims onlyClaim Sub Type
Type of Encountertype_of_encounterenumType of encounterType of Encounter
Claim Date *claim_datedateDate of the claim. Must fall between the batch's start_date and end_dateDate
Admission Dateadmission_datedateAdmission date. Used for in-patient claims and DRGDate
Discharge Date *discharge_datedateDischarge date. For an out-patient claim, use the claim dateDate
Admission Code *admission_codestringAdmission codeText, e.g. 1
Admission Diagnosisadmission_diagnosisstringAdmission diagnosis descriptionText
Doctor​
CSV HeaderKeyTypeDescriptionAccepted Values
Unique Physician IDdoctor_idstringStable ID of the treating doctor. Can be anonymizedText
Doctor Namedoctor_namestringDoctor nameText
Doctor Specialtydoctor_specialtyenumDoctor's specialtyDoctor Specialty
Diagnoses​
CSV HeaderKeyTypeDescriptionAccepted Values
Principal Diagnosis Code *primary_diagnosis_codestringPrincipal diagnosisICD-10 code, e.g. J18.9
Principal Diagnosis Descriptionprimary_diagnosis_descriptionstringPrincipal diagnosis descriptionText
Additional Diagnoses Codesecondary_diagnosis_codestringSecondary diagnosesICD-10 codes separated by |, e.g. E11.9 | I10
Additional Diagnosessecondary_diagnosis_descriptionstringSecondary diagnosis descriptions, in the same order as the codesText separated by |
Clinical Information​
CSV HeaderKeyTypeDescriptionAccepted Values
Chief Complaintschief_complaintsstringChief complaintsText
History of Present Illnesshistory_of_present_illnessstringHistory of present illnessText
Treatment Plantreatment_planstringTreatment planText
Significant Signssignificant_signsstringSignificant signsText
General Examinationgeneral_examinationstringGeneral examination findingsText
Is Packageis_packagebooleanThe claim is a packageBoolean
Maternity Coveris_maternitybooleanMaternity caseBoolean
Newbornis_new_bornbooleanNewborn caseBoolean
Medical Provider​
CSV HeaderKeyTypeDescriptionAccepted Values
Provider CCHI Code *provider_cchi_idstringCCHI code of the provider. Must be registered in NajeebText
Provider Internal Codeprovider_internal_codestringYour internal provider codeText
Provider Nphies IDprovider_nphies_idstringProvider NPHIES IDText
Provider Nameprovider_namestringProvider nameText
Provider Typeprovider_typeenumType of providerProvider Type
Provider Cityprovider_citystringProvider cityText
Policy Holder and Pre-Authorization​
CSV HeaderKeyTypeDescriptionAccepted Values
Policy Holder ID *ph_erp_idstringERP ID of the policy holder. Must be registered in NajeebText
Policy holder Namepolicy_holder_namestringPolicy holder nameText
Policy Holder Provincepolicy_holder_provincestringPolicy holder provinceText
Pre-authorization Numberauthorization_numberstringAuthorization number of the prior authorization that covered this claimText, e.g. AU-12345
Transaction IDtransaction_idstringtransaction_id of the prior authorization that covered this claimText, up to 255 characters
Linking a Claim to Its Pre-Authorization​

Send authorization_number, transaction_id, or both. These are the same values used by Prior Authorization, so the AI Engine can compare what was approved with what was claimed.

  • Each value must exist in Najeeb. An unknown value is a validation error.
  • When both are sent, the transaction_id must belong to that authorization_number.

The old header ar_erp_id is still read as authorization_number, but new integrations should not use it.

Member​
CSV HeaderKeyTypeDescriptionAccepted Values
Member ID *member_idstringStable ID of the member. Can be anonymizedText
Member Namemember_namestringMember name. Optional; leave it empty to keep claims anonymousText
Date of Birth *date_of_birthdateMember date of birth. Najeeb calculates the age from itDate
Gender *genderenumMember genderGender
Marital Statusmarital_statusenumMember marital statusMarital Status
NationalitynationalitystringNationalityText, e.g. Saudi
ProvinceprovincestringMember provinceText, e.g. Riyadh
Mobilephone_numberstringMember mobile numberText
RelationrelationenumRelation to the principal memberRelation
Principal Name or IDprincipal_name_or_idstringStable ID of the principal member. Can be anonymizedText
CategorycategorystringThe member's class (category). The old header Class is still readText
Network Codenetwork_codestringThe member's network, by name. Must exist in NajeebText, up to 255 characters
Is VIPis_vipbooleanVIP memberBoolean
Insurance Addition Dateinsurance_addition_datedateDate the member was added to the insuranceDate
Insurance Start Dateinsurance_start_datedateStart of the member's insuranceDate
Insurance End Dateinsurance_end_datedateEnd of the member's insuranceDate
Member Effective Frommember_effective_fromdateStart of the member's cover on the policy. When empty, Insurance Start Date is usedDate
Member Effective Tomember_effective_todateEnd of the member's cover on the policy. Not before Member Effective From. When empty, Insurance End Date is usedDate
Policy​
CSV HeaderKeyTypeDescriptionAccepted Values
Policy Numberpolicy_nostringPolicy numberText, e.g. POL-2026-01
Policy Namepolicy_namestringPolicy nameText
Policy Grouppolicy_groupstringPolicy groupText
Policy Start Datepolicy_start_datedatePolicy start date. When empty, Insurance Start Date is usedDate
Policy End Datepolicy_end_datedatePolicy end date. Not before Policy Start Date. When empty, Insurance End Date is usedDate
Plan Nameplan_namestringPlan nameText
Plan Typeplan_typeenumPlan typePlan Type
DRG​

Optional. These columns switch on DRG coding for an in-patient claim and carry the DRG the provider billed. DRG problems never fail a row or the batch. Accepted values, defaults and the issues they can raise are in Claims Batch DRG Validator: DRG Columns.

CSV HeaderKeyDescription
DRG Enableddrg_enabledTRUE calculates the DRG of this claim. One TRUE row enables the whole claim
Provider DRG Versionprovider_drg_versionAR-DRG version of the billed DRG. Default 9
Provider DRG Codeprovider_drg_codeThe DRG the provider billed, e.g. E62B
Provider DRG Weightprovider_drg_weightRelative weight of the billed DRG
Separation Modeseparation_modeMode of separation, 01 to 09
Leave Daysleave_daysLeave days within the stay
Length of Staylength_of_stayLength of stay in days
Same Day Flagsame_day_flagSame-day episode
Admission Weight (g)admission_weightAdmission weight in grams, for patients under one year
Ventilation Hoursmechanical_ventilation_hoursHours of mechanical ventilation

Line-Level Columns​

These can differ on every row.

Line Identity​
CSV HeaderKeyTypeDescriptionAccepted Values
Item ERP ID *item_erp_idstringYour ID of the line. Returned with its validation errors and its resultText, 1-255 characters
Row IDrow_idintegerYour row number. Returned in the resultWhole number
Service​
CSV HeaderKeyTypeDescriptionAccepted Values
Mapped Code *mapped_codestringThe service code Najeeb looks the service up by. Send the NPHIES code, as in the sample, unless Najeeb set up your own service codes for your accountText, e.g. 83600-00-10
Mapped Description *mapped_descriptionstringDescription of the mapped serviceText
NPHIES Service Codenphies_service_codestringNPHIES service code. Recommended: DRG grouping reads procedures from itText, e.g. 38306-00-00
NPHIES Service Descriptionnphies_service_descriptionstringNPHIES service descriptionText
Service Type *service_typeenumService categoryService Type
Provider Service Codeprovider_service_codestringThe provider's own service codeText
Provider Service Descriptionprovider_service_descriptionstringThe provider's own service descriptionText
Treatment Datetreatment_datedateDate the service was deliveredDate
Tooth IDtooth_idstringTooth number, for dental linesText
UnitunitstringUnit of measure, for drugsText, e.g. mg
RouteroutestringRoute of administrationText, e.g. Oral
FrequencyfrequencyenumFrequency of administrationFrequency
DirectionsdirectionsstringDirections of useText
DurationdurationstringDuration of treatmentText, e.g. 5 days
Days Supplydays_supplystringDays of supply, for pharmacy linesText
Quantities and Amounts​

All amounts are in SAR.

CSV HeaderKeyTypeDescriptionAccepted Values
Quantity Claimed *quantity_claimednumberQuantity claimed by the providerNumber
Quantity Approved *quantity_approvednumberQuantity approved in your adjudicationNumber
Unit Price *unit_pricenumberPrice per unitNumber
Agreed Priceagreed_pricenumberContracted price per unit, when different from Unit PriceNumber
Provider Gross Claimed *amount_claimednumberGross amount claimed by the providerNumber
Gross Approved *amount_approvednumberGross amount approved in your adjudicationNumber
Discount *discountnumberDiscountNumber. 0 when none
FactorfactornumberPricing factorNumber
Deductibleprovider_deductible_mountnumberDeductibleNumber
Exceeding Limitationexceeding_limitationnumberAmount above the benefit limitNumber
VAT Amount *vat_amountnumberVAT on the approved amountNumber. 0 when none
Net Amount Including VAT Amount *net_amount_including_vat_amountnumberApproved amount plus VATNumber
Invoice Numberinvoice_numberstringInvoice numberText
Claimed and approved values

A prior authorization is sent before the service and carries claimed values only. A claim is sent after your adjudication and carries both the claimed and the approved values. This lets the AI Engine compare what was claimed with what you approved.

Benefit​
CSV HeaderKeyTypeDescriptionAccepted Values
Benefit Codebenefit_codeintegerBenefit codeWhole number
Sub-Benefit Codesub_benefit_codeintegerSub-benefit codeWhole number

1.4 Enums​

Enum values are the same in the CSV file and in JSON.

Claim Type​

ValueDescription
INSTITUTIONALInstitutional (hospital) services
PROFESSIONALProfessional (clinic) services
PHARMACYPharmacy services
DENTALDental services
OPTICALOptical services

Claim Sub Type​

ValueDescription
IN_PATIENTIn-patient
OUT_PATIENTOut-patient
EMERGENCYEmergency

Type of Encounter​

ValueDescription
HOSPITAL_INPATIENTHospital in-patient
DAY_CASEDay case
EMERGENCYEmergency
OUTPATIENTOut-patient
HOME_HEALTH_CAREHome health care
PRIMARY_HEALTH_CAREPrimary health care

Provider Type​

ValueDescription
CLINICClinic
POLYCLINICPolyclinic
DENTAL_CLINICDental clinic
HOSPITALHospital
PHARMACYPharmacy
PHYSIOTHERAPYPhysiotherapy center
LABSLaboratory
OPTICAL_CENTEROptical center
AMBULANCE_SERVICESAmbulance services
ONE_DAY_SURGERY_CENTEROne-day surgery center

Plan Type​

ValueDescription
SME_POLICYSME policy
SME_AGGREGATOR_POLICYSME aggregator policy
GROUP_POLICYGroup policy
TOURISM_VISA_POLICYTourism visa policy
PREMIUM_VISA_POLICYPremium visa policy
DOMESTIC_WORKER_POLICYDomestic worker policy
VISITOR_VISA_POLICYVisitor visa policy
VISITOR_VISA_EXTEND_POLICYVisitor visa extension policy

Plan Type also accepts the value written with spaces or hyphens, e.g. GROUP POLICY or group-policy.

Service Type​

ValueDescription
AMBULATORYAmbulatory service
CONSULTATIONConsultation
PHARMACEUTICALDrug
DEVICEMedical device
OPTICALOptical
DENTALDental
BABY_FORMULABaby formula
UNLISTEDUnlisted service

Frequency​

ValueDescription
ODOnce daily
QDOnce daily
Q24HEvery 24 hours
BIDTwice daily
Q12HEvery 12 hours
TIDThree times daily
Q8HEvery 8 hours
QIDFour times daily
Q6HEvery 6 hours
Q4HEvery 4 hours
QODEvery other day
QMMonthly

Gender​

ValueDescription
MALEMale
FEMALEFemale

Marital Status​

ValueDescription
SINGLESingle
MARRIEDMarried
ENGAGEDEngaged
UNKNOWNUnknown
WIDOWEDWidowed
DIVORCEDDivorced
SEPARATEDSeparated

Relation​

ValueDescription
SELFThe member is the principal
FATHERFather
MOTHERMother
SONSon
DAUGHTERDaughter
SISTERSister
HUSBANDHusband
WIFEWife
WIFE_WITHOUT_MATERNITYWife without maternity cover
MOTHER_MBMother (maternity benefit)
SENIOR_EMPLOYEESenior employee
FEMALE_EMPLOYEE_WITH_MATFemale employee with maternity cover
CHILDChild
SPOUSESpouse
EMPLOYEEEmployee
OTHEROther

Doctor Specialty​

ValueValueValue
ALTERNATIVE_MEDICINEGENERAL_SURGERYPEDIATRIC_HEMATO_ONCOLOGY
ANESTHESIOLOGYHEMATO_ONCOLOGYPEDIATRIC_NEPHROLOGY
CARDIOLOGYINFECTIOUS_DISEASESPEDIATRIC_NEUROLOGY
CARDIOVASCULAR_AND_THORACIC_SURGERYINTENSIVISTPEDIATRIC_PULMONOLOGY
COLON_AND_RECTAL_SURGERYINTERNAL_MEDICINEPEDIATRIC_SURGERY
DENTISTLAB_SPECIALISTPEDIATRICS
DERMATOLOGYMEDICAL_GENETICSPHARMACIST
EAR_NOSE_AND_THROATNEPHROLOGYPHYSICAL_MEDICINE_AND_REHABILITATION
EMERGENCY_DEPARTMENTNEUROLOGYPLASTIC_SURGERY
ENDOCRINOLOGY_AND_METABOLISMNEUROSURGERYPREVENTIVE_MEDICINE
FORENSIC_MEDICINENUCLEAR_MEDICINEPSYCHIATRIST
GASTROENTEROLOGYNURSEPULMONOLOGY
GENERAL_PHYSICIANNUTRITIONRADIATION_ONCOLOGY
OBSTETRICS_AND_GYNECOLOGYONCOLOGISTRADIOLOGIST
ONCOLOGY_SURGERYOPHTHALMOLOGYRHEUMATOLOGY
ORTHOPEDIC_SURGERYORTHOTICS_AND_PROSTHETICSSPORTS_MEDICINE
PATHOLOGYPEDIATRIC_CARDIOLOGYUROLOGY
PEDIATRIC_ENDOCRINOLOGYPEDIATRIC_GASTROENTEROLOGYVASCULAR_SURGERY
OTHER
Enums are stricter than in Prior Authorization

Prior Authorization accepts free text for doctor_speciality, items[].service_type and items[].frequency. Claims accept only the enum values above, so map the value, e.g. Cardiology to CARDIOLOGY.

2. Batch Results​

Read the outcome of a batch in two calls: first the batch result summary, then the processed claims, page by page. Both use the batch_erp_id you uploaded with.

2.1 Get Batch Result Summary​

GET /batch/result/{batch_erp_id}

Returns the batch status, whether its claims can be read yet, the number of validation errors, and the batch totals. It works in every status, so you can poll it instead of waiting for the webhook. For a batch with at least one DRG-enabled claim, it also returns drg_summary.

Path Parameters​

ParameterTypeRequiredDescription
batch_erp_id *stringYesThe batch_erp_id of the batch

Example Request​

curl "https://api.{client_namespace}.najeeb.ai/v4.0/health/batch/result/BATCH-2026-11-001" \
-H "access-key: YOUR_API_KEY"

Response (200 OK)​

{
"batch_id": 801230,
"batch_erp_id": "BATCH-2026-11-001",
"status": "PENDING_AUDIT",
"is_result_ready": true,
"failed_reason": null,
"validation_errors_count": 0,
"description": "November 2026 settled claims",
"tags": ["november-2026", "erp-sync"],
"start_date": "2026-11-01T00:00:00.000Z",
"end_date": "2026-11-30T00:00:00.000Z",
"created_at": "2026-12-01T08:15:00.000Z",
"processed_at": "2026-12-01T09:40:00.000Z",
"totals": {
"claims_count": 1200,
"claims_cost": 350000.5,
"claims_items_count": 3340,
"claims_items_vat_amount": 18000.25,
"accepted_claims_items_count": 3100,
"accepted_claims_items_cost": 310000,
"rejected_claims_items_count": 240,
"rejected_claims_items_cost": 40000.5,
"medically_rejected_claims_items_count": 200,
"medically_rejected_claims_items_cost": 33000,
"technically_rejected_claims_items_count": 40,
"technically_rejected_claims_items_cost": 7000.5,
"fraud_claims_count": 0,
"fraud_claims_cost": 0
}
}

Response Fields​

FieldTypeDescription
batch_idnumberNajeeb's ID of the batch
batch_erp_idstringYour ID of the batch
statusenumBatch status. See Batch Flow
is_result_readybooleantrue once the claims can be read, from PENDING_AUDIT onward
failed_reasonstringWhy the batch failed. Set only when status is FAILED, otherwise null
validation_errors_countnumberNumber of validation errors. Read them with Get Validation Errors
description / tagsstring / arrayAs sent with the batch
start_date / end_datestringPeriod covered by the batch (ISO 8601)
created_atstringWhen the batch was stored (ISO 8601)
processed_atstringWhen processing finished (ISO 8601). null until then
totalsobjectBatch totals. Every value is null until the batch is processed. See Totals Object
drg_summaryobjectDRG totals. Present only for a batch with at least one DRG-enabled claim. See Claims Batch DRG Validator: Batch Summary

Totals Object​

FieldTypeDescription
claims_count / claims_costnumberClaims in the batch, and their claimed cost
claims_items_countnumberLines in the batch
claims_items_vat_amountnumberVAT on all lines
accepted_claims_items_count / accepted_claims_items_costnumberAccepted lines and their cost
rejected_claims_items_count / rejected_claims_items_costnumberRejected lines and their cost
medically_rejected_claims_items_count / medically_rejected_claims_items_costnumberLines rejected for a medical reason, and their cost
technically_rejected_claims_items_count / technically_rejected_claims_items_costnumberLines rejected for a technical reason, and their cost
fraud_claims_count / fraud_claims_costnumberClaims flagged as fraud, and their cost

Errors​

Error CodeHTTP StatusDescription
E_BATCH_001404No batch has this batch_erp_id
401 Unauthorized401Missing or invalid access-key

2.2 Get Processed Claims​

GET /batch/result/{batch_erp_id}/claims

Returns the claims of a processed batch. Each claim comes with all of its lines, the decision on every line, the approved quantity and amount, the rejection reasons and, for DRG-enabled claims, the DRG results. The claims can be read from PENDING_AUDIT onward; before that the call answers 409.

Claims come page by page, in a fixed order. To read the whole batch, repeat the call, increasing skip by limit, until skip reaches totalCount.

Query Parameters​

ParameterTypeRequiredDescriptionAccepted Values
limitintegerNoClaims per page1-500. Default 100
skipintegerNoClaims to skip0 or more. Default 0
pageintegerNoPage number, instead of skip. When sent, skip is ignored1 or more
claim_idstringNoReturn only this claimText
drg_statusenumNoReturn only claims whose claimed DRG has this statusGROUPED, UNGROUPABLE, ERROR
drg_matchingenumNoReturn only claims whose billed DRG compares this way with Najeeb's DRGMATCHED, NOT_MATCHED, NOT_SENT, INVALID

Example Request​

curl "https://api.{client_namespace}.najeeb.ai/v4.0/health/batch/result/BATCH-2026-11-001/claims?limit=100&skip=0" \
-H "access-key: YOUR_API_KEY"

Response (200 OK)​

{
"totalCount": 1200,
"data": [
{
"batch_erp_id": "BATCH-2026-11-001",
"claim_id": "CLM-1001",
"status": "PARTIALLY_ACCEPTED",
"issues": [],
"claim_type": "PROFESSIONAL",
"claim_sub_type": "OUT_PATIENT",
"type_of_encounter": "OUTPATIENT",
"claim_date": "2026-11-01T00:00:00.000Z",
"member_id": "MBR-5001",
"provider_cchi_code": "12345",
"policy_no": "POL-2026-01",
"principal_diagnosis_code": "J02.9",
"items": [
{
"issues": [],
"item_erp_id": "CLM-1001-1",
"row_id": 1,
"serial_number": 1,
"status": "ACCEPTED",
"mapped_code": "83600-00-10",
"mapped_description": "Consultation general practitioner",
"nphies_service_code": "83600-00-10",
"nphies_service_description": "Consultation general practitioner",
"provider_service_code": "CONS-GP",
"provider_service_description": "GP Consultation",
"provider_service_type": "CONSULTATION",
"quantity_claimed": 1,
"quantity_approved": 1,
"unit_price": 200,
"agreed_price": null,
"provider_gross_claimed": 200,
"gross_approved": 200,
"discount": 0,
"factor": null,
"deductible": null,
"exceeding_limitation": null,
"vat_amount": 30,
"net_amount_including_vat_amount": 230,
"invoice_number": "INV-9001",
"benefit_code": null,
"sub_benefit_code": null,
"tooth_id": null,
"treatment_date": "2026-11-01T00:00:00.000Z",
"reasons": []
},
{
"issues": [],
"item_erp_id": "CLM-1001-2",
"row_id": 2,
"serial_number": 2,
"status": "REJECTED",
"mapped_code": "73100-00-30",
"mapped_description": "Complete blood count",
"nphies_service_code": "73100-00-30",
"nphies_service_description": "Complete blood count",
"provider_service_code": "LAB-CBC",
"provider_service_description": "CBC",
"provider_service_type": "AMBULATORY",
"quantity_claimed": 1,
"quantity_approved": 0,
"unit_price": 80,
"agreed_price": null,
"provider_gross_claimed": 80,
"gross_approved": 0,
"discount": 0,
"factor": null,
"deductible": null,
"exceeding_limitation": null,
"vat_amount": 0,
"net_amount_including_vat_amount": 0,
"invoice_number": "INV-9001",
"benefit_code": null,
"sub_benefit_code": null,
"tooth_id": null,
"treatment_date": "2026-11-01T00:00:00.000Z",
"reasons": [
{ "code": "MN-1-1", "cause": "The service is not clinically justified by the diagnosis" }
]
}
]
}
]
}
FieldTypeDescription
totalCountnumberClaims of the batch that match the filters
dataarrayOne page of claims. See Claim Result Object

Errors​

Error CodeHTTP StatusDescription
E_BAD_REQUEST_400400limit, skip or page is out of range, or drg_status / drg_matching is not an allowed value
E_BATCH_001404No batch has this batch_erp_id
E_BATCH_005409The results are not ready: the batch is still validating or processing, or it failed or was rejected. details carries the current status
401 Unauthorized401Missing or invalid access-key

Claim Result Object​

The same object is returned for batch claims and for single claims.

FieldTypeDescription
batch_erp_idstringYour ID of the batch. With claim_id it identifies a batch claim. Not sent for a single claim
claim_idstringYour ID of the claim
statusenumClaim status: PENDING, PROCESSING, ACCEPTED, PARTIALLY_ACCEPTED, REJECTED, REFERRED, AUDITING, FURTHER_DETAILS, CANCELLED, OVERWRITTEN
issuesarrayClaim-level notes, alerts and DRG issues. Always present; empty when there is nothing to report. See Issue Object
claim_typeenumClaim Type, or null
claim_sub_typeenumClaim Sub Type
type_of_encounterenumType of Encounter, or null
claim_datestringClaim date (ISO 8601), or null
member_idstringThe member_id you sent
provider_cchi_codestringThe provider CCHI code you sent as provider_cchi_id
policy_nostringPolicy number
principal_diagnosis_codestringThe principal diagnosis you sent as primary_diagnosis_code
itemsarrayEvery line of the claim. See Claim Item Result Object
provider_drg, settled_drg, drgobjectDRG keys. See DRG Results

Claim Item Result Object​

FieldTypeDescription
issuesarrayLine-level issues, e.g. DRG issues about this line. Always present; may be empty
item_erp_idstringThe item_erp_id you sent
row_idnumberThe row_id you sent, or null
serial_numbernumberPosition of the line in the claim
statusenumDecision on the line: PENDING, ACCEPTED, PARTIALLY_ACCEPTED, REJECTED
mapped_code / mapped_descriptionstringService code and description the line was processed with
nphies_service_code / nphies_service_descriptionstringNPHIES service code and description
provider_service_code / provider_service_description / provider_service_typestringThe provider's own service code, description and type
quantity_claimed / quantity_approvednumberQuantity claimed, and quantity approved after the audit
unit_price / agreed_pricenumberUnit price, and the agreed price (null when none)
provider_gross_claimed / gross_approvednumberGross amount claimed (amount_claimed), and gross amount approved after the audit
discount / factor / deductible / exceeding_limitationnumberAs sent
vat_amount / net_amount_including_vat_amountnumberVAT and net amount including VAT
invoice_numberstringInvoice number
benefit_code / sub_benefit_codenumberBenefit and sub-benefit codes
tooth_id / treatment_datestringTooth number (dental) and date of service
reasonsarrayRejection reasons. Empty when the line is accepted. See Reason Object

Reason Object​

FieldTypeDescription
codestringRejection reason code, e.g. MN-1-1
causestringRejection reason text

Issue Object​

The shared shape of every note, warning and error about a claim, a line or a DRG. It is the same object used by the DRG products.

FieldTypeDescription
levelenumERROR, WARNING, INFO
codestringStable issue code, e.g. PROVIDER_DRG_COMPLEXITY_HIGHER
messagestringExplanation for a person
fieldstringThe field the issue is about. Optional
valuestring or numberThe value sent. Optional

DRG Results​

A claim carries three optional DRG keys. They are left out, not null, when they do not apply, so a client that does not use DRG receives the same claim without them.

KeyPresent whenDescribed in
provider_drgA billed DRG was sent or found on a lineClaims Batch DRG Validator: Claim Result
settled_drgA DRG was agreed after reviewClaims Batch DRG Validator: Claim Result
drgThe claim is IN_PATIENT and was sent with drg_enabledClaims Batch DRG Validator: Claim Result

The DRG result fields (najeeb_drg_code, matching and the rest) are shared by every DRG product and described in DRG Coder & Validator: DRG Result Object.

3. CLAIM Webhook (Batch Status)​

Register a webhook with hook_type set to CLAIM using Create Webhook. Najeeb sends a POST every time the status of a batch changes. See Batch Flow for the statuses.

Status update

{
"event_type": "CLAIM",
"data": {
"event": "webHook.pushResultBack",
"batch_id": 801230,
"batch_erp_id": "BATCH-2026-11-001",
"status": "PENDING_AUDIT"
}
}

Validation failed

{
"event_type": "CLAIM",
"data": {
"event": "webHook.pushResultBack",
"batch_id": 801230,
"batch_erp_id": "BATCH-2026-11-001",
"status": "FAILED",
"payload": [
{
"claim_number": "CLM-1002",
"column": "Gender",
"error": "gender must be one of the following values: MALE, FEMALE"
}
]
}
}
FieldTypeDescription
event_typestringAlways CLAIM
data.eventstringAlways webHook.pushResultBack
data.batch_idnumberNajeeb's ID of the batch
data.batch_erp_idstringYour ID of the batch
data.statusenumThe new batch status
data.payloadarrayOnly with FAILED. Validation errors, each with claim_number (the claim's claim_id), column and error. At most 100 errors. Empty when the file had no processable rows
Validation errors are capped in the webhook

The FAILED webhook carries at most 100 validation errors. When a batch has more, the webhook lists only the first 100. Read every error with Get Validation Errors (GET /batch/validation-errors/{batch_erp_id}). validation_errors_count in Get Batch Result Summary gives the total.

4. Single Claim (JSON)​

Send one claim at a time, with its lines nested in items, in the same way as a Prior Authorization request. The claim is validated while you wait, audited by the AI Engine, and the result is pushed to your CLAIM_RESULT webhook.

4.1 Create a Claim​

POST /claim/create

Request Headers​

HeaderTypeRequiredDescription
access-keystringYesYour API key
Content-TypestringYesapplication/json

Query Parameters​

ParameterTypeRequiredDescriptionAccepted Values
use_price_listbooleanNoPrice each item with the price list configured in Najeeb instead of the sent unit_pricetrue, false (default false)
send_patient_historybooleanNoInclude the member's earlier claims in the AI audittrue, false (default false)

Request Body​

The body uses the same keys, types and enums as the CSV columns, with three differences:

CSV (batch)JSON (single claim)
LinesOne row per line, claim-level columns repeatedClaim-level keys once at the root; line-level keys in items[]
Diagnosesprimary_diagnosis_* and pipe-separated secondary_diagnosis_*diagnoses[], one object per diagnosis, as in Prior Authorization
DRGFlat provider_drg_* and DRG columnsdrg_enabled, provider_drg {} and drg_info {}, as in the Pre-auth DRG Coder

Dates are ISO 8601 strings: YYYY-MM-DD or a full date-time. Booleans are JSON true / false.

{
"claim_id": "string (required)",
"authorization_number": "string (optional)",
"transaction_id": "string (optional)",
"claim_type": "Enum Claim Type (optional)",
"claim_sub_type": "Enum Claim Sub Type (required)",
"type_of_encounter": "Enum Type of Encounter (optional)",
"claim_date": "date (required)",
"admission_date": "date (optional)",
"discharge_date": "date (required)",
"admission_code": "string (required)",
"admission_diagnosis": "string (optional)",
"doctor_id": "string (optional)",
"doctor_name": "string (optional)",
"doctor_specialty": "Enum Doctor Specialty (optional)",
"diagnoses": [
  {
    "type": "Enum PRIMARY | SECONDARY (required)",
    "code": "string (required)",
    "name": "string (optional)"
  }
],
"chief_complaints": "string (optional)",
"history_of_present_illness": "string (optional)",
"treatment_plan": "string (optional)",
"significant_signs": "string (optional)",
"general_examination": "string (optional)",
"is_package": "boolean (optional)",
"is_maternity": "boolean (optional)",
"is_new_born": "boolean (optional)",
"provider_cchi_id": "string (required)",
"provider_internal_code": "string (optional)",
"provider_nphies_id": "string (optional)",
"provider_name": "string (optional)",
"provider_type": "Enum Provider Type (optional)",
"provider_city": "string (optional)",
"ph_erp_id": "string (required)",
"policy_holder_name": "string (optional)",
"policy_holder_province": "string (optional)",
"member_id": "string (required)",
"member_name": "string (optional)",
"date_of_birth": "date (required)",
"gender": "Enum Gender (required)",
"marital_status": "Enum Marital Status (optional)",
"nationality": "string (optional)",
"province": "string (optional)",
"phone_number": "string (optional)",
"relation": "Enum Relation (optional)",
"principal_name_or_id": "string (optional)",
"category": "string (optional)",
"network_code": "string (optional)",
"is_vip": "boolean (optional)",
"insurance_addition_date": "date (optional)",
"insurance_start_date": "date (optional)",
"insurance_end_date": "date (optional)",
"member_effective_from": "date (optional)",
"member_effective_to": "date (optional)",
"policy_no": "string (optional)",
"policy_name": "string (optional)",
"policy_group": "string (optional)",
"policy_start_date": "date (optional)",
"policy_end_date": "date (optional)",
"plan_name": "string (optional)",
"plan_type": "Enum Plan Type (optional)",
"drg_enabled": "boolean (optional)",
"provider_drg": {
  "drg_version": "string (optional)",
  "drg_code": "string (required when the object is sent)",
  "drg_weight": "number (optional)"
},
"drg_info": {
  "separation_mode": "string (optional)",
  "leave_days": "number (optional)",
  "length_of_stay": "number (optional)",
  "same_day_flag": "boolean (optional)",
  "admission_weight": "number (optional)",
  "mechanical_ventilation_hours": "number (optional)"
},
"items": 
  {
    "item_erp_id": "string (required)",
    "row_id": "number (optional)",
    "mapped_code": "string (required)",
    "mapped_description": "string (required)",
    "nphies_service_code": "string (optional)",
    "nphies_service_description": "string (optional)",
    "service_type": "Enum [Service Type (required)",
    "provider_service_code": "string (optional)",
    "provider_service_description": "string (optional)",
    "treatment_date": "date (optional)",
    "tooth_id": "string (optional)",
    "unit": "string (optional)",
    "route": "string (optional)",
    "frequency": "Enum Frequency (optional)",
    "directions": "string (optional)",
    "duration": "string (optional)",
    "days_supply": "string (optional)",
    "quantity_claimed": "number (required)",
    "quantity_approved": "number (required)",
    "unit_price": "number (required)",
    "agreed_price": "number (optional)",
    "amount_claimed": "number (required)",
    "amount_approved": "number (required)",
    "discount": "number (required)",
    "factor": "number (optional)",
    "provider_deductible_mount": "number (optional)",
    "exceeding_limitation": "number (optional)",
    "vat_amount": "number (required)",
    "net_amount_including_vat_amount": "number (required)",
    "invoice_number": "string (optional)",
    "benefit_code": "number (optional)",
    "sub_benefit_code": "number (optional)"
  }
]
}

Each key has the meaning, rules and accepted values of the CSV column with the same key in CSV Columns. The JSON-only keys are:

ParameterTypeRequiredDescriptionAccepted Values
diagnoses *arrayYesThe claim's diagnoses. Exactly one has type PRIMARYAt least 1
diagnoses[].type *enumYesDiagnosis typePRIMARY, SECONDARY
diagnoses[].code *stringYesICD-10 codee.g. J18.9
diagnoses[].namestringNoDiagnosis descriptionText
items *arrayYesThe claim's linesAt least 1
provider_drgobjectNoThe DRG the provider billed: drg_version, drg_code, drg_weight. See Pre-auth DRG Coder: Provider DRG ObjectObject
drg_infoobjectNoDRG grouping inputs. Same rules as the DRG columnsObject

Example Request​

curl -X POST "https://api.{client_namespace}.najeeb.ai/v4.0/health/claim/create?send_patient_history=true" \
-H "access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "claim_id": "CLM-1002",
  "authorization_number": "AU-12345",
  "claim_type": "INSTITUTIONAL",
  "claim_sub_type": "IN_PATIENT",
  "type_of_encounter": "HOSPITAL_INPATIENT",
  "claim_date": "2026-11-03",
  "admission_date": "2026-11-03",
  "discharge_date": "2026-11-06",
  "admission_code": "1",
  "diagnoses": [
    { "type": "PRIMARY", "code": "J18.9", "name": "Pneumonia unspecified organism" }
  ],
  "provider_cchi_id": "67890",
  "provider_type": "HOSPITAL",
  "ph_erp_id": "PH-001",
  "policy_no": "POL-2026-01",
  "plan_type": "GROUP_POLICY",
  "member_id": "MBR-5002",
  "date_of_birth": "1992-08-20",
  "gender": "FEMALE",
  "marital_status": "MARRIED",
  "relation": "WIFE",
  "insurance_start_date": "2026-01-01",
  "insurance_end_date": "2026-12-31",
  "drg_enabled": true,
  "provider_drg": { "drg_version": "9", "drg_code": "E62B", "drg_weight": 1.2 },
  "drg_info": { "length_of_stay": 3 },
  "items": [
    {
      "item_erp_id": "CLM-1002-1",
      "mapped_code": "83300-00-10",
      "mapped_description": "Room and board",
      "nphies_service_code": "83300-00-10",
      "nphies_service_description": "Room and board",
      "service_type": "AMBULATORY",
      "treatment_date": "2026-11-03",
      "quantity_claimed": 3,
      "quantity_approved": 3,
      "unit_price": 500,
      "amount_claimed": 1500,
      "amount_approved": 1500,
      "discount": 0,
      "vat_amount": 225,
      "net_amount_including_vat_amount": 1725,
      "invoice_number": "INV-9002"
    },
    {
      "item_erp_id": "CLM-1002-2",
      "mapped_code": "7000000123",
      "mapped_description": "Ceftriaxone 1 g vial",
      "nphies_service_code": "7000000123",
      "nphies_service_description": "Ceftriaxone 1 g vial",
      "service_type": "PHARMACEUTICAL",
      "treatment_date": "2026-11-04",
      "quantity_claimed": 2,
      "quantity_approved": 2,
      "unit_price": 45,
      "amount_claimed": 90,
      "amount_approved": 90,
      "discount": 0,
      "vat_amount": 13.5,
      "net_amount_including_vat_amount": 103.5,
      "invoice_number": "INV-9002"
    }
  ]
}'

Response (201 Created)​

{
"claim_internal_id": 552310,
"claim_id": "CLM-1002",
"code": 201,
"message": "Claim created successfully"
}
FieldTypeDescription
claim_internal_idnumberNajeeb's ID of the claim
claim_idstringYour ID of the claim
codenumber201
messagestringSuccess message
Asynchronous decision

The 201 response confirms that the claim was valid and accepted. The AI audit runs in the background, and the result is pushed to your CLAIM_RESULT webhook.

Errors​

Errors use the v4.0 shape { "ErrorCode": "string", "message": "string", "details": ["string"] }.

Error CodeHTTP StatusDescription
E_BAD_REQUEST_400400A field is missing or invalid. details lists every problem
E_EPH_01404Policy holder not found
E_EMP_01404Medical provider not found
E_EPA_02404Diagnosis not found
E_CLAIM_001409A claim with this claim_id already exists
401 Unauthorized401Missing or invalid access-key

4.2 CLAIM_RESULT Webhook​

Register a webhook with hook_type set to CLAIM_RESULT using Create Webhook. When the AI audit of a single claim finishes, Najeeb sends the full Claim Result Object under data. It is sent again when a reviewer changes the decision in the Najeeb portal.

{
"event_type": "CLAIM_RESULT",
"data": {
"claim_internal_id": 552310,
"claim_id": "CLM-1002",
"status": "ACCEPTED",
"issues": [],
"claim_type": "INSTITUTIONAL",
"claim_sub_type": "IN_PATIENT",
"type_of_encounter": "HOSPITAL_INPATIENT",
"claim_date": "2026-11-03T00:00:00.000Z",
"member_id": "MBR-5002",
"provider_cchi_code": "67890",
"policy_no": "POL-2026-01",
"principal_diagnosis_code": "J18.9",
"provider_drg": { "drg_version": "9", "drg_code": "E62B", "drg_weight": 1.2, "source": "REQUEST", "validity": "VALID" },
"drg": { "mode": "SHADOW", "claimed": { "status": "GROUPED", "drg_result": { "najeeb_drg_code": "E62B", "matching": true } }, "approved": null },
"items": [
{ "item_erp_id": "CLM-1002-1", "status": "ACCEPTED", "quantity_approved": 3, "gross_approved": 1500, "issues": [], "reasons": [] },
{ "item_erp_id": "CLM-1002-2", "status": "ACCEPTED", "quantity_approved": 2, "gross_approved": 90, "issues": [], "reasons": [] }
]
}
}

The example is shortened: every item carries all the fields of the Claim Item Result Object, and drg carries the full calculations described in the Claims Batch DRG Validator.

4.3 Get a Claim Result​

GET /claim/result/{claim_id}

Returns the current Claim Result Object of a single claim, plus claim_internal_id. Use it when a webhook was missed, or to read the result again later.

Error CodeHTTP StatusDescription
E_CLAIM_002404No claim has this claim_id
E_CLAIM_003409The AI audit has not finished. details carries the current status
401 Unauthorized401Missing or invalid access-key

5. Other Batch APIs​

All endpoints below use the Base URL and the access-key header.

5.1 List Batches​

GET /batch/list
ParameterTypeRequiredDescriptionAccepted Values
limitintegerNoBatches per page0 or more. Default 10
skipintegerNoBatches to skip0 or more. Default 0
{
"totalCount": 42,
"batches": [
{
"id": 801230,
"batch_erp_id": "BATCH-2026-11-001",
"start_date": "2026-11-01T00:00:00.000Z",
"end_date": "2026-11-30T00:00:00.000Z",
"mp_status": "CLAIMED",
"insurance_status": "PENDING_AUDIT",
"failed_reason": null,
"description": "November 2026 settled claims",
"created_at": "2026-12-01T08:15:00.000Z"
}
]
}

insurance_status is the batch status (see Batch Flow). mp_status is the medical-provider-side status: CLAIMED, PROCESSING or APPROVED. A 400 (E_BAD_REQUEST_400) is returned when limit or skip is not a whole number of 0 or more.

5.2 Get a Batch​

GET /claim/batch/{batch_erp_id}

Returns the status and totals of one batch. For the validation error count and the per-line decisions, use Batch Results.

{
"id": 801230,
"start_date": "2026-11-01T00:00:00.000Z",
"end_date": "2026-11-30T00:00:00.000Z",
"mp_status": "CLAIMED",
"insurance_status": "PENDING_AUDIT",
"failed_reason": null,
"description": "November 2026 settled claims",
"created_at": "2026-12-01T08:15:00.000Z",
"total_claims_count": 1200,
"total_claims_cost": 350000.5,
"total_accepted_claims_items_count": 3100,
"total_accepted_claims_items_cost": 310000,
"total_rejected_claims_items_count": 240,
"total_rejected_claims_items_cost": 40000.5,
"total_fraud_claims_cost": 0,
"total_fraud_claims_count": 0
}

Errors: 404 E_BATCH_001 when no batch has this batch_erp_id.

5.3 Get Validation Errors​

GET /batch/validation-errors/{batch_erp_id}

Returns every validation error of a batch, oldest first, page by page. A batch without errors returns totalCount 0 and an empty data list. Use it to read the errors beyond the 100 sent in the FAILED webhook.

ParameterTypeRequiredDescriptionAccepted Values
limitintegerNoErrors per page. 0 returns only totalCount0-1000. Default 100
skipintegerNoErrors to skip. Next page = skip + limit0 or more. Default 0
{
"totalCount": 2,
"data": [
{
"claim_id": "CLM-1002",
"item_erp_id": "CLM-1002-1",
"column": "Gender",
"row": 4,
"error": "gender must be one of the following values: MALE, FEMALE"
}
]
}
FieldTypeDescription
claim_idstringClaim ID of the row. null when the error is not tied to a claim
item_erp_idstringItem ERP ID of the row. null when the error is not tied to a row
columnstringThe column the error is on
rownumberRow number in the file
errorstringWhat is wrong with the value

Errors: 400 E_BAD_REQUEST_400 when limit or skip is out of range; 404 E_BATCH_001 when no batch has this batch_erp_id.

5.4 Set the Paid Amount​

PUT /batch/paid-amount/edit/{batch_erp_id}

Records the amount paid for a batch and moves the batch to PAID. The CLAIM webhook is sent with the new status.

ParameterTypeRequiredDescriptionAccepted Values
paid_amount *integerYesAmount paid for the batch, in SAR (request body)Whole number
{ "paid_amount": 1000 }
{
"message": "Batch paid amount updated successfully",
"internal_id": 801230,
"batch_erp_id": "BATCH-2026-11-001",
"code": 200,
"paid_amount": 1000
}

Errors: 400 E_BAD_REQUEST_400 when paid_amount is missing or not a whole number; 404 E_BATCH_001 when no batch has this batch_erp_id.

Error Handling​

Every endpoint answers errors with the v4.0 shape used across Najeeb products:

{
"ErrorCode": "E_BATCH_001",
"message": "Batch not found",
"details": []
}
Error CodeHTTP StatusDescriptionResolution
E_BAD_REQUEST_400400Request validation failed. details lists each problemFix the listed fields
401 Unauthorized401Missing or invalid access-keyCheck your API key
E_BATCH_001404No batch has this batch_erp_idCheck the batch_erp_id
E_BATCH_004413The batch file is larger than 1 GBSplit the file into several batches
E_BATCH_005409The batch results are not ready. details carries the current statusWait for the PENDING_AUDIT webhook, or poll Get Batch Result Summary
E_CLAIM_001409A single claim with this claim_id already existsUse a new claim_id
E_CLAIM_002404No single claim has this claim_idCheck the claim_id
E_CLAIM_003409The single claim's audit has not finishedWait for the CLAIM_RESULT webhook

Errors inside a batch file are not HTTP errors. They are reported per row with the FAILED webhook and Get Validation Errors.

Best Practices​

  1. Register the webhooks first. A batch that fails validation is reported only through the FAILED webhook and the results endpoints.
  2. Start from the sample file. Use the sample batch CSV headers, and check a small batch before uploading a full month.
  3. Use YYYY-MM-DD dates. Avoid slash dates, which can be misread.
  4. Keep claim-level values identical on every row of a claim.
  5. Use stable, anonymized IDs. member_id, doctor_id and principal_name_or_id only need to identify the same person consistently.
  6. Link claims to their prior authorizations with authorization_number or transaction_id.
  7. Read all validation errors with Get Validation Errors when a batch fails. The webhook carries at most 100.
  8. Page through results with limit and skip until you reach totalCount.
  9. Log every upload, webhook delivery and result read, with the batch_erp_id or claim_id.

Next Steps​