Prior Authorization / Standard
Najeeb Prior Authorization is a comprehensive pre-authorization processing solution designed to streamline and automate the pre-authorization workflow for insurance companies in the Kingdom of Saudi Arabia.
This service enables the utilization of the AI Engine capabilities without having to store any sensitive data outside the Insurance Company Network, as all the data submitted is processed ephemerally.
Service Description
Najeeb Prior Authorization provides a seamless API integration that enables insurance companies to submit pre-authorization requests from their core systems and receive processed results. The service handles the entire pre-authorization lifecycle, from initial request submission to AI-powered adjudication, with all processing happening ephemerally within your dedicated, isolated Najeeb instance.
Key Features
- AI-Powered Adjudication: Leverage Najeeb's AI Engine for intelligent pre-authorization processing
- Ephemeral Data Processing: All data is processed temporarily and securely within your isolated Najeeb instance
- Comprehensive Validation: Built-in validation for diagnoses, medical providers, policies, and benefits
- Policy Business Logic: Configurable policy validation including member enrollment, network, and benefit checks
- Patient History: Optional patient history retrieval for more accurate decisions
- Encounter Details: Full encounter tracking for inpatient and outpatient services
- Supporting Information: Attach clinical supporting information (vital signs, lab results, etc.)
- DRG Coding: optionally calculate the claimed and approved AR-DRGs of inpatient requests, check the provider's DRG, and record the settled DRG, with the Pre-auth DRG Coder (
drg_enabled) - KSA Compliance: Fully compliant with Saudi healthcare and pharmaceutical regulations
- Scalable Architecture: Handles high volumes of requests with reliable performance
How It Works
- Request Submission: Your core system sends a pre-authorization request to the Najeeb API
- Processing: The request is processed within your isolated Najeeb instance with ephemeral data handling
- Validation: Automated validation of diagnoses, provider credentials, policy, and member information
- AI Analysis: The request is sent to the AI Engine for intelligent adjudication
- Response: An acknowledgment is returned with the internal ID and authorization number. The final decision is delivered asynchronously via your configured webhook
Requirements Prior to Integration
Before integrating with Najeeb Prior Authorization, ensure you have the following:
A. Technical Requirements
- API Access Credentials
- Valid API key (
access-key) provided by Najeeb - Access to your dedicated Najeeb instance endpoint
- Network connectivity to the Najeeb API infrastructure
- Data Synchronization Prerequisites
The typical integration flow follows a logical sequence of data setup before transactional operations can begin.
Refer to the Integration Interfaces documentation for detailed API endpoints to create and manage each of these entities.
Before creating a pre-authorization request, ensure all related entities data has been synchronized with your Najeeb instance. The following entities must exist in the system to process requests without errors:
- Policy Holder — must be created first as the parent entity for policies
- Policy — must be linked to the policy holder, with category, benefits, and sub-benefits configured
- Member — must be registered and assigned to the policy
- Medical Provider — the provider's CCHI number must be registered in the system
Failure to sync any of these entities will result in 404 Not Found errors (e.g., E_EPH_01, E_EPA_014, E_EMP_01, E_EPA_015) when submitting a pre-authorization request. See the Error Codes table for the full list.
B. Providing Reference Data Lists
To ensure accurate processing, the following reference data lists should be shared with the Najeeb technical team before going live:
-
Medical Providers (preferred) — a list of medical providers including their names and CCHI codes. While providers can be created via the Medical Provider API, sharing the list in advance enables the Najeeb team to pre-load provider data for reporting and validation purposes.History Processing
-
Policy Categories (Classes) — A coded list of category descriptions ranked by order of importance (priority). These categories are assigned to members upon policy enrollment and are used during claims adjudication to determine applicable benefits and coverage rules.
-
Benefits and Sub-Benefits (preferred) — a complete list of benefit codes and descriptions, along with their sub-benefit codes and descriptions. These are used during policy template configuration and item-level validation. If not provided in advance, you should include
benefit_descriptionandsub_benefit_descriptionin each item of the pre-authorization request so that Najeeb can auto-create the records.
Providing these lists upfront reduces integration friction and avoids runtime errors caused by missing reference data. Contact the Najeeb support team to coordinate the data exchange.
If a member already exists in the system, the existing record will be retained — no duplicate will be created and no overwrite will occur.
To activate member history:
1- you must include "with_patient_history": true in create pre-auth payload.
2- you must update the preauth with the doctor's decision, using the "Auditor Synch Prior Authorization API".z
transaction_idis the primary idempotency key and must be unique per request; a duplicate value returns a conflict error.authorization_numberis not required to be unique; it can be reused across follow-up requests related to the same authorization.
Integration Guide
The Najeeb Prior Authorization integration is accomplished through a single API endpoint that receives a pre-authorization request from your insurance company core system. All data processing is ephemeral and handled entirely within your isolated Najeeb instance.
The Prior Authorization create endpoint processes requests asynchronously. The API returns an acknowledgment with the internal ID immediately. The Najeeb AI Engine then processes the request, and the final decision is delivered via your configured webhook endpoint.
Base URL
https://api.{client_namespace}.najeeb.ai/v4.0/health
Authentication
All API requests are authenticated using an API key passed in a dedicated header:
access-key: YOUR_API_KEY
For access key provisioning, please contact Najeeb support.
API Endpoint
Create Prior Authorization Request
POST /approval-request/create
This endpoint receives a pre-authorization request from your core system and processes it within your isolated Najeeb instance.
Request Headers
| Header | Type | Required | Description |
|---|---|---|---|
access-key | string | Yes | API key for authentication |
Content-Type | string | Yes | Must be application/json |
Request Body Parameters
The request body is a JSON object with the following structure:
{
"authorization_number": "string",
"transaction_id": "string",
"policy_no": "string",
"ph_erp_id": "string",
"related_authorization_number": "string",
"related_request_date": "date",
"referred_authorization_number": "string",
"is_referred": "boolean",
"medical_provider_cchi_no": "string",
"member_id": "string",
"member_dob": "string",
"member_gender": "Enum Member Gender",
"marital_status": "Enum Marital Status",
"visit_type": "Enum Visit Type",
"request_date": "string",
"claim_type": "Enum Claim Type",
"claim_sub_type": "Enum Claim Sub Type",
"is_emergency": "boolean",
"is_maternity": "boolean",
"is_new_born": "boolean",
"is_referral": "boolean",
"referral_cchi_code": "string",
"referral_valid_days": "number",
"hcp_appointed_flag": "boolean",
"hcp_appointed_as_referred": "boolean",
"hcp_moh_flag": "boolean",
"is_declaration_requested": "boolean",
"is_declaration_clean": "boolean",
"declared_diagnoses": ["string"],
"declaration_attachment": {
"type": "Enum Attachment Type",
"value": "string",
"file_name": "string"
},
"doctor_check": "Enum [Doctor Check"],
"advanced_preauth": "boolean",
"advanced_preauth_status": "Enum Advanced Prior Authorization Status",
"with_patient_history": "boolean",
"diagnoses":
{
"type": "Enum [Diagnosis Type",
"code": "string",
"name": "string"
}
],
"items": [
{
"claimed_quantity": "number",
"claimed_amount": "number",
"agreed_price": "number",
"provider_deductible_amount": "number",
"service_code": "string",
"service_description": "string",
"nphies_code": "string",
"nphies_type": "PHARMACEUTICAL",
"service_type": "PHARMACEUTICAL",
"benefit_code": "number",
"benefit_description": "string",
"sub_benefit_code": "number",
"sub_benefit_description": "string",
"duration": "string",
"frequency": "OD",
"treatment_date": "string",
"justification": "string",
"erp_item_id": "string",
"related_diagnosis_codes": ["string"],
"reason_code": "string",
"tooth_id": "string",
"serial_number": "string",
"nphies_description": "string"
}
],
"doctor_id": "string",
"doctor_speciality": "string",
"doctor_name": "string",
"approval_remarks": "string",
"referral_remarks": "string",
"additional_remarks": "string",
"internal_referral_notes": "string",
"internal_notes": "string",
"currency": "string",
"currency_rate": "number",
"nphies_bundle_id": "string",
"provider_system_id": "string",
"provider_comment": "string",
"erp_user_id": "string",
"price_list_level": "string",
"period_start_date": "string",
"encounter_id": "string",
"encounter_status": "string",
"encounter_class": "string",
"encounter_priority": "string",
"encounter_start_date": "string",
"encounter_end_date": "string",
"encounter_arrival_code": "string",
"encounter_department": "string",
"encounter_triage_category": "string",
"encounter_triage_date": "string",
"encounter_death_cause": "string",
"encounter_admit_source": "string",
"encounter_length_of_stay": "string",
"encounter_admission": "string",
"encounter_discharge": "string",
"supporting_info": [
{
"sequence_number": "number",
"type": "string",
"code": "string",
"value": "string",
"file_name": "string",
"unit": "string",
"start_date": "string",
"end_date": "string",
"value_url": "string",
"related_erp_item_ids": ["string"]
}
],
"drg_enabled": "boolean",
"provider_drg": {
"drg_version": "string",
"drg_code": "string",
"drg_weight": "number"
},
"drg_info": {
"separation_mode": "Enum Separation Mode",
"leave_days": "number",
"length_of_stay": "number",
"same_day_flag": "boolean",
"admission_weight": "number",
"mechanical_ventilation_hours": "number"
},
"retry": "boolean"
}Parameter Details
Root Level Parameters
| Parameter | Type | Required | Description | Accepted Values |
|---|---|---|---|---|
authorization_number * | string | Yes | The authorization number of the prior authorization. It can repeat across requests: a new request (new transaction_id) that reuses an existing authorization_number supersedes the earlier request(s), which are marked OVERWRITTEN | Alphanumeric string, 1-255 characters |
transaction_id * | string | Yes | Unique transaction ID for this request (idempotency key). A duplicate value returns 409 E_EPA_069 | Alphanumeric string, 1-255 characters |
retry | boolean | No | When true, re-runs AI processing for the existing request identified by transaction_id instead of creating a new one. The body is still validated in full. Returns 200 (see Retry Response); an unknown transaction_id returns 404 E_EPA_064 | true, false (default: false) |
policy_no * | string | Yes | The policy number of the prior authorization | Alphanumeric string, 1-255 characters |
ph_erp_id * | string | Yes | The ERP ID of the policy holder. | String, 1-255 characters |
related_authorization_number | string | No | The related authorization number for follow-up requests | Alphanumeric string, max 255 characters |
related_request_date | date | No | Request date of the related request (related_authorization_number). Shown in the portal and the prior authorization export; not used in AI processing | ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ |
referred_authorization_number | string | No | The referred authorization number | Alphanumeric string, max 255 characters |
is_referred | boolean | No | Flag indicating the request is a referred request from a previous one. When true, all items must include reason_code. Please compare with is_referral | |
true, false | ||||
internal_referral_notes | string | No | Internal referral notes | Alphanumeric, max 255 characters |
internal_notes | string | No | Internal notes | Alphanumeric, max 255 characters |
medical_provider_cchi_no * | string | Yes | The CCHI number of the medical provider | Alphanumeric string, 1-255 characters |
member_id * | string | Yes | The member ID of the prior authorization | Alphanumeric string, 1-255 characters |
member_dob * | string | Yes | Member date of birth | ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ |
member_gender * | Enum | Yes | The gender of the member | Enum: MALE, FEMALE |
marital_status * | Enum | Yes | The marital status of the member | Enum: SINGLE, MARRIED, ENGAGED, UNKNOWN, WIDOWED, DIVORCED, SEPARATED |
visit_type | Enum | No | The visit type of the prior authorization | Enum: NEW_VISIT, FOLLOW_UP, REFILL, WALK_IN, REFERRAL |
request_date * | date | Yes | The request date of the prior authorization | ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ |
claim_type * | Enum | Yes | The claim type of the prior authorization | Enum: INSTITUTIONAL, PROFESSIONAL, PHARMACY, DENTAL, OPTICAL |
claim_sub_type * | Enum | Yes | The claim sub type of the prior authorization | Enum: IN_PATIENT, OUT_PATIENT, EMERGENCY |
is_emergency | boolean | No | Flag indicating an emergency case | true, false |
is_maternity | boolean | No | Flag indicating a maternity case | true, false |
is_new_born | boolean | No | Flag indicating a newborn case | true, false |
is_referral | boolean | No | Flag indicating the member is requested to be referred to another provider. When true and referral_cchi_code is sent, the request is linked to that referral provider. Please compare with is_referred | true, false |
referral_cchi_code | string | No | CCHI code of the referral provider. Used only when is_referral is true: the request is linked to this provider as a referral. An unknown code is rejected with 404 MEDICAL_PROVIDER_NOT_FOUND and nothing is created | Alphanumeric string, max 255 characters |
referral_valid_days | number | No | Referral validity in days, used in AI processing. When is_referral is true and referral_cchi_code is sent, it is also stored as the referral's valid days (0 when absent) | Integer, minimum 0 |
hcp_appointed_flag | boolean | No | Flag indicating the healthcare provider is appointed to the member | true, false |
hcp_appointed_as_referred | boolean | No | Flag indicating the provider was appointed to the member based on a doctor's referral request (also covers acute medications dispensed at outside pharmacies). Used in AI processing | true, false (default: false) |
hcp_moh_flag | boolean | No | Flag indicating the healthcare provider is registered in the Ministry of Health. | true, false |
is_declaration_requested | boolean | No | Flag indicating a health declaration was requested from the member. When true, the AI applies the declaration check for pre-existing conditions that were not disclosed | true, false (default: false) |
is_declaration_clean | boolean | No | Flag indicating the member's declaration is clean. Evaluated only when is_declaration_requested is true | true, false (default: false) |
declared_diagnoses | array | No | ICD-10 codes the member declared on the health declaration, independent of diagnoses. Each code must exist in the diagnosis table; an unknown code returns 404 and nothing is created. An empty list or a missing key means none | Array of unique strings, max 255 characters each |
declaration_attachment | object | No | The member's health-declaration document. You can submit files in one of two ways: as a Base64-encoded string, or via a file URL accessible by our server. Null or missing means none | Object: see Declaration Attachment Object |
doctor_check | array | No | Doctor manual checks are populated after the doctor reviews the request. This field should be provided in Create Preauth only if the request is advanced; otherwise, it should be supplied in Update Preauth whenever available. Doctor checks are used for AI processing based on historical requests. An empty list or a missing key both mean none, and unknown or repeated values return 400. | Array of Doctor Check values: CHRONIC, CONGENITAL, RTA, WORK_RELATED, VACCINATION, PSYCHIATRIC, CHECKUP, INFERTILITY, PREGNANCY |
advanced_preauth | boolean | No | Flag indicating advanced pre-authorization. For advanced preauth, all services must come with predefined reason codes. | true, false |
advanced_preauth_status | Enum | Conditional | Required when advanced_preauth is true | Enum: ACCEPTED, REJECTED |
with_patient_history | boolean | No | Include the member's history in AI processing: previously accepted and partially accepted prior authorizations within the look-back window (365 days by default) ending at the treatment date of the first item. Must be true for history to be processed | true, false (default: false) |
period_start_date | date | No | The period start date of the prior authorization | ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ |
diagnoses * | array | Yes | Array of diagnosis objects | A single primary diagnosis is required |
items * | array | Yes | Array of item objects | Minimum one item is required |
doctor_id | string | No | The doctor ID | Alphanumeric string, 1-255 characters |
doctor_speciality | string | No | The doctor's medical specialty | String, 1-255 characters |
doctor_name | string | No | The doctor's name | String, 1-255 characters |
approval_remarks | string | No | Doctor's remarks for prior authorization | Free text, 1-255 characters |
referral_remarks | string | No | Doctor's remarks for referral request | Free text, 1-255 characters |
additional_remarks | string | No | Doctor's additional remarks or notes | Free text, 1-255 characters |
currency | string | No | Currency code | String, 1-255 characters |
currency_rate | number | No | Currency exchange rate | Decimal, minimum 0 |
nphies_bundle_id | string | No | The NPHIES bundle ID | Alphanumeric string, 1-255 characters |
provider_system_id | string | No | Provider system identifier | Alphanumeric string, 1-255 characters |
provider_comment | string | No | Provider comments | Free text, 1-255 characters |
erp_user_id | string | No | The ERP user ID who requested the preauth | Alphanumeric string, 1-255 characters |
price_list_level | string | No | The price list level | String, 1-255 characters |
supporting_info | array | No | Array of supporting information objects | See Supporting Info Object |
drg_enabled | boolean | No | Calculate the claimed and approved AR-DRGs of this request with the Pre-auth DRG Coder. Runs only when claim_sub_type is IN_PATIENT and the Pre-auth DRG Coder is enabled for your account. Never rejects or delays the request. Added with the DRG release | true, false (default). null is false |
provider_drg | object | No | The DRG the provider billed. Stored even without drg_enabled. A DRG billed as an item is also found: see Provider DRG on an item. Added with the DRG release | See DRG Reference Object |
drg_info | object | No | DRG grouping inputs. Used only when drg_enabled is true. Added with the DRG release | See DRG Info Object |
Encounter Parameters
| Parameter | Type | Required | Description | Accepted Values |
|---|---|---|---|---|
encounter_id | string | No | Encounter identifier | Alphanumeric string, 1-255 characters |
encounter_status | string | No | Encounter status | String, 1-255 characters |
encounter_class | string | No | Encounter class | String, 1-255 characters |
encounter_priority | string | No | Encounter priority | String, 1-255 characters |
encounter_start_date | date | No | Encounter start date | ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ |
encounter_end_date | date | No | Encounter end date | ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ |
encounter_arrival_code | string | No | Encounter arrival code | Alphanumeric string, 1-255 characters |
encounter_department | string | No | Encounter department | String, 1-255 characters |
encounter_triage_category | string | No | Encounter triage category | String, 1-255 characters |
encounter_triage_date | date | No | Encounter triage date | ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ |
encounter_death_cause | string | No | Encounter death cause | String, 1-255 characters |
encounter_admit_source | string | No | Encounter admit source | String, 1-255 characters |
encounter_length_of_stay | string | No | Encounter length of stay | String, 1-255 characters |
encounter_admission | string | No | Encounter admission details | String, 1-255 characters |
encounter_discharge | string | No | Encounter discharge details | String, 1-255 characters |
When drg_enabled is true and claim_sub_type is IN_PATIENT, send encounter_start_date and encounter_end_date: they are the admission and separation dates the DRG is calculated from. Without them the request is still accepted and processed, but it is not DRG-coded (drg.status ERROR, issue E_DRG_003). encounter_length_of_stay is free text and is not used for DRG coding. See Pre-auth DRG Coder.
Diagnosis Object
| Parameter | Type | Required | Description | Accepted Values |
|---|---|---|---|---|
type * | Enum | Yes | Type of diagnosis | Enum: PRIMARY, SECONDARY |
code * | string | Yes | ICD-10 diagnosis code. Items reference it through related_diagnosis_codes | Valid ICD-10 code format |
name | string | No | Diagnosis name/description | String |
Item Object
| Parameter | Type | Required | Description | Accepted Values |
|---|---|---|---|---|
service_code * | string | Yes | Service code of the item | Alphanumeric string, max 255 characters |
service_description * | string | Yes | Service description of the item | String, max 255 characters |
nphies_code * | string | Yes | NPHIES code of the item | Alphanumeric string, max 255 characters |
nphies_type * | string | Yes | NPHIES type of the item | String, max 255 characters |
service_type * | string | Yes | Service type of the item | String, max 255 characters |
claimed_quantity * | number | Yes | Quantity of the item | Decimal, minimum 0 |
claimed_amount * | number | Yes | Claimed amount/price of the item | Decimal |
agreed_price | number | No | Agreed unit price of the item when available, used in AI processing. Without a price list configured by Najeeb, each item is capped at agreed_price as the maximum allowed to be requested from the provider. Send null if undefined (default); sending "0" means it conflicts with the provider contract and is not equivalent to null. | Decimal |
provider_deductible_amount | number | No | Provider deductible amount | Decimal, minimum 0 |
nphies_description | string | No | NPHIES description of the item | String, max 255 characters |
duration | string | No | Duration of the item | Free text, max 255 characters |
frequency | string | No | Frequency of the item | Free text (for example OD, BID, TID) |
treatment_date | date | No | Treatment date of the item. | ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ |
justification | string | No | Medical justification for the item | Free text, max 255 characters |
erp_item_id | string | No | ERP item ID of the item. Supporting information references it through related_erp_item_ids | Alphanumeric string, max 255 characters |
related_diagnosis_codes | array | No | Codes of the diagnoses this item relates to, used in AI processing. Every code must be a diagnoses[].code of the same request, otherwise the request is rejected with 400 | Array of unique strings, max 255 characters each |
reason_code | string | Conditional | reason_code string Conditional — Should be null in standard requests. Required when is_referred or advanced_preauth is true. A non-empty value prevents the Najeeb engine from processing the current request. | Alphanumeric string, max 255 characters |
benefit_code | number | No | Benefit code of the item | Integer, |
benefit_description | string | No | Benefit description. Used to auto-create the benefit if the code does not exist in the system | String, max 255 characters |
sub_benefit_code | number | No | Sub benefit code of the item | Integer, |
sub_benefit_description | string | No | Sub-benefit description. Used to auto-create the sub-benefit if the code does not exist in the system | String, max 255 characters |
tooth_id | string | No | Tooth identifier (for dental services) | Alphanumeric string, max 255 characters |
serial_number | string | No | Serial number of the item | Alphanumeric string, max 255 characters |
If benefits and sub-benefits lists have not been provided by the client to the Najeeb team in advance, you must include benefit_description and sub_benefit_description alongside the corresponding codes. Najeeb will use these descriptions to auto-create the benefit or sub-benefit records when the codes do not yet exist in the system.
Supporting Info Object
| Parameter | Type | Required | Description | Accepted Values |
|---|---|---|---|---|
sequence_number | number | No | Sequence number for ordering | Integer, minimum 1 |
type | string | No | Type of supporting information. Use ATTACHMENT to upload a file in value | String, max 255 characters |
code | string | No | Supporting information code | See Supporting Info Code |
value | string | No | Value of the supporting information. When type is ATTACHMENT, send the base64-encoded file content (a data URL is also accepted); the file is stored and its URL is saved instead | String |
file_name | string | No | Original file name when type is ATTACHMENT, used to infer the file extension | String, max 255 characters |
unit | string | No | Unit of measurement | String, max 50 characters |
start_date | date | No | Start date of the information | ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ |
end_date | date | No | End date of the information | ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ |
value_url | string | No | URL to supporting document | Valid HTTP/HTTPS URL, max 500 characters |
related_erp_item_ids | array | No | ERP item IDs of the items this supporting information relates to, used in AI processing. Every ID must be an items[].erp_item_id of the same request, otherwise the request is rejected with 400 | Array of unique strings, max 255 characters each |
Declaration Attachment Object
| Parameter | Type | Required | Description | Accepted Values |
|---|---|---|---|---|
type * | Enum | Yes | How value is read | Enum: BASE64, URL |
value * | string | Yes | Base64 file content (bare, or as a data: URL) when type is BASE64; the file URL when type is URL. Invalid base64 or an empty file returns 400 | String, non-empty |
file_name * | string | Yes | File name shown in the portal and exports. For BASE64, an extension is added from the content when it has none | String, max 255 characters |
Enums
Visit Type Enum:
NEW_VISIT- New visitFOLLOW_UP- Follow-up visitREFILL- RefillWALK_IN- Walk-in visitREFERRAL- Referral visit
Member Gender Enum:
MALE- MaleFEMALE- Female
Marital Status Enum:
SINGLE- SingleMARRIED- MarriedENGAGED- EngagedUNKNOWN- UnknownWIDOWED- WidowedDIVORCED- DivorcedSEPARATED- Separated
Claim Type Enum:
INSTITUTIONAL- Institutional services for inpatientsPROFESSIONAL- Professional services for outpatientsPHARMACY- Pharmacy servicesDENTAL- Dental servicesOPTICAL- Optical services
Claim Sub Type Enum:
IN_PATIENT- Inpatient servicesOUT_PATIENT- Outpatient servicesEMERGENCY- Emergency services
Diagnosis Type Enum (lower-case values are also accepted):
PRIMARY- Primary diagnosisSECONDARY- Secondary diagnosis
Advanced Prior Authorization Status Enum:
ACCEPTED- Advanced pre-authorization acceptedREJECTED- Advanced pre-authorization rejected
Doctor Check Enum (doctor_check):
CHRONIC- Chronic conditionCONGENITAL- Congenital conditionRTA- Road traffic accidentWORK_RELATED- Work-related injury or conditionVACCINATION- VaccinationPSYCHIATRIC- Psychiatric conditionCHECKUP- Check-upINFERTILITY- InfertilityPREGNANCY- Pregnancy
Supporting Info Code (supporting_info[].code):
Always send the code in upper-case:
| Code |
|---|
INFO |
ONSET |
ATTACHMENT |
MISSING_TOOTH |
EMPLOYMENT_IMPACTED |
LAB_TEST |
REASON_FOR_VISIT |
DAYS_SUPPLY |
VITAL_SIGN_WEIGHT |
VITAL_SIGN_SYSTOLIC |
VITAL_SIGN_DIASTOLIC |
ICU_HOURS |
VENTILATION_HOURS |
VITAL_SIGN_HEIGHT |
CHIEF_COMPLAINT |
CHIEF_COMPLAINTS |
BIRTH_WEIGHT |
TEMPERATURE |
PULSE |
OXYGEN_SATURATION |
RESPIRATORY_RATE |
MORPHOLOGY |
LAST_MENSTRUAL_PERIOD |
TREATMENT_PLAN |
PATIENT_HISTORY |
PHYSICAL_EXAMINATION |
HISTORY_OF_PRESENT_ILLNESS |
ADMISSION_WEIGHT |
ESTIMATED_LENGTH_OF_STAY |
INVESTIGATION_RESULT |
SIGNIFICANT_SIGNS |
GENERAL_EXAMINATION |
VITAL_INFORMATION |
OTHER |
Example Request
curl -X POST "https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/create" \
-H "access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"authorization_number": "AU-12345",
"transaction_id": "550e8400-e29b-41d4-a716-446655440001",
"policy_no": "no-01",
"ph_erp_id": "UAT-policy-id-01",
"medical_provider_cchi_no": "22697412",
"member_id": "uat-a-002",
"member_dob": "1990-01-15T00:00:00.000Z",
"member_gender": "Enum Member Gender",
"marital_status": "Enum Marital Status",
"visit_type": "Enum Visit Type",
"request_date": "2024-02-15T10:04:20.346Z",
"claim_type": "Enum Claim Type",
"claim_sub_type": "Enum Claim Sub Type",
"is_emergency": false,
"is_maternity": false,
"is_new_born": false,
"diagnoses":
{
"type": "Enum [Diagnosis Type",
"code": "E40",
"name": "Kwashiorkor"
},
{
"type": "Enum Diagnosis Type",
"code": "Z24",
"name": "Need for immunisation against certain single viral diseases"
}
],
"items": [
{
"claimed_quantity": 1,
"claimed_amount": 100,
"treatment_date": "2024-02-15T10:00:00.000Z",
"provider_deductible_amount": 0,
"service_code": "FMCARS0008",
"service_description": "Pharmacological Stress Echocardiography",
"nphies_code": "55113-00-00",
"nphies_type": "UNMAPPED CATEGORY",
"service_type": "UNMAPPED CATEGORY",
"justification": "Patient requires cardiac assessment",
"erp_item_id": "ITEM-001",
"related_diagnosis_codes": ["E40"]
}
],
"doctor_id": "1",
"doctor_speciality": "Cardiology",
"doctor_name": "Dr. Ahmed",
"approval_remarks": "This is a test prior authorization",
"additional_remarks": "Patient requires cardiac evaluation",
"currency": "SAR",
"currency_rate": 1,
"provider_system_id": "Provider System ID",
"provider_comment": "Provider Comment",
"encounter_status": "active",
"encounter_class": "outpatient",
"encounter_department": "Cardiology",
"supporting_info": [
{
"sequence_number": 1,
"type": "MEDICAL_RECORD",
"code": "VITAL_SIGN_SYSTOLIC",
"value": "120",
"unit": "mmHg",
"related_erp_item_ids": ["ITEM-001"]
}
]
}'Response
Success Response (201 Created)
{
"approval_request_internal_id": "number",
"authorization_number": "string",
"transaction_id": "string",
"code": 201,
"message": "Approval request created successfully"
}
Response Fields
| Field | Type | Description |
|---|---|---|
approval_request_internal_id | number | Internal identifier assigned to the request |
authorization_number | string | The authorization number assigned to the request |
transaction_id | string | Echoes the submitted transaction ID |
code | number | HTTP status code (201) |
message | string | Success message |
Example Success Response
{
"approval_request_internal_id": 12345,
"authorization_number": "AU-12345",
"transaction_id": "550e8400-e29b-41d4-a716-446655440001",
"code": 201,
"message": "Approval request created successfully"
}
Retry Response (200 OK)
Returned when the request is sent with "retry": true for an existing transaction_id.
{
"approval_request_internal_id": 12345,
"authorization_number": "AU-12345",
"transaction_id": "550e8400-e29b-41d4-a716-446655440001",
"code": 200,
"message": "Pipeline retry initiated successfully"
}
The success response confirms the request has been accepted for processing. The AI Engine will process the request asynchronously, and the final decision (approval, rejection, or partial approval) will be delivered via your configured webhook endpoint.
Error Responses
Error Response Structure
{
"ErrorCode": "string",
"message": "string",
"details": ["string"]
}
Error Codes
| Error Code | HTTP Status | Description |
|---|---|---|
E_BAD_REQUEST_400 | 400 | Request validation failed — see the details array for field-level errors |
E_EPH_01 | 404 | Policy holder not found |
E_EPA_014 | 404 | Policy not found |
E_EPA_015 | 404 | Network not found |
E_EPA_02 | 404 | Diagnosis not found |
E_EBA_01 | 404 | Benefit not found |
E_EBA_02 | 404 | Sub benefit not found |
E_EPA_01 | 404 | Patient not found |
E_EMP_01 | 404 | Medical provider not found |
E_EPA_021 | 422 | Patient not joined to policy |
E_EPA_069 | 409 | A prior authorization already exists with this transaction_id |
E_EPA_064 | 404 | retry is true but no prior authorization exists with this transaction_id |
MEDICAL_PROVIDER_NOT_FOUND | 404 | is_referral is true and referral_cchi_code does not match a medical provider; nothing is created |
401 Unauthorized | 401 | Missing or invalid access-key |
Example Error Responses
Bad Request:
{
"ErrorCode": "E_BAD_REQUEST_400",
"message": "Bad request",
"details": [
"member_gender must be one of the following values: MALE, FEMALE"
]
}
Unknown In-Request Reference:
{
"ErrorCode": "E_BAD_REQUEST_400",
"message": "Bad request",
"details": [
"items[0].related_diagnosis_codes[0] (Z99) must match a diagnoses[].code of the same request",
"supporting_info[0].related_erp_item_ids[0] (ITEM-404) must match an items[].erp_item_id of the same request"
]
}
Referral Provider Not Found:
{
"ErrorCode": "MEDICAL_PROVIDER_NOT_FOUND",
"message": "Medical provider with CCHI code 10000000 not found",
"details": []
}
Diagnosis Not Found:
{
"ErrorCode": "E_EPA_02",
"message": "Diagnosis not found, The codes of the diagnosis are:[Z99]",
"details": []
}
Policy Holder Not Found:
{
"ErrorCode": "E_EPH_01",
"message": "Policy holder not found",
"details": []
}
Policy Not Found:
{
"ErrorCode": "E_EPA_014",
"message": "Policy not found",
"details": []
}
Medical Provider Not Found:
{
"ErrorCode": "E_EMP_01",
"message": "Medical provider not found, The identifier of the medical provider is: 99999",
"details": []
}
Patient Not Joined to Policy:
{
"ErrorCode": "E_EPA_021",
"message": "Patient not joined to policy",
"details": []
}
Duplicate Transaction ID:
{
"ErrorCode": "E_EPA_069",
"message": "Approval request already exists with this transaction_id: 550e8400-e29b-41d4-a716-446655440001",
"details": []
}
Unauthorized:
{
"ErrorCode": "API key is required",
"message": "Unauthorized",
"details": []
}
Data Processing
All data processing is ephemeral, meaning:
- Data is processed temporarily within your isolated Najeeb instance
- No persistent storage of request data (except for audit logs)
- Data is securely handled and encrypted in transit
- Compliance with KSA data protection regulations
Best Practices
- Date Formats: Use ISO 8601 format with timezone for all date fields (e.g.,
2024-01-15T10:04:20.346Z). All date fields must include the full datetime with timezone — date-only values will be rejected. - Diagnoses: A single primary diagnosis is required to support the requested services. You may also send one or multiple secondary diagnoses.
- Items: Ensure all required item fields are provided, especially
service_code,service_description,nphies_code,nphies_type,service_type,claimed_quantity, andclaimed_amount - Referred Requests: When
is_referredistrue, every item must include a non-emptyreason_code - Error Handling: Implement retry logic with exponential backoff for transient errors
- Validation: Validate data before sending requests to avoid unnecessary API calls
- Monitoring: Monitor response times and error rates
- Logging: Log all requests and responses for audit and debugging purposes
- Timeout Configuration: Set your HTTP client timeout to 50 seconds to accommodate processing time.
- Supporting Info: Include relevant supporting information (vital signs, lab results, clinical notes) when available to improve AI decision accuracy
- Retry: Use the
retryflag to re-trigger AI processing for an existing request instead of creating a duplicate - In-Request References:
items[].related_diagnosis_codesmust point to codes sent indiagnoses, andsupporting_info[].related_erp_item_idsmust point toerp_item_idvalues sent initems; senderp_item_idon every item you want to reference - Treatment Date: Send
treatment_dateon every item. The first item's treatment date is used as the request's treatment date: patient history is evaluated against it and it is returned astreatment_dateinPRE_AUTH_RESULT
Code Examples
- cURL
- JavaScript
- Python
curl -X POST "https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/create" \
-H "access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"authorization_number": "AU-12345",
"transaction_id": "550e8400-e29b-41d4-a716-446655440001",
"policy_no": "no-01",
"ph_erp_id": "UAT-policy-id-01",
"medical_provider_cchi_no": "22697412",
"member_id": "uat-a-002",
"member_dob": "1990-01-15T00:00:00.000Z",
"member_gender": "Enum Member Gender",
"marital_status": "Enum Marital Status",
"visit_type": "Enum Visit Type",
"request_date": "2024-02-15T10:04:20.346Z",
"claim_type": "Enum Claim Type",
"claim_sub_type": "Enum Claim Sub Type",
"diagnoses":
{
"type": "Enum [Diagnosis Type",
"code": "E40",
"name": "Kwashiorkor"
},
{
"type": "Enum Diagnosis Type",
"code": "Z24",
"name": "Need for immunisation against certain single viral diseases"
}
],
"items": [
{
"claimed_quantity": 1,
"claimed_amount": 100,
"treatment_date": "2024-02-15T10:00:00.000Z",
"provider_deductible_amount": 0,
"service_code": "FMCARS0008",
"service_description": "Pharmacological Stress Echocardiography",
"nphies_code": "55113-00-00",
"nphies_type": "UNMAPPED CATEGORY",
"service_type": "UNMAPPED CATEGORY",
"justification": "Patient requires cardiac assessment"
}
],
"doctor_speciality": "Cardiology",
"doctor_name": "Dr. Ahmed",
"approval_remarks": "This is a test prior authorization",
"currency": "SAR",
"currency_rate": 1,
"provider_system_id": "Provider System ID",
"provider_comment": "Provider Comment"
}'const response = await fetch('https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/create', {
method: 'POST',
headers: {
'access-key': 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
authorization_number: 'AU-12345',
transaction_id: '550e8400-e29b-41d4-a716-446655440001',
policy_no: 'no-01',
ph_erp_id: 'UAT-policy-id-01',
medical_provider_cchi_no: '22697412',
member_id: 'uat-a-002',
member_dob: '1990-01-15T00:00:00.000Z',
member_gender: 'MALE',
marital_status: 'SINGLE',
visit_type: 'NEW_VISIT',
request_date: '2024-02-15T10:04:20.346Z',
claim_type: 'PROFESSIONAL',
claim_sub_type: 'OUT_PATIENT',
diagnoses: [
{ type: 'PRIMARY', code: 'E40', name: 'Kwashiorkor' },
{ type: 'SECONDARY', code: 'Z24', name: 'Need for immunisation against certain single viral diseases' },
],
items: [
{
claimed_quantity: 1,
claimed_amount: 100,
treatment_date: '2024-02-15T10:00:00.000Z',
provider_deductible_amount: 0,
service_code: 'FMCARS0008',
service_description: 'Pharmacological Stress Echocardiography',
nphies_code: '55113-00-00',
nphies_type: 'UNMAPPED CATEGORY',
service_type: 'UNMAPPED CATEGORY',
justification: 'Patient requires cardiac assessment',
},
],
doctor_speciality: 'Cardiology',
doctor_name: 'Dr. Ahmed',
approval_remarks: 'This is a test prior authorization',
currency: 'SAR',
currency_rate: 1,
provider_system_id: 'Provider System ID',
provider_comment: 'Provider Comment',
}),
});
const result = await response.json();
console.log(result);
import requests
response = requests.post(
'https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/create',
headers={
'access-key': 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
json={
'authorization_number': 'AU-12345',
'transaction_id': '550e8400-e29b-41d4-a716-446655440001',
'policy_no': 'no-01',
'ph_erp_id': 'UAT-policy-id-01',
'medical_provider_cchi_no': '22697412',
'member_id': 'uat-a-002',
'member_dob': '1990-01-15T00:00:00.000Z',
'member_gender': 'MALE',
'marital_status': 'SINGLE',
'visit_type': 'NEW_VISIT',
'request_date': '2024-02-15T10:04:20.346Z',
'claim_type': 'PROFESSIONAL',
'claim_sub_type': 'OUT_PATIENT',
'diagnoses': [
{'type': 'PRIMARY', 'code': 'E40', 'name': 'Kwashiorkor'},
{'type': 'SECONDARY', 'code': 'Z24', 'name': 'Need for immunisation against certain single viral diseases'},
],
'items': [
{
'claimed_quantity': 1,
'claimed_amount': 100,
'treatment_date': '2024-02-15T10:00:00.000Z',
'provider_deductible_amount': 0,
'service_code': 'FMCARS0008',
'service_description': 'Pharmacological Stress Echocardiography',
'nphies_code': '55113-00-00',
'nphies_type': 'UNMAPPED CATEGORY',
'service_type': 'UNMAPPED CATEGORY',
'justification': 'Patient requires cardiac assessment',
},
],
'doctor_speciality': 'Cardiology',
'doctor_name': 'Dr. Ahmed',
'approval_remarks': 'This is a test prior authorization',
'currency': 'SAR',
'currency_rate': 1,
'provider_system_id': 'Provider System ID',
'provider_comment': 'Provider Comment',
},
)
result = response.json()
print(result)
Webhook Response (Najeeb Decision Result)
After the Najeeb Engine finishes processing a prior authorization request, Najeeb delivers the decision to your configured webhook endpoint as an HTTP POST. This is the asynchronous response referenced in the Integration Guide.
To receive the Najeeb decision, register a webhook with hook_type set to PRE_AUTH_RESULT. See Webhook for registration details.
When It Is Sent
The PRE_AUTH_RESULT webhook is sent in two cases. The payload shape is the same; the values differ as follows.
| After AI processing | After a reviewer decision in the Najeeb portal | |
|---|---|---|
| When | The AI Engine finishes processing the request, including after a retry | A reviewer submits the decision for the request in the Najeeb portal |
status | The AI decision for the request (ACCEPTED, PARTIALLY_ACCEPTED or REJECTED). Falls back to the request status while no AI decision exists | The reviewer's final status for the request |
items_decisions[].decision | The AI decision for the item. An item sent on create with a predefined reason_code keeps its own decision | The reviewer's status for the item |
items_decisions[].status | Same value as decision | null |
| Automation fields | Set by the automation rules (see Automation Fields) | is_request_automated and is_item_automated are false; both notes are null |
reason_code | The item's reasons whose source is enabled for push in your instance settings. Reasons sent on create with a predefined reason_code are returned unchanged when that setting is enabled | All reasons of the item |
By default the payload is wrapped in an envelope: event_type (always PRE_AUTH_RESULT) at the root and the result under data. A webhook configured with the flat response type receives the data object only. Contact Najeeb support to change the response type.
Response Payload Structure
The example below is a result sent after AI processing: the first item was accepted and automated, the second was rejected and needs review, so the request is not automated.
{
"event_type": "PRE_AUTH_RESULT",
"data": {
"pre_auth_internal_id": 161081,
"transaction_id": "550e8400-e29b-41d4-a716-446655440001",
"authorization_number": "AU-12345",
"nphies_reopen_at": null,
"nphies_reopen_reason": null,
"submitter_erp_id": null,
"approval_remarks": "This is a test prior authorization",
"referral_remarks": null,
"internal_referral_notes": null,
"is_referred": false,
"is_request_automated": false,
"request_automation_note": null,
"internal_notes": null,
"request_alerts": [
"A prior authorization for the same diagnosis and service was previously submitted and rejected."
],
"issues": [
{
"level": "WARNING",
"code": "SIMILAR_REJECTED_REQUESTS",
"message": "A prior authorization for the same diagnosis and service was previously submitted and rejected."
}
],
"status": "PARTIALLY_ACCEPTED",
"reviewer_erp_id": null,
"member_id": "uat-a-002",
"source": null,
"is_emergency": false,
"is_new_born": false,
"is_maternity": false,
"related_authorization_number": null,
"claim_type": null,
"treatment_date": "2024-02-15T10:00:00.000Z",
"period_start_date": null,
"doctor_id": "1",
"doctor_name": "Dr. Ahmed",
"doctor_speciality": "Cardiology",
"nphies_bundle_id": null,
"provider_system_id": "Provider System ID",
"provider_comment": "Provider Comment",
"ERP_user_id": null,
"price_list_level": null,
"patient_id": "uat-a-002",
"medical_provider_cchi_no": "22697412",
"ph_erp_id": "UAT-policy-id-01",
"currency": "SAR",
"currency_rate": 1,
"is_reviewer_accepted_as_road_traffic_accident": false,
"is_traffic_accident": false,
"assign_to_erp_id": null,
"additional_remarks": "Patient requires cardiac evaluation",
"total_recovery_utilized": 0,
"total_exgratia_utilized": 0,
"benefit_code": null,
"visit_type": "Enum Visit Type",
"is_referral": false,
"referral_provider_cchi_code": null,
"valid_days": null,
"referred_at": null,
"encounter": {
"encounter_id": null,
"encounter_status": "active",
"encounter_class": "outpatient",
"encounter_priority": null,
"encounter_start_date": null,
"encounter_end_date": null,
"encounter_arrival_code": null,
"encounter_department": "Cardiology",
"encounter_triage_category": null,
"encounter_triage_date": null,
"encounter_death_cause": null,
"encounter_admit_source": null,
"encounter_length_of_stay": null,
"encounter_admission": null,
"encounter_discharge": null
},
"items_decisions": [
{
"id": 501,
"item_erp_id": "ITEM-001",
"service_code": "FMCARS0008",
"duration": null,
"frequency": null,
"admission_date": null,
"discharge_date": null,
"approved_quantity": 1,
"approved_amount": 100,
"price": 100,
"request_amount": 100,
"provider_deductible_mount": 0,
"net_request_amount": 100,
"rejected_amount": 0,
"price_rejected_amount": 0,
"net_payable": 100,
"decision": "ACCEPTED",
"status": "ACCEPTED",
"warning_message": null,
"benefit_code": 10,
"sub_benefit_code": 1001,
"reason_code": [],
"najeeb_ai_alert": "",
"najeeb_ai_score": null,
"is_item_automated": true,
"item_automation_note": "This item was accepted automatically by the system.",
"issues": [],
"pbm_drug_info": null,
"treatment_date": null
},
{
"id": 502,
"item_erp_id": "ITEM-002",
"service_code": "9-420-05",
"duration": null,
"frequency": "OD",
"admission_date": null,
"discharge_date": null,
"approved_quantity": 0,
"approved_amount": 0,
"price": 1871.95,
"request_amount": 1871.95,
"provider_deductible_mount": 0,
"net_request_amount": 1871.95,
"rejected_amount": 0,
"price_rejected_amount": 0,
"net_payable": 0,
"decision": "REJECTED",
"status": "REJECTED",
"warning_message": null,
"benefit_code": 10,
"sub_benefit_code": 1001,
"reason_code": [
{
"najeeb_ai_code": "AD-2-5",
"najeeb_ai_description": "Time limit for submission has expired",
"najeeb_ai_message": "The time difference between the treatment date and the request date is more than 24 hours.",
"nphies_code": "AD-2-5",
"nphies_description": "Time limit for submission has expired",
"special_case_amount": null,
"erp_code": null,
"is_approved": false,
"severity": null,
"source": "RULES"
}
],
"najeeb_ai_alert": "Diagnosis \"Z24\" is invalid / inactive as per the ICD AM 10th Ed. Electronic Code List Edits.",
"najeeb_ai_score": 0,
"is_item_automated": false,
"item_automation_note": null,
"issues": [],
"pbm_drug_info": {
"id": 3210,
"sfda_code": "9-420-05",
"name": "Hepsera 10 mg tablet",
"scientific_name": "adefovir dipivoxil",
"manufacture_name": "Hepsera",
"pharmaceutical_form": "Tablet",
"strength": "10",
"unit": "mg",
"package_size": "30.000",
"price": 1871.95
},
"treatment_date": null
}
]
}
}Parameter Details
All date-time values are ISO 8601 strings in UTC (for example 2024-02-15T10:00:00.000Z).
Root Level Parameters
| Parameter | Type | Nullable | Description |
|---|---|---|---|
event_type | string | No | Webhook event identifier. Always PRE_AUTH_RESULT. Sent only with the default envelope |
pre_auth_internal_id | number | No | Najeeb internal identifier of the prior authorization |
transaction_id | string | Yes | The transaction_id sent on create |
authorization_number | string | Yes | The authorization_number sent on create |
nphies_reopen_at | string | Yes | Date-time the request was reopened through NPHIES |
nphies_reopen_reason | string | Yes | Reason for reopening through NPHIES |
submitter_erp_id | string | Yes | ERP ID of the reviewer of the request |
approval_remarks | string | Yes | Approval remarks of the request |
referral_remarks | string | Yes | Referral remarks of the request |
internal_referral_notes | string | Yes | Internal referral notes |
is_referred | boolean | Yes | The is_referred flag of the request |
is_request_automated | boolean | No | true only when every item of the request is automated. See Automation Fields |
request_automation_note | string | Yes | Explains the request's automation. Sent only when is_request_automated is true, otherwise null |
internal_notes | string | Yes | Internal notes of the request |
request_alerts | array of strings | No | Request-level alerts and notes generated during processing |
issues | array | No | Request-level issues, on every request. Repeats the information of notes and request_alerts in a structured form; both are kept. See Request Issues. Added with the DRG release |
status | string | Yes | Decision status of the request. See When It Is Sent |
reviewer_erp_id | string | Yes | ERP ID of the reviewer of the request |
member_id | string | Yes | The member ID |
source | string | Yes | Source of the request, when recorded. null for requests created through the integration API |
is_emergency | boolean | Yes | Emergency flag of the request |
is_new_born | boolean | Yes | Newborn flag of the request |
is_maternity | boolean | Yes | Maternity flag of the request |
related_authorization_number | string | Yes | The related_authorization_number sent on create |
claim_type | string | Yes | Reserved; currently always null |
treatment_date | date | Yes | Treatment date of the request (the treatment date of its first item) |
period_start_date | date | Yes | The period_start_date sent on create |
doctor_id | string | Yes | The doctor ID |
doctor_name | string | Yes | The doctor's name |
doctor_speciality | string | Yes | The doctor's medical specialty |
nphies_bundle_id | string | Yes | The NPHIES bundle ID |
provider_system_id | string | Yes | Provider system identifier |
provider_comment | string | Yes | Provider comments |
ERP_user_id | string | Yes | The erp_user_id sent on create |
price_list_level | string | Yes | The price list level |
patient_id | string | Yes | The member ID (same value as member_id) |
medical_provider_cchi_no | string | Yes | CCHI number of the medical provider |
ph_erp_id | string | Yes | ERP ID of the policy holder |
currency | string | Yes | Currency code |
currency_rate | number | Yes | Currency exchange rate |
is_reviewer_accepted_as_road_traffic_accident | boolean | Yes | Whether the reviewer accepted the case as a road traffic accident |
is_traffic_accident | boolean | Yes | Whether the case is flagged as a road traffic accident |
assign_to_erp_id | string | Yes | ERP ID of the user the request is assigned to |
additional_remarks | string | Yes | Additional remarks of the request |
total_recovery_utilized | number | No | Total recovery amount utilized (0 when none) |
total_exgratia_utilized | number | No | Total ex-gratia amount utilized (0 when none) |
benefit_code | number | Yes | Reserved; currently always null. Benefit codes are sent per item |
visit_type | string | Yes | Visit type of the request: NewVisit, FollowUp, Refill, WalkIn or Referral |
is_referral | boolean | No | Whether the request is linked to a referral provider |
referral_provider_cchi_code | string | Yes | CCHI code of the referral provider when the request is referred |
valid_days | number | Yes | Referral validity in days |
referred_at | string | Yes | Date-time the request was referred |
encounter | object | Yes | Encounter details (see Encounter Object) |
provider_drg | object | No | The provider DRG, with source and validity. Present when one was sent or found. Added with the DRG release |
settled_drg | object | No | The settled DRG, with settled_at. Present when set. Added with the DRG release |
drg | object | No | mode, and the current claimed and approved DRG results. Present only when the request was sent with drg_enabled: true and is inpatient. See Pre-auth DRG Coder result. Added with the DRG release |
items_decisions | array | No | One decision per item (see Item Decision Object) |
Encounter Object
Echoes the encounter fields sent on create; each is null when not sent.
| Parameter | Type | Nullable | Description |
|---|---|---|---|
encounter_id | string | Yes | Encounter identifier |
encounter_status | string | Yes | Encounter status |
encounter_class | string | Yes | Encounter class |
encounter_priority | string | Yes | Encounter priority |
encounter_start_date | date | Yes | Encounter start date |
encounter_end_date | date | Yes | Encounter end date |
encounter_arrival_code | string | Yes | Encounter arrival code |
encounter_department | string | Yes | Encounter department |
encounter_triage_category | string | Yes | Encounter triage category |
encounter_triage_date | date | Yes | Encounter triage date |
encounter_death_cause | string | Yes | Encounter death cause |
encounter_admit_source | string | Yes | Encounter admit source |
encounter_length_of_stay | string | Yes | Encounter length of stay |
encounter_admission | string | Yes | Encounter admission details |
encounter_discharge | string | Yes | Encounter discharge details |
Item Decision Object
Each entry in items_decisions is the decision for one item of the request.
| Parameter | Type | Nullable | Description |
|---|---|---|---|
id | number | No | Najeeb internal identifier of the item |
item_erp_id | string | Yes | The erp_item_id sent on create |
service_code | string | Yes | Service code of the item. When the AI mapped the item to another service, the mapped service's code |
duration | string | Yes | Approved duration |
frequency | string | Yes | Frequency of the item |
admission_date | date | Yes | Kept for compatibility; always null |
discharge_date | date | Yes | Kept for compatibility; always null |
approved_quantity | number | No | Approved quantity (0 when none) |
approved_amount | number | No | Approved amount (0 when none) |
price | number | Yes | Price list price of the item. null when your instance runs without a price list |
request_amount | number | Yes | Requested amount |
provider_deductible_mount | number | Yes | Provider deductible amount (the key is spelled provider_deductible_mount) |
net_request_amount | number | Yes | Net requested amount after deductions |
rejected_amount | number | No | Reserved; currently always 0 |
price_rejected_amount | number | No | Reserved; currently always 0 |
net_payable | number | Yes | Net payable amount |
decision | string | Yes | Decision for the item, for example ACCEPTED or REJECTED. See When It Is Sent |
status | string | Yes | Same value as decision after AI processing; null after a reviewer decision in the portal |
warning_message | string | Yes | Reserved; currently always null |
benefit_code | number | Yes | Benefit code of the item |
sub_benefit_code | number | Yes | Sub-benefit code of the item |
reason_code | array | Yes | Reasons for the decision (see Reason Code Object). Empty array when the item has none |
najeeb_ai_alert | string | No | AI alerts and notes for the item, joined with commas. Empty string when there are none |
najeeb_ai_score | number | Yes | Najeeb AI score for the item |
is_item_automated | boolean | No | true when the automation rules let you apply this item's decision without review. See Automation Fields |
item_automation_note | string | Yes | Explains the item's automation. Sent only when is_item_automated is true, otherwise null |
issues | array | No | Issues about this item, for example a procedure left out of DRG grouping. Present on every item. Added with the DRG release |
pbm_drug_info | object | Yes | Drug details when the item is a pharmaceutical product (see PBM Drug Info Object), otherwise null |
treatment_date | date | Yes | Reserved; currently always null. Use the root treatment_date |
Reason Code Object
Each entry in reason_code is one reason for the item decision.
| Parameter | Type | Nullable | Description |
|---|---|---|---|
najeeb_ai_code | string | Yes | Najeeb reason code |
najeeb_ai_description | string | Yes | Description of the reason |
najeeb_ai_message | string | Yes | Detailed message explaining why the reason applies to this item |
nphies_code | string | Yes | NPHIES reason code the Najeeb reason maps to |
nphies_description | string | Yes | Description of the NPHIES reason |
special_case_amount | number | Yes | Amount linked to the reason, when the reason concerns an amount |
erp_code | string | Yes | Your ERP code for the reason, when one is mapped |
is_approved | boolean | Yes | true when the reason code starts with 00 (an approval reason) |
severity | string | Yes | Severity level of the reason, as returned by the AI (PBM checks) |
source | string | Yes | Where the reason came from, for example AI, RULES, PBM, PORTAL or INTEGRATION |
PBM Drug Info Object
Present only when the item is a pharmaceutical product.
| Parameter | Type | Nullable | Description |
|---|---|---|---|
id | number | No | Najeeb internal identifier of the drug |
sfda_code | string | No | SFDA drug code |
name | string | No | Drug name |
scientific_name | string | Yes | Scientific (generic) name |
manufacture_name | string | Yes | Manufacturer name |
pharmaceutical_form | string | Yes | Pharmaceutical form (for example tablet, capsule, injection) |
strength | string | Yes | Drug strength |
unit | string | Yes | Unit of measurement |
package_size | string | Yes | Package size |
price | number | Yes | Drug price |
Automation Fields
The automation rules configured for your instance decide, per item, whether you can apply the decision without a manual review.
| Level | Flag | Note when the flag is true | Note when the flag is false |
|---|---|---|---|
| Item | is_item_automated | item_automation_note, for example This item was rejected automatically by the system. Due to [ AD-2-5 | Time limit for submission has expired ] (one bracket per reason; no "Due to" part when the item has no reason) | null |
| Request | is_request_automated (true only when every item is automated) | request_automation_note, for example This request was accepted automatically by the system, as all items were accepted. | null |
Each item's note follows that item's own flag, so an automated item still carries its note when the request as a whole is not automated.
Example Webhook Payload
See also the PRE_AUTH_RESULT example on the Webhook page.