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 for | Periodic bulk audits, for example a month of settled claims | Auditing one claim at a time, as soon as it is settled |
| Endpoint | POST /batch/file/upload | POST /claim/create |
| Format | One CSV file, one row per service line | One JSON object per claim, with its lines in items |
| Your reference | batch_erp_id for the batch, claim_id for each claim | claim_id |
| Notification | CLAIM webhook on every batch status change | CLAIM_RESULT webhook with the full result |
| Results | GET /batch/result/{batch_erp_id} and GET /batch/result/{batch_erp_id}/claims | GET /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_numberortransaction_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
- Get your API key and your instance URL from Najeeb. See Authentication.
- 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.
- Register a webhook: use Create Webhook with
hook_typeCLAIMfor batch status updates, andCLAIM_RESULTfor single-claim results.
Batch Flow
After PENDING_AUDIT, the batch moves through the review statuses. Each change is pushed to the CLAIM webhook:
| Status | Meaning | Results readable |
|---|---|---|
VALIDATING | The batch was stored and its rows are being validated | No |
FAILED | Validation found errors, or the file had no processable rows. Nothing was processed | No |
REJECTED | The batch was not sent to the AI Engine | No |
PROCESSING | All rows are valid and the AI Engine is auditing the claims | No |
PENDING_AUDIT | Processing finished. The results are ready | Yes |
AUDITING | The batch was opened for audit | Yes |
AUDIT_COMPLETED | The audit finished | Yes |
SETTLED | The batch was settled | Yes |
PAID | The paid amount was recorded with Set the Paid Amount | Yes |
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
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.
| Field | Kind | Rule |
|---|---|---|
provider_cchi_id | Lookup | CCHI code of a medical provider registered in Najeeb. An unknown code is a validation error |
ph_erp_id | Lookup | ERP ID of a policy holder registered in Najeeb. An unknown ID is a validation error |
mapped_code | Lookup | The service code Najeeb looks the line's service up by |
primary_diagnosis_code, secondary_diagnosis_code | Lookup | ICD-10 codes, looked up in Najeeb's diagnosis list |
network_code | Lookup | Name of a network registered in Najeeb |
authorization_number, transaction_id | Lookup | Must belong to an existing prior authorization in Najeeb. See Linking a Claim to Its Pre-Authorization |
member_id | Stable ID | Any 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_id | Stable ID | Any stable ID. Can be anonymized |
batch_erp_id | Your reference | Your ID of the batch, 1-255 characters. Every batch endpoint uses it |
claim_id | Your reference | Your 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_id | Your reference | Your 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
| Header | Type | Required | Description |
|---|---|---|---|
access-key | string | Yes | Your API key |
Content-Type | string | Yes | multipart/form-data |
Query Parameters
| Parameter | Type | Required | Description | Accepted Values |
|---|---|---|---|---|
use_price_list | boolean | No | Price each line with the price list configured in Najeeb instead of the sent Unit Price | true, false (default false) |
send_patient_history | boolean | No | Include each member's earlier claims in the AI audit | true, false (default false) |
Form Fields
| Field | Type | Required | Description | Accepted Values |
|---|---|---|---|---|
file | file | Yes, unless file_id is sent | The batch CSV file. See CSV File Format | .csv, not empty, at most 1 GB |
file_id | integer | Yes, unless file is sent | ID of a file already stored in Najeeb, used instead of file | Integer |
batch_erp_id * | string | Yes | Your ID of the batch | 1-255 characters |
start_date * | date | Yes | First day covered by the batch. Every Claim Date in the file must fall between start_date and end_date | YYYY-MM-DD |
end_date * | date | Yes | Last day covered by the batch. Must be after start_date | YYYY-MM-DD |
description | string | No | Free text stored with the batch | String |
tags | array | No | Labels stored with the batch | A 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 Code | HTTP Status | Description |
|---|---|---|
E_BAD_REQUEST_400 | 400 | A 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_004 | 413 | The file is larger than 1 GB. Nothing is stored |
401 Unauthorized | 401 | Missing 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
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
| Rule | Detail |
|---|---|
| One row per service line | Each row is one service line (item). Rows that share a Claim ID form one claim |
| Claim-level columns repeat | Claim-level columns (member, provider, policy, diagnoses, dates, DRG) must carry the same value on every row of the claim |
| Header row | Required. It must be within the first 10 lines of the file |
| Header names | Use 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 columns | Ignored |
| Encoding | UTF-8. A byte-order mark (BOM) is allowed |
| Separator and quoting | Comma-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 values | An empty cell is "not sent". A required column must not be empty |
| Dates | Use 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 |
| Numbers | Plain numbers with . as the decimal separator, e.g. 1725.50. No thousands separators or currency symbols |
| Booleans | TRUE or FALSE. Y/N, Yes/No and 1/0 are also accepted |
| Enum values | Upper-case values from Enums, e.g. IN_PATIENT |
| Several diagnoses | Separate them with a pipe, e.g. E11.9 | I10. Descriptions follow the same order |
| Size | At 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 Header | Key | Type | Description | Accepted Values |
|---|---|---|---|---|
Claim ID * | claim_id | string | Your ID of the claim. Rows that share it form one claim | Text, e.g. CLM-1001 |
Claim Type | claim_type | enum | Type of claim | Claim Type |
Claim Sub Type * | claim_sub_type | enum | Sub-type of claim. DRG is calculated for IN_PATIENT claims only | Claim Sub Type |
Type of Encounter | type_of_encounter | enum | Type of encounter | Type of Encounter |
Claim Date * | claim_date | date | Date of the claim. Must fall between the batch's start_date and end_date | Date |
Admission Date | admission_date | date | Admission date. Used for in-patient claims and DRG | Date |
Discharge Date * | discharge_date | date | Discharge date. For an out-patient claim, use the claim date | Date |
Admission Code * | admission_code | string | Admission code | Text, e.g. 1 |
Admission Diagnosis | admission_diagnosis | string | Admission diagnosis description | Text |
Doctor
| CSV Header | Key | Type | Description | Accepted Values |
|---|---|---|---|---|
Unique Physician ID | doctor_id | string | Stable ID of the treating doctor. Can be anonymized | Text |
Doctor Name | doctor_name | string | Doctor name | Text |
Doctor Specialty | doctor_specialty | enum | Doctor's specialty | Doctor Specialty |
Diagnoses
| CSV Header | Key | Type | Description | Accepted Values |
|---|---|---|---|---|
Principal Diagnosis Code * | primary_diagnosis_code | string | Principal diagnosis | ICD-10 code, e.g. J18.9 |
Principal Diagnosis Description | primary_diagnosis_description | string | Principal diagnosis description | Text |
Additional Diagnoses Code | secondary_diagnosis_code | string | Secondary diagnoses | ICD-10 codes separated by |, e.g. E11.9 | I10 |
Additional Diagnoses | secondary_diagnosis_description | string | Secondary diagnosis descriptions, in the same order as the codes | Text separated by | |
Clinical Information
| CSV Header | Key | Type | Description | Accepted Values |
|---|---|---|---|---|
Chief Complaints | chief_complaints | string | Chief complaints | Text |
History of Present Illness | history_of_present_illness | string | History of present illness | Text |
Treatment Plan | treatment_plan | string | Treatment plan | Text |
Significant Signs | significant_signs | string | Significant signs | Text |
General Examination | general_examination | string | General examination findings | Text |
Is Package | is_package | boolean | The claim is a package | Boolean |
Maternity Cover | is_maternity | boolean | Maternity case | Boolean |
Newborn | is_new_born | boolean | Newborn case | Boolean |
Medical Provider
| CSV Header | Key | Type | Description | Accepted Values |
|---|---|---|---|---|
Provider CCHI Code * | provider_cchi_id | string | CCHI code of the provider. Must be registered in Najeeb | Text |
Provider Internal Code | provider_internal_code | string | Your internal provider code | Text |
Provider Nphies ID | provider_nphies_id | string | Provider NPHIES ID | Text |
Provider Name | provider_name | string | Provider name | Text |
Provider Type | provider_type | enum | Type of provider | Provider Type |
Provider City | provider_city | string | Provider city | Text |
Policy Holder and Pre-Authorization
| CSV Header | Key | Type | Description | Accepted Values |
|---|---|---|---|---|
Policy Holder ID * | ph_erp_id | string | ERP ID of the policy holder. Must be registered in Najeeb | Text |
Policy holder Name | policy_holder_name | string | Policy holder name | Text |
Policy Holder Province | policy_holder_province | string | Policy holder province | Text |
Pre-authorization Number | authorization_number | string | Authorization number of the prior authorization that covered this claim | Text, e.g. AU-12345 |
Transaction ID | transaction_id | string | transaction_id of the prior authorization that covered this claim | Text, 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_idmust belong to thatauthorization_number.
The old header ar_erp_id is still read as authorization_number, but new integrations should not use it.
Member
| CSV Header | Key | Type | Description | Accepted Values |
|---|---|---|---|---|
Member ID * | member_id | string | Stable ID of the member. Can be anonymized | Text |
Member Name | member_name | string | Member name. Optional; leave it empty to keep claims anonymous | Text |
Date of Birth * | date_of_birth | date | Member date of birth. Najeeb calculates the age from it | Date |
Gender * | gender | enum | Member gender | Gender |
Marital Status | marital_status | enum | Member marital status | Marital Status |
Nationality | nationality | string | Nationality | Text, e.g. Saudi |
Province | province | string | Member province | Text, e.g. Riyadh |
Mobile | phone_number | string | Member mobile number | Text |
Relation | relation | enum | Relation to the principal member | Relation |
Principal Name or ID | principal_name_or_id | string | Stable ID of the principal member. Can be anonymized | Text |
Category | category | string | The member's class (category). The old header Class is still read | Text |
Network Code | network_code | string | The member's network, by name. Must exist in Najeeb | Text, up to 255 characters |
Is VIP | is_vip | boolean | VIP member | Boolean |
Insurance Addition Date | insurance_addition_date | date | Date the member was added to the insurance | Date |
Insurance Start Date | insurance_start_date | date | Start of the member's insurance | Date |
Insurance End Date | insurance_end_date | date | End of the member's insurance | Date |
Member Effective From | member_effective_from | date | Start of the member's cover on the policy. When empty, Insurance Start Date is used | Date |
Member Effective To | member_effective_to | date | End of the member's cover on the policy. Not before Member Effective From. When empty, Insurance End Date is used | Date |
Policy
| CSV Header | Key | Type | Description | Accepted Values |
|---|---|---|---|---|
Policy Number | policy_no | string | Policy number | Text, e.g. POL-2026-01 |
Policy Name | policy_name | string | Policy name | Text |
Policy Group | policy_group | string | Policy group | Text |
Policy Start Date | policy_start_date | date | Policy start date. When empty, Insurance Start Date is used | Date |
Policy End Date | policy_end_date | date | Policy end date. Not before Policy Start Date. When empty, Insurance End Date is used | Date |
Plan Name | plan_name | string | Plan name | Text |
Plan Type | plan_type | enum | Plan type | Plan 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 Header | Key | Description |
|---|---|---|
DRG Enabled | drg_enabled | TRUE calculates the DRG of this claim. One TRUE row enables the whole claim |
Provider DRG Version | provider_drg_version | AR-DRG version of the billed DRG. Default 9 |
Provider DRG Code | provider_drg_code | The DRG the provider billed, e.g. E62B |
Provider DRG Weight | provider_drg_weight | Relative weight of the billed DRG |
Separation Mode | separation_mode | Mode of separation, 01 to 09 |
Leave Days | leave_days | Leave days within the stay |
Length of Stay | length_of_stay | Length of stay in days |
Same Day Flag | same_day_flag | Same-day episode |
Admission Weight (g) | admission_weight | Admission weight in grams, for patients under one year |
Ventilation Hours | mechanical_ventilation_hours | Hours of mechanical ventilation |
Line-Level Columns
These can differ on every row.
Line Identity
| CSV Header | Key | Type | Description | Accepted Values |
|---|---|---|---|---|
Item ERP ID * | item_erp_id | string | Your ID of the line. Returned with its validation errors and its result | Text, 1-255 characters |
Row ID | row_id | integer | Your row number. Returned in the result | Whole number |
Service
| CSV Header | Key | Type | Description | Accepted Values |
|---|---|---|---|---|
Mapped Code * | mapped_code | string | The 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 account | Text, e.g. 83600-00-10 |
Mapped Description * | mapped_description | string | Description of the mapped service | Text |
NPHIES Service Code | nphies_service_code | string | NPHIES service code. Recommended: DRG grouping reads procedures from it | Text, e.g. 38306-00-00 |
NPHIES Service Description | nphies_service_description | string | NPHIES service description | Text |
Service Type * | service_type | enum | Service category | Service Type |
Provider Service Code | provider_service_code | string | The provider's own service code | Text |
Provider Service Description | provider_service_description | string | The provider's own service description | Text |
Treatment Date | treatment_date | date | Date the service was delivered | Date |
Tooth ID | tooth_id | string | Tooth number, for dental lines | Text |
Unit | unit | string | Unit of measure, for drugs | Text, e.g. mg |
Route | route | string | Route of administration | Text, e.g. Oral |
Frequency | frequency | enum | Frequency of administration | Frequency |
Directions | directions | string | Directions of use | Text |
Duration | duration | string | Duration of treatment | Text, e.g. 5 days |
Days Supply | days_supply | string | Days of supply, for pharmacy lines | Text |
Quantities and Amounts
All amounts are in SAR.
| CSV Header | Key | Type | Description | Accepted Values |
|---|---|---|---|---|
Quantity Claimed * | quantity_claimed | number | Quantity claimed by the provider | Number |
Quantity Approved * | quantity_approved | number | Quantity approved in your adjudication | Number |
Unit Price * | unit_price | number | Price per unit | Number |
Agreed Price | agreed_price | number | Contracted price per unit, when different from Unit Price | Number |
Provider Gross Claimed * | amount_claimed | number | Gross amount claimed by the provider | Number |
Gross Approved * | amount_approved | number | Gross amount approved in your adjudication | Number |
Discount * | discount | number | Discount | Number. 0 when none |
Factor | factor | number | Pricing factor | Number |
Deductible | provider_deductible_mount | number | Deductible | Number |
Exceeding Limitation | exceeding_limitation | number | Amount above the benefit limit | Number |
VAT Amount * | vat_amount | number | VAT on the approved amount | Number. 0 when none |
Net Amount Including VAT Amount * | net_amount_including_vat_amount | number | Approved amount plus VAT | Number |
Invoice Number | invoice_number | string | Invoice number | Text |
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 Header | Key | Type | Description | Accepted Values |
|---|---|---|---|---|
Benefit Code | benefit_code | integer | Benefit code | Whole number |
Sub-Benefit Code | sub_benefit_code | integer | Sub-benefit code | Whole number |
1.4 Enums
Enum values are the same in the CSV file and in JSON.
Claim Type
| Value | Description |
|---|---|
INSTITUTIONAL | Institutional (hospital) services |
PROFESSIONAL | Professional (clinic) services |
PHARMACY | Pharmacy services |
DENTAL | Dental services |
OPTICAL | Optical services |
Claim Sub Type
| Value | Description |
|---|---|
IN_PATIENT | In-patient |
OUT_PATIENT | Out-patient |
EMERGENCY | Emergency |
Type of Encounter
| Value | Description |
|---|---|
HOSPITAL_INPATIENT | Hospital in-patient |
DAY_CASE | Day case |
EMERGENCY | Emergency |
OUTPATIENT | Out-patient |
HOME_HEALTH_CARE | Home health care |
PRIMARY_HEALTH_CARE | Primary health care |
Provider Type
| Value | Description |
|---|---|
CLINIC | Clinic |
POLYCLINIC | Polyclinic |
DENTAL_CLINIC | Dental clinic |
HOSPITAL | Hospital |
PHARMACY | Pharmacy |
PHYSIOTHERAPY | Physiotherapy center |
LABS | Laboratory |
OPTICAL_CENTER | Optical center |
AMBULANCE_SERVICES | Ambulance services |
ONE_DAY_SURGERY_CENTER | One-day surgery center |
Plan Type
| Value | Description |
|---|---|
SME_POLICY | SME policy |
SME_AGGREGATOR_POLICY | SME aggregator policy |
GROUP_POLICY | Group policy |
TOURISM_VISA_POLICY | Tourism visa policy |
PREMIUM_VISA_POLICY | Premium visa policy |
DOMESTIC_WORKER_POLICY | Domestic worker policy |
VISITOR_VISA_POLICY | Visitor visa policy |
VISITOR_VISA_EXTEND_POLICY | Visitor visa extension policy |
Plan Type also accepts the value written with spaces or hyphens, e.g. GROUP POLICY or group-policy.
Service Type
| Value | Description |
|---|---|
AMBULATORY | Ambulatory service |
CONSULTATION | Consultation |
PHARMACEUTICAL | Drug |
DEVICE | Medical device |
OPTICAL | Optical |
DENTAL | Dental |
BABY_FORMULA | Baby formula |
UNLISTED | Unlisted service |
Frequency
| Value | Description |
|---|---|
OD | Once daily |
QD | Once daily |
Q24H | Every 24 hours |
BID | Twice daily |
Q12H | Every 12 hours |
TID | Three times daily |
Q8H | Every 8 hours |
QID | Four times daily |
Q6H | Every 6 hours |
Q4H | Every 4 hours |
QOD | Every other day |
QM | Monthly |
Gender
| Value | Description |
|---|---|
MALE | Male |
FEMALE | Female |
Marital Status
| Value | Description |
|---|---|
SINGLE | Single |
MARRIED | Married |
ENGAGED | Engaged |
UNKNOWN | Unknown |
WIDOWED | Widowed |
DIVORCED | Divorced |
SEPARATED | Separated |
Relation
| Value | Description |
|---|---|
SELF | The member is the principal |
FATHER | Father |
MOTHER | Mother |
SON | Son |
DAUGHTER | Daughter |
SISTER | Sister |
HUSBAND | Husband |
WIFE | Wife |
WIFE_WITHOUT_MATERNITY | Wife without maternity cover |
MOTHER_MB | Mother (maternity benefit) |
SENIOR_EMPLOYEE | Senior employee |
FEMALE_EMPLOYEE_WITH_MAT | Female employee with maternity cover |
CHILD | Child |
SPOUSE | Spouse |
EMPLOYEE | Employee |
OTHER | Other |
Doctor Specialty
| Value | Value | Value |
|---|---|---|
ALTERNATIVE_MEDICINE | GENERAL_SURGERY | PEDIATRIC_HEMATO_ONCOLOGY |
ANESTHESIOLOGY | HEMATO_ONCOLOGY | PEDIATRIC_NEPHROLOGY |
CARDIOLOGY | INFECTIOUS_DISEASES | PEDIATRIC_NEUROLOGY |
CARDIOVASCULAR_AND_THORACIC_SURGERY | INTENSIVIST | PEDIATRIC_PULMONOLOGY |
COLON_AND_RECTAL_SURGERY | INTERNAL_MEDICINE | PEDIATRIC_SURGERY |
DENTIST | LAB_SPECIALIST | PEDIATRICS |
DERMATOLOGY | MEDICAL_GENETICS | PHARMACIST |
EAR_NOSE_AND_THROAT | NEPHROLOGY | PHYSICAL_MEDICINE_AND_REHABILITATION |
EMERGENCY_DEPARTMENT | NEUROLOGY | PLASTIC_SURGERY |
ENDOCRINOLOGY_AND_METABOLISM | NEUROSURGERY | PREVENTIVE_MEDICINE |
FORENSIC_MEDICINE | NUCLEAR_MEDICINE | PSYCHIATRIST |
GASTROENTEROLOGY | NURSE | PULMONOLOGY |
GENERAL_PHYSICIAN | NUTRITION | RADIATION_ONCOLOGY |
OBSTETRICS_AND_GYNECOLOGY | ONCOLOGIST | RADIOLOGIST |
ONCOLOGY_SURGERY | OPHTHALMOLOGY | RHEUMATOLOGY |
ORTHOPEDIC_SURGERY | ORTHOTICS_AND_PROSTHETICS | SPORTS_MEDICINE |
PATHOLOGY | PEDIATRIC_CARDIOLOGY | UROLOGY |
PEDIATRIC_ENDOCRINOLOGY | PEDIATRIC_GASTROENTEROLOGY | VASCULAR_SURGERY |
OTHER |
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
| Parameter | Type | Required | Description |
|---|---|---|---|
batch_erp_id * | string | Yes | The 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
| Field | Type | Description |
|---|---|---|
batch_id | number | Najeeb's ID of the batch |
batch_erp_id | string | Your ID of the batch |
status | enum | Batch status. See Batch Flow |
is_result_ready | boolean | true once the claims can be read, from PENDING_AUDIT onward |
failed_reason | string | Why the batch failed. Set only when status is FAILED, otherwise null |
validation_errors_count | number | Number of validation errors. Read them with Get Validation Errors |
description / tags | string / array | As sent with the batch |
start_date / end_date | string | Period covered by the batch (ISO 8601) |
created_at | string | When the batch was stored (ISO 8601) |
processed_at | string | When processing finished (ISO 8601). null until then |
totals | object | Batch totals. Every value is null until the batch is processed. See Totals Object |
drg_summary | object | DRG totals. Present only for a batch with at least one DRG-enabled claim. See Claims Batch DRG Validator: Batch Summary |
Totals Object
| Field | Type | Description |
|---|---|---|
claims_count / claims_cost | number | Claims in the batch, and their claimed cost |
claims_items_count | number | Lines in the batch |
claims_items_vat_amount | number | VAT on all lines |
accepted_claims_items_count / accepted_claims_items_cost | number | Accepted lines and their cost |
rejected_claims_items_count / rejected_claims_items_cost | number | Rejected lines and their cost |
medically_rejected_claims_items_count / medically_rejected_claims_items_cost | number | Lines rejected for a medical reason, and their cost |
technically_rejected_claims_items_count / technically_rejected_claims_items_cost | number | Lines rejected for a technical reason, and their cost |
fraud_claims_count / fraud_claims_cost | number | Claims flagged as fraud, and their cost |
Errors
| Error Code | HTTP Status | Description |
|---|---|---|
E_BATCH_001 | 404 | No batch has this batch_erp_id |
401 Unauthorized | 401 | Missing 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
| Parameter | Type | Required | Description | Accepted Values |
|---|---|---|---|---|
limit | integer | No | Claims per page | 1-500. Default 100 |
skip | integer | No | Claims to skip | 0 or more. Default 0 |
page | integer | No | Page number, instead of skip. When sent, skip is ignored | 1 or more |
claim_id | string | No | Return only this claim | Text |
drg_status | enum | No | Return only claims whose claimed DRG has this status | GROUPED, UNGROUPABLE, ERROR |
drg_matching | enum | No | Return only claims whose billed DRG compares this way with Najeeb's DRG | MATCHED, 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" }
]
}
]
}
]
}
| Field | Type | Description |
|---|---|---|
totalCount | number | Claims of the batch that match the filters |
data | array | One page of claims. See Claim Result Object |
Errors
| Error Code | HTTP Status | Description |
|---|---|---|
E_BAD_REQUEST_400 | 400 | limit, skip or page is out of range, or drg_status / drg_matching is not an allowed value |
E_BATCH_001 | 404 | No batch has this batch_erp_id |
E_BATCH_005 | 409 | The results are not ready: the batch is still validating or processing, or it failed or was rejected. details carries the current status |
401 Unauthorized | 401 | Missing or invalid access-key |
Claim Result Object
The same object is returned for batch claims and for single claims.
| Field | Type | Description |
|---|---|---|
batch_erp_id | string | Your ID of the batch. With claim_id it identifies a batch claim. Not sent for a single claim |
claim_id | string | Your ID of the claim |
status | enum | Claim status: PENDING, PROCESSING, ACCEPTED, PARTIALLY_ACCEPTED, REJECTED, REFERRED, AUDITING, FURTHER_DETAILS, CANCELLED, OVERWRITTEN |
issues | array | Claim-level notes, alerts and DRG issues. Always present; empty when there is nothing to report. See Issue Object |
claim_type | enum | Claim Type, or null |
claim_sub_type | enum | Claim Sub Type |
type_of_encounter | enum | Type of Encounter, or null |
claim_date | string | Claim date (ISO 8601), or null |
member_id | string | The member_id you sent |
provider_cchi_code | string | The provider CCHI code you sent as provider_cchi_id |
policy_no | string | Policy number |
principal_diagnosis_code | string | The principal diagnosis you sent as primary_diagnosis_code |
items | array | Every line of the claim. See Claim Item Result Object |
provider_drg, settled_drg, drg | object | DRG keys. See DRG Results |
Claim Item Result Object
| Field | Type | Description |
|---|---|---|
issues | array | Line-level issues, e.g. DRG issues about this line. Always present; may be empty |
item_erp_id | string | The item_erp_id you sent |
row_id | number | The row_id you sent, or null |
serial_number | number | Position of the line in the claim |
status | enum | Decision on the line: PENDING, ACCEPTED, PARTIALLY_ACCEPTED, REJECTED |
mapped_code / mapped_description | string | Service code and description the line was processed with |
nphies_service_code / nphies_service_description | string | NPHIES service code and description |
provider_service_code / provider_service_description / provider_service_type | string | The provider's own service code, description and type |
quantity_claimed / quantity_approved | number | Quantity claimed, and quantity approved after the audit |
unit_price / agreed_price | number | Unit price, and the agreed price (null when none) |
provider_gross_claimed / gross_approved | number | Gross amount claimed (amount_claimed), and gross amount approved after the audit |
discount / factor / deductible / exceeding_limitation | number | As sent |
vat_amount / net_amount_including_vat_amount | number | VAT and net amount including VAT |
invoice_number | string | Invoice number |
benefit_code / sub_benefit_code | number | Benefit and sub-benefit codes |
tooth_id / treatment_date | string | Tooth number (dental) and date of service |
reasons | array | Rejection reasons. Empty when the line is accepted. See Reason Object |
Reason Object
| Field | Type | Description |
|---|---|---|
code | string | Rejection reason code, e.g. MN-1-1 |
cause | string | Rejection 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.
| Field | Type | Description |
|---|---|---|
level | enum | ERROR, WARNING, INFO |
code | string | Stable issue code, e.g. PROVIDER_DRG_COMPLEXITY_HIGHER |
message | string | Explanation for a person |
field | string | The field the issue is about. Optional |
value | string or number | The 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.
| Key | Present when | Described in |
|---|---|---|
provider_drg | A billed DRG was sent or found on a line | Claims Batch DRG Validator: Claim Result |
settled_drg | A DRG was agreed after review | Claims Batch DRG Validator: Claim Result |
drg | The claim is IN_PATIENT and was sent with drg_enabled | Claims 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"
}
]
}
}
| Field | Type | Description |
|---|---|---|
event_type | string | Always CLAIM |
data.event | string | Always webHook.pushResultBack |
data.batch_id | number | Najeeb's ID of the batch |
data.batch_erp_id | string | Your ID of the batch |
data.status | enum | The new batch status |
data.payload | array | Only 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 |
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
| Header | Type | Required | Description |
|---|---|---|---|
access-key | string | Yes | Your API key |
Content-Type | string | Yes | application/json |
Query Parameters
| Parameter | Type | Required | Description | Accepted Values |
|---|---|---|---|---|
use_price_list | boolean | No | Price each item with the price list configured in Najeeb instead of the sent unit_price | true, false (default false) |
send_patient_history | boolean | No | Include the member's earlier claims in the AI audit | true, 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) | |
|---|---|---|
| Lines | One row per line, claim-level columns repeated | Claim-level keys once at the root; line-level keys in items[] |
| Diagnoses | primary_diagnosis_* and pipe-separated secondary_diagnosis_* | diagnoses[], one object per diagnosis, as in Prior Authorization |
| DRG | Flat provider_drg_* and DRG columns | drg_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:
| Parameter | Type | Required | Description | Accepted Values |
|---|---|---|---|---|
diagnoses * | array | Yes | The claim's diagnoses. Exactly one has type PRIMARY | At least 1 |
diagnoses[].type * | enum | Yes | Diagnosis type | PRIMARY, SECONDARY |
diagnoses[].code * | string | Yes | ICD-10 code | e.g. J18.9 |
diagnoses[].name | string | No | Diagnosis description | Text |
items * | array | Yes | The claim's lines | At least 1 |
provider_drg | object | No | The DRG the provider billed: drg_version, drg_code, drg_weight. See Pre-auth DRG Coder: Provider DRG Object | Object |
drg_info | object | No | DRG grouping inputs. Same rules as the DRG columns | Object |
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"
}
| Field | Type | Description |
|---|---|---|
claim_internal_id | number | Najeeb's ID of the claim |
claim_id | string | Your ID of the claim |
code | number | 201 |
message | string | Success message |
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 Code | HTTP Status | Description |
|---|---|---|
E_BAD_REQUEST_400 | 400 | A field is missing or invalid. details lists every problem |
E_EPH_01 | 404 | Policy holder not found |
E_EMP_01 | 404 | Medical provider not found |
E_EPA_02 | 404 | Diagnosis not found |
E_CLAIM_001 | 409 | A claim with this claim_id already exists |
401 Unauthorized | 401 | Missing 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 Code | HTTP Status | Description |
|---|---|---|
E_CLAIM_002 | 404 | No claim has this claim_id |
E_CLAIM_003 | 409 | The AI audit has not finished. details carries the current status |
401 Unauthorized | 401 | Missing 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
| Parameter | Type | Required | Description | Accepted Values |
|---|---|---|---|---|
limit | integer | No | Batches per page | 0 or more. Default 10 |
skip | integer | No | Batches to skip | 0 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.
| Parameter | Type | Required | Description | Accepted Values |
|---|---|---|---|---|
limit | integer | No | Errors per page. 0 returns only totalCount | 0-1000. Default 100 |
skip | integer | No | Errors to skip. Next page = skip + limit | 0 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"
}
]
}
| Field | Type | Description |
|---|---|---|
claim_id | string | Claim ID of the row. null when the error is not tied to a claim |
item_erp_id | string | Item ERP ID of the row. null when the error is not tied to a row |
column | string | The column the error is on |
row | number | Row number in the file |
error | string | What 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.
| Parameter | Type | Required | Description | Accepted Values |
|---|---|---|---|---|
paid_amount * | integer | Yes | Amount 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 Code | HTTP Status | Description | Resolution |
|---|---|---|---|
E_BAD_REQUEST_400 | 400 | Request validation failed. details lists each problem | Fix the listed fields |
401 Unauthorized | 401 | Missing or invalid access-key | Check your API key |
E_BATCH_001 | 404 | No batch has this batch_erp_id | Check the batch_erp_id |
E_BATCH_004 | 413 | The batch file is larger than 1 GB | Split the file into several batches |
E_BATCH_005 | 409 | The batch results are not ready. details carries the current status | Wait for the PENDING_AUDIT webhook, or poll Get Batch Result Summary |
E_CLAIM_001 | 409 | A single claim with this claim_id already exists | Use a new claim_id |
E_CLAIM_002 | 404 | No single claim has this claim_id | Check the claim_id |
E_CLAIM_003 | 409 | The single claim's audit has not finished | Wait 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
- Register the webhooks first. A batch that fails validation is reported only through the
FAILEDwebhook and the results endpoints. - Start from the sample file. Use the sample batch CSV headers, and check a small batch before uploading a full month.
- Use
YYYY-MM-DDdates. Avoid slash dates, which can be misread. - Keep claim-level values identical on every row of a claim.
- Use stable, anonymized IDs.
member_id,doctor_idandprincipal_name_or_idonly need to identify the same person consistently. - Link claims to their prior authorizations with
authorization_numberortransaction_id. - Read all validation errors with Get Validation Errors when a batch fails. The webhook carries at most 100.
- Page through results with
limitandskipuntil you reachtotalCount. - Log every upload, webhook delivery and result read, with the
batch_erp_idorclaim_id.
Next Steps
- Claims Batch DRG Validator: DRG coding of in-patient claims
- Prior Authorization: the pre-service request that claims link back to
- Webhook: register and manage webhook endpoints
- Authentication Guide: set up the
access-key