Prior Authorization / Lightweight

Najeeb Prior Authorization Lightweight as a Service 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.

Service Model

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.

Prior Authorization MODES

The "Prior Authorization Lightweight" flow differs from the "Prior Authorization Standard" flow primarily in its validation logic. Unlike Standard mode, the Lightweight flow does not validate member policies, consumption limits, or existing entitlements. Furthermore, it omits pre-creation checks for members, policies, and policy holders, as well as membership join validations. Consequently, if a member or policy does not already exist in Lightweight mode, the system automatically creates it on the fly.

Service Description

Najeeb Prior Authorization Lightweight as a Service provides a seamless API integration that enables insurance companies to submit pre-authorization requests from their core systems and receive adjudicated results in real time. 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

• Adjudication: Receive instant responses to pre-authorization submissions
• Ephemeral Data Processing: All data is processed temporarily and securely within your isolated Najeeb instance
• AI-Powered Processing: Leverage Najeeb's AI Engine for intelligent pre-authorization adjudication
• Comprehensive Validation: Built-in validation for diagnoses, medical providers, and service codes
• Automated Validation: Built-in validation for diagnosis codes, service codes, and prescriber information
• KSA Compliance: Fully compliant with Saudi healthcare regulations
• Scalable Architecture: Handles high volumes of requests with reliable performance

This is a lightweight version of the AI Engine capabilities

Due to this, some capabilities of the full version of the AI Engine will be dropped under this request like:

• Policy and benefits validation
• Network validation
• Member enrollment and join checks
• Contractual rejections due to the lack of price list information

How It Works

1. Request Submission: Your core system sends a pre-authorization request to the Najeeb API
2. Processing: The request is processed within your isolated Najeeb instance with ephemeral data handling
3. Validation: Automated validation of diagnosis codes, service codes, and provider credentials
4. Response: Adjudicated result is returned to your system with approval, rejection, or additional requirements

Requirements Prior to Integration

Before integrating with Najeeb Prior Authorization Lightweight as a Service, ensure you have the following:

Technical Requirements

1. 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

2. Data Requirements

• Transaction data (authorization number, unique transaction ID, treatment date)
• Policy data (policy number, policy holder ERP ID)
• Medical provider data (CCHI number). For reporting purposes, we recommend sending a list of medical providers (including names and CCHI codes) to the Najeeb technical team in advance.
• Member data (member ID, date of birth, gender, marital status)
• Prescriber information (doctor ID, speciality, name)
• Item/service details (service code, description, NPHIES code and type, quantity, amount)
• Diagnosis codes (ICD-10 format)

Data Preparation

Ensure your system can provide:

• Transaction Data: authorization number, a unique transaction ID
• Policy Data: policy number, policy holder ERP ID
• Member Data: member ID, date of birth, gender, marital status
• Provider Data: medical provider CCHI number, doctor ID/specialty/name
• Item Data: service code, service description, NPHIES code and type, quantity, amount, benefit/sub-benefit codes
• Diagnosis Data: ICD-10 diagnosis codes (primary/secondary)

ph_erp_id

For the ph_erp_id field, provide your internal policyholder identifier. If this identifier is not available, send the value "default" for all requests.:::

member_id

If the member_id was not defined earlier in Najeeb, then Najeeb will create a new member record with the demographics defined in the request member_dob & member_gender. Important note: If a member already exists in the system, the existing record will be retained—no duplicate will be created and no overwrite will occur. However, if you send subsequent requests with the same member_id but differing demographic information, the system will flag a member information inconsistency warning.

Request Unique Identifier

• transaction_id is the primary idempotency key and must be unique per request; a duplicate value returns an error.
• authorization_number is not required to be unique; it can be reused across follow-up requests related to the same authorization.

Service Identifiers

service_code, service_description, nphies_code, nphies_type, and service_type are all required on every item.

Integration Guide

The Najeeb Prior Authorization Lightweight 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.

Historical Data Synch

Najeeb offers additional endpoints for synchronizing historical claims and requests made by the member. While integration with these APIs is optional, it allows Najeeb to make more accurate decisions by leveraging the member's past data.

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 Lightweight Request

POST /approval-request/create

This endpoint receives a prior authorization request from your core system and processes it ephemerally within your isolated Najeeb instance. The request is validated and acknowledged synchronously.

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",
  "transaction_type": "string",
  "policy_no": "string",
  "ph_erp_id": "string",
  "related_authorization_number": "string",
  "medical_provider_cchi_no": "string",
  "member_id": "string",
  "member_dob": "string",
  "member_gender": "string",
  "marital_status": "string",
  "treatment_date": "date",
  "request_date": "date",
  "claim_type": "string",
  "claim_sub_type": "string",
  "is_emergency": "boolean",
  "is_maternity": "boolean",
  "is_new_born": "boolean",
  "benefit_code": "number",
  "benefit_description": "string",
  "diagnoses": [
    {
      "type": "primary",
      "code": "string",
      "name": "string"
    },
    {
      "type": "secondary",
      "code": "string",
      "name": "string"
    }
  ],
  "items": [
    {
      "claimed_quantity": "number",
      "claimed_amount": "number",
      "duration": "string",
      "admission_date": "date",
      "frequency": "string",
      "discharge_date": "date",
      "justification": "string",
      "erp_item_id": "string",
      "service_code": "string",
      "service_description": "string",
      "nphies_code": "string",
      "nphies_type": "string",
      "service_type": "string",
      "benefit_code": "number",
      "benefit_description": "string",
      "sub_benefit_code": "number",
      "sub_benefit_description": "string",
      "serial_number": "string"
    }
  ],
  "doctor_id": "string",
  "doctor_speciality": "string",
  "doctor_name": "string",
  "approval_remarks": "string",
  "additional_remarks": "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"
}

Parameter Details

Root Level Parameters

Parameter	Type	Required	Description	Accepted Values
authorization_number *	string	Yes	The authorization number of the prior authorization can be repeated.	Alphanumeric string, 1-255 characters
transaction_id *	string	Yes	Unique transaction ID for this request; a duplicate value returns an error	Alphanumeric string, max 255 characters
transaction_type	string	No	Indicates whether this request is a pre-authorization or a claim	Enum: PREAUTH, CLAIM
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 of the prior authorization	Alphanumeric string, 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 *	string	Yes	The gender of the member	Enum: MALE, FEMALE
marital_status *	string	Yes	The marital status of the member	Enum: SINGLE, MARRIED, ENGAGED, UNKNOWN, WIDOWED, DIVORCED, SEPARATED
treatment_date *	date	Yes	The treatment date of the prior authorization	ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
request_date *	date	Yes	The request date of the prior authorization	ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
claim_type *	string	Yes	The claim type of the prior authorization	Enum: INSTITUTIONAL, PROFESSIONAL, PHARMACY, DENTAL, OPTICAL
claim_sub_type *	string	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
benefit_code	number	No	The benefit code of the prior authorization	Integer, 0-9999999
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
diagnoses *	array	Yes	Array of diagnosis objects	Minimum 1 diagnosis required
items *	array	Yes	Array of item objects	Minimum one item is required
doctor_id	string	No	The doctor ID of the prior authorization	Alphanumeric string, max 255 characters
doctor_speciality	string	No	The doctor's medical specialty	String, max 255 characters
doctor_name	string	No	The doctor's name	String, max 255 characters
approval_remarks	string	No	Remarks for approval	Free text, max 255 characters
additional_remarks	string	No	Additional remarks or notes	Free text, max 255 characters
currency	string	No	Currency code	String, max 255 characters
currency_rate	number	No	Currency exchange rate	Decimal, minimum 0
nphies_bundle_id	string	No	The NPHIES bundle ID of the prior authorization	Alphanumeric string, max 255 characters
provider_system_id	string	No	Provider system identifier	Alphanumeric string, max 255 characters
provider_comment	string	No	Provider comments	Free text, max 255 characters
erp_user_id	string	No	The ERP user ID of the prior authorization	Alphanumeric string, max 255 characters
price_list_level	string	No	The price list level of the prior authorization	Alphanumeric string, max 255 characters

Diagnosis Object

Parameter	Type	Required	Description	Accepted Values
type *	Enum	Yes	Type of diagnosis	Enum: primary, secondary
code *	string	Yes	ICD-10 diagnosis code	Valid ICD-10 code format, max 255 characters
name	string	No	Diagnosis name/description	String, max 255 characters

Item Object

Parameter	Type	Required	Description	Accepted Values
service_code *	string	Yes	Service code of the item	Alphanumeric string, 1-255 characters
service_description *	string	Yes	Service description of the item	String, 1-255 characters
nphies_code *	string	Yes	NPHIES code of the item	Alphanumeric string, 1-255 characters
nphies_type *	string	Yes	NPHIES type of the item	Enum: AMBULATORY, CONSULTATION, PHARMACEUTICAL, DEVICE, OPTICAL, DENTAL, BABY_FORMULA
service_type *	string	Yes	Service type of the item	Enum: AMBULATORY, CONSULTATION, PHARMACEUTICAL, DEVICE, OPTICAL, DENTAL, BABY_FORMULA
claimed_quantity	number	No	Quantity of the item (defaults to 1 if not sent)	Integer, 1-1000000000
claimed_amount	number	No	Claimed amount/price of the item	Decimal, default 0
duration	string	No	Duration of the item	Free text
admission_date	date	No	Admission date of the item	ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
frequency	string	No	Frequency of the item	Enum:[OD, BID, Q12H, TID, Q8H, QID, Q6H, QD, Q24H, QOD, QM, Q4H]
discharge_date	date	No	Discharge 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	Alphanumeric string, max 255 characters
benefit_code	number	No	Benefit code of the item	Integer, 0-9999999
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, 0-9999999
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
serial_number	string	No	Serial number of the item	Alphanumeric string, max 255 characters

Enums

Transaction Type Enum:

• PREAUTH - Pre-authorization request
• CLAIM - Claim request

Member Gender Enum:

• MALE - Male
• FEMALE - Female

Marital Status Enum:

• SINGLE - Single
• MARRIED - Married
• ENGAGED - Engaged
• UNKNOWN - Unknown
• WIDOWED - Widowed
• DIVORCED - Divorced
• SEPARATED - Separated

Claim Type Enum:

• INSTITUTIONAL - Institutional services for inpatients
• PROFESSIONAL - Professional services for outpatients
• PHARMACY - Pharmacy services
• DENTAL - Dental services
• OPTICAL - Optical services

Claim Sub Type Enum:

• IN_PATIENT - Inpatient services
• OUT_PATIENT - Outpatient services
• EMERGENCY - Emergency services

Diagnosis Type Enum:

• primary - Primary diagnosis
• secondary - Secondary diagnosis

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",
    "transaction_type": "PREAUTH",
    "policy_no": "no-01",
    "ph_erp_id": "default",
    "medical_provider_cchi_no": "10566",
    "member_id": "mem-01",
    "member_dob": "1990-01-15T00:00:00.000Z",
    "member_gender": "MALE",
    "marital_status": "SINGLE",
    "treatment_date": "2024-02-15T10:00:00.000Z",
    "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": [
      {
        "service_code": "FMCARS0008",
        "service_description": "Pharmacological Stress Echocardiography",
        "nphies_code": "55113-00-00",
        "nphies_type": "AMBULATORY",
        "service_type": "AMBULATORY",
        "claimed_quantity": 1,
        "claimed_amount": 100,
        "justification": "Patient requires cardiac assessment"
      }
    ],
    "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"
  }'

Note: claim_type accepts INSTITUTIONAL, PROFESSIONAL, PHARMACY, DENTAL, or OPTICAL — adjust to the value that matches the service being submitted.

Response

Success Response (201 Created)

{
  "pre_auth_internal_id": "number",
  "status": "string",
  "authorization_number": "string",
  "transaction_id": "string",
  "note": "string",
  "items_results": [
    {
      "service_code": "string",
      "approved": "boolean",
      "approved_quantity":  "number",
      "approved_duration": "string",
      "najeeb_ai_alert": "string",
      "rejection_reason": []
    },
    {
      "service_code": "string",
      "approved": "boolean",
      "approved_quantity":  "string",
      "approved_duration": "string",
      "najeeb_ai_alert": "string",
      "rejection_reason": [
        {
          "code": "string",
          "nphies_code": "string",
          "message": "string"
        }
      ]
    }
  ]
}

Response Fields

Field	Type	Description
approval_request_internal_id	number	Internal identifier assigned to the request
status	string	"COMPLETED": means the request processing has been completed
authorization_number	string	Echoes the submitted authorization number
transaction_id	string	Echoes the submitted transaction ID
request_alerts	array of string	AI-generated alerts on request level
items_decisions	array	Per-item adjudication decisions (see Item Decision Object below)

Item Decision Object

Field	Type	Description
service_code	string	Service/item code being processed
approved	boolean	Final approval decision by Najeeb (true/false)
approved_quantity	number	Quantity approved by Najeeb for the service/item
approved_duration	number	Duration approved by Najeeb (in days)
najeeb_ai_alert	number	AI-generated alert or note on the level of the item
rejection_reason	number	List of rejection reason objects (see below)

Rejection Reason Object

Field	Type	Description
code	string	Rejection reason code from Najeeb
nphies_code	string	Corresponding NPHIES code
message	string	Rejection message

Example Success Response

{
  "pre_auth_internal_id": 12345,
  "status": "COMPLETED",
  "authorization_number": "AU-12345",
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "request_alerts": ["This Pre-auth request is similar to previously rejected requests."],
  "items_results": [
    {
      "service_code": "FMCARS0008",
      "approved": true,
      "approved_quantity": 1,
      "approved_duration": "30",
      "najeeb_ai_alert": "",
      "rejection_reason": []
    },
    {
      "service_code": "55113-00-00",
      "approved": false,
      "approved_quantity": 0,
      "approved_duration": "0",
      "najeeb_ai_alert": "Service not medically justified for the given diagnosis",
      "rejection_reason": [
        {
          "code": "MN-1-1",
          "nphies_code": "MN-1-1",
          "message": "Diagnosis does not support the requested service"
        }
      ]
    }
  ]
}

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_EPA_02	404	Diagnosis not found
E_EPA_069	409	Prior authorization already exists with this transaction_id:{{transaction_id}}
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"
  ]
}

Diagnosis Not Found:

{
  "ErrorCode": "E_EPA_02",
  "message": "Diagnosis not found, The codes of the diagnosis are:[0]",
  "details": []
}

Duplicate Prior Authorization:

{
  "ErrorCode": "E_EPA_069",
  "message": "Prior authorization already exists with this transaction_id:{{transaction_id}}",
  "details": []
}

Error: 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

1. Date Formats: Use ISO 8601 format with timezone for all date fields (e.g., 2024-01-15T10:04:20.346Z)
2. Diagnoses: A single primary diagnosis is required to support the requested services. You may also send one or multiple additional diagnoses.
3. Items: Ensure all required item fields are provided, especially service_code, service_description, nphies_code, nphies_type, and service_type
4. Error Handling: Implement retry logic with exponential backoff for transient errors
5. Validation: Validate data before sending requests to avoid unnecessary API calls
6. Monitoring: Monitor response times and error rates
7. Logging: Log all requests and responses for audit and debugging purposes
8. Timeout Configuration: Set your HTTP client timeout to 50 seconds to accommodate AI Engine processing time.

Code Examples

cURL

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-12sdfghj2",
    "transaction_id": "transaction_id3",
    "transaction_type": "PREAUTH",
    "policy_no": "no-01",
    "ph_erp_id": "default",
    "medical_provider_cchi_no": "10566",
    "member_id": "mem-01",
    "member_dob": "2025-12-29T11:41:30.625Z",
    "member_gender": "MALE",
    "marital_status": "SINGLE",
    "treatment_date": "2025-12-29T11:41:30.625Z",
    "request_date": "2025-12-29T11:41:30.625Z",
    "claim_type": "PROFESSIONAL",
    "claim_sub_type": "OUT_PATIENT",
    "diagnoses": [
      {
        "type": "primary",
        "code": "E40"
      },
      {
        "type": "secondary",
        "code": "Z24",
        "name": "Need for immunisation against certain single viral diseases"
      }
    ],
    "items": [
      {
        "service_code": "40903-00-00",
        "service_description": "Neuroendoscopy",
        "service_type": "AMBULATORY",
        "nphies_code": "40903-00-00",
        "nphies_type": "AMBULATORY",
        "claimed_quantity": 1,
        "claimed_amount": 500
      }
    ]
  }'

JavaScript

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-12sdfghj2',
    transaction_id: 'transaction_id3',
    transaction_type: 'PREAUTH',
    policy_no: 'no-01',
    ph_erp_id: 'default',
    medical_provider_cchi_no: '10566',
    member_id: 'mem-01',
    member_dob: '2025-12-29T11:41:30.625Z',
    member_gender: 'MALE',
    marital_status: 'SINGLE',
    treatment_date: '2025-12-29T11:41:30.625Z',
    request_date: '2025-12-29T11:41:30.625Z',
    claim_type: 'PROFESSIONAL',
    claim_sub_type: 'OUT_PATIENT',
    diagnoses: [
      { type: 'primary', code: 'E40' },
      { type: 'secondary', code: 'Z24', name: 'Need for immunisation against certain single viral diseases' },
    ],
    items: [
      {
        service_code: '40903-00-00',
        service_description: 'Neuroendoscopy',
        service_type: 'AMBULATORY',
        nphies_code: '40903-00-00',
        nphies_type: 'AMBULATORY',
        claimed_quantity: 1,
        claimed_amount: 500,
      },
    ],
  }),
});

const result = await response.json();
console.log(result);

Python

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-12sdfghj2',
        'transaction_id': 'transaction_id3',
        'transaction_type': 'PREAUTH',
        'policy_no': 'no-01',
        'ph_erp_id': 'default',
        'medical_provider_cchi_no': '10566',
        'member_id': 'mem-01',
        'member_dob': '2025-12-29T11:41:30.625Z',
        'member_gender': 'MALE',
        'marital_status': 'SINGLE',
        'treatment_date': '2025-12-29T11:41:30.625Z',
        'request_date': '2025-12-29T11:41:30.625Z',
        'claim_type': 'PROFESSIONAL',
        'claim_sub_type': 'OUT_PATIENT',
        'diagnoses': [
            {'type': 'primary', 'code': 'E40'},
            {'type': 'secondary', 'code': 'Z24', 'name': 'Need for immunisation against certain single viral diseases'},
        ],
        'items': [
            {
                'service_code': '40903-00-00',
                'service_description': 'Neuroendoscopy',
                'service_type': 'AMBULATORY',
                'nphies_code': '40903-00-00',
                'nphies_type': 'AMBULATORY',
                'claimed_quantity': 1,
                'claimed_amount': 500,
            },
        ],
    },
)

result = response.json()
print(result)

Webhook Response (Najeeb Decision Result)

After the Najeeb Engine finishes processing a pre-authorization request, Najeeb delivers the final decision to your configured webhook endpoint. This is the asynchronous response referenced in the Integration Guide.

Webhook Configuration

To receive the Najeeb decision, register a webhook with hook_type set to PRE_AUTH_RESULT. See Webhook for registration details and the example payload.

Response Payload Structure

{
  "event_type": "PRE_AUTH_RESULT",
  "data": {
  "pre_auth_internal_id": 161081,
  "transaction_id": "#tr-0001",
  "authorization_number": "#A-0001",
  "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,
  "internal_notes": null,
  "request_alerts": [
    "A prior authorization for the same diagnosis and service was previously submitted and rejected."
  ],
  "status": "PENDING",
  "reviewer_erp_id": null,
  "member_id": "uat-a-002",
  "source": "PORTAL",
  "is_emergency": false,
  "is_new_born": false,
  "is_maternity": false,
  "related_authorization_number": null,
  "claim_type": null,
  "treatment_date": "2025-12-05T19:40:28.542Z",
  "period_start_date": "2025-12-05T19:40:28.542Z",
  "doctor_id": "1",
  "doctor_name": "Dr. Ahmed",
  "doctor_speciality": "Cardiology",
  "nphies_bundle_id": "1",
  "provider_system_id": "Provider System ID",
  "provider_comment": "Provider Comment",
  "ERP_user_id": null,
  "price_list_level": "Price List Level",
  "patient_id": "uat-a-002",
  "medical_provider_cchi_no": "22697412",
  "ph_erp_id": "default",
  "currency": "SAR",
  "currency_rate": 1,
  "is_reviewer_accepted_as_road_traffic_accident": false,
  "is_traffic_accident": false,
  "assign_to_erp_id": null,
  "additional_remarks": null,
  "total_recovery_utilized": 0,
  "total_exgratia_utilized": 0,
  "benefit_code": null,
  "is_referral": false,
  "referral_provider_cchi_code": null,
  "valid_days": null,
  "referred_at": null,
  "encounter": {
    "encounter_id": "Encounter ID",
    "encounter_status": "active",
    "encounter_class": "inpatient",
    "encounter_priority": "urgent",
    "encounter_start_date": "2025-12-05T19:40:28.542Z",
    "encounter_end_date": "2025-12-05T19:40:28.542Z",
    "encounter_arrival_code": "A01",
    "encounter_department": "Cardiology",
    "encounter_triage_category": "Category1",
    "encounter_triage_date": "2025-12-05T19:40:28.542Z",
    "encounter_death_cause": "Heart Failure",
    "encounter_admit_source": "Referral",
    "encounter_length_of_stay": "5 days",
    "encounter_admission": "Admission details",
    "encounter_discharge": "Discharge details"
  },
  "items_decisions": [
    {
      "item_erp_id": "16562",
      "service_code": "9-420-05",
      "duration": null,
      "frequency": "10 times",
      "admission_date": "2025-12-05T19:40:28.541Z",
      "discharge_date": "2025-12-05T19:40:28.541Z",
      "approved_quantity": 2,
      "approved_amount": 4500,
      "price": 0,
      "request_amount": 4500,
      "provider_deductible_amount": 0,
      "net_request_amount": 4500,
      "rejected_amount": 0,
      "price_rejected_amount": 0,
      "net_payable": null,
      "decision": "PENDING",
      "warning_message": null,
      "benefit_code": 10,
      "sub_benefit_code": 1001,
      "reason_code": [
        {
          "najeeb_ai_code": "BE-1-5",
          "najeeb_ai_description": "Claim information is inconsistent with preauthorized services",
          "najeeb_ai_message": "Pharmaceutical service Hepsera 10 mg tablet is inconsistent with claim type PROFESSIONAL",
          "nphies_code": "BE-1-5",
          "nphies_description": "Claim information is inconsistent with preauthorized services",
          "special_case_amount": null,
          "erp_code": null,
          "is_approved": false,
          "source": "RULES"
        },
        {
          "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 48 hours.",
          "nphies_code": "AD-2-5",
          "nphies_description": "Time limit for submission has expired",
          "special_case_amount": null,
          "erp_code": null,
          "is_approved": false,
          "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,
      "pbm_drug_info": {
        "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
      }
    },
    {
      "item_erp_id": "16562",
      "service_code": "179-186-02",
      "duration": null,
      "frequency": "10 times",
      "admission_date": "2025-12-05T19:40:28.541Z",
      "discharge_date": "2025-12-05T19:40:28.541Z",
      "approved_quantity": 2,
      "approved_amount": 4500,
      "price": 0,
      "request_amount": 4500,
      "provider_deductible_amount": 0,
      "net_request_amount": 4500,
      "rejected_amount": 0,
      "price_rejected_amount": 0,
      "net_payable": null,
      "decision": "PENDING",
      "warning_message": null,
      "benefit_code": 10,
      "sub_benefit_code": 1001,
      "reason_code": [
        {
          "najeeb_ai_code": "BE-1-5",
          "najeeb_ai_description": "Claim information is inconsistent with preauthorized services",
          "najeeb_ai_message": "Pharmaceutical service Albenda 200 mg tablet is inconsistent with claim type PROFESSIONAL",
          "nphies_code": "BE-1-5",
          "nphies_description": "Claim information is inconsistent with preauthorized services",
          "special_case_amount": null,
          "erp_code": null,
          "is_approved": false,
          "source": "RULES"
        },
        {
          "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 48 hours.",
          "nphies_code": "AD-2-5",
          "nphies_description": "Time limit for submission has expired",
          "special_case_amount": null,
          "erp_code": null,
          "is_approved": false,
          "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,
      "pbm_drug_info": {
        "sfda_code": "179-186-02",
        "name": "Albenda 200 mg tablet",
        "scientific_name": "albendazole",
        "manufacture_name": "Albenda",
        "pharmaceutical_form": "Film-coated tablet",
        "strength": "200",
        "unit": "mg",
        "package_size": "2.000",
        "price": 6.15
      }
    }
  ]
}
}

Event Type

Every webhook payload includes "event_type": "PRE_AUTH_RESULT" at the root level so you can identify the notification type. Decision fields are nested under the data object.

Parameter Details

Root Level Parameters

Parameter	Type	Nullable	Description
event_type	string	No	Webhook event identifier. Always PRE_AUTH_RESULT for this response
pre_auth_internal_id	number	No	Najeeb internal identifier for the prior authorization
transaction_id	string	Yes	The unique transaction ID submitted in the original request
authorization_number	string	Yes	The authorization number of the prior authorization
status	string	Yes	The final decision status of the prior authorization
period_start_date	string	Yes	The period start date of the prior authorization
treatment_date	string	Yes	The treatment date of the prior authorization
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_reopen_at	string	Yes	Timestamp when the request was reopened via NPHIES
nphies_reopen_reason	string	Yes	Reason for reopening via NPHIES
submitter_erp_id	string	Yes	ERP ID of the reviewer who submitted the decision
reviewer_erp_id	string	Yes	ERP ID of the assigned reviewer
member_id	string	Yes	The member UUID
patient_id	string	Yes	The patient UUID
source	string	Yes	The source of the prior authorization
is_emergency	boolean	Yes	Flag indicating an emergency case
is_new_born	boolean	Yes	Flag indicating a newborn case
is_maternity	boolean	Yes	Flag indicating a maternity case
related_authorization_number	string	Yes	The related authorization number for follow-up requests
claim_type	string	Yes	The claim type (INSTITUTIONAL, PROFESSIONAL, PHARMACY, DENTAL, OPTICAL)
claim_sub_type	string	Yes	The claim sub type (IN_PATIENT, OUT_PATIENT, EMERGENCY)
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
price_list_level	string	Yes	The price list level
medical_provider_cchi_no	string	Yes	CCHI number of the medical provider
ph_erp_id	string	Yes	ERP code 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
is_referral	boolean	No	Flag indicating the request is a referred request from a previous one.
referral_provider_cchi_code	string	Yes	CCHI code of the referral provider
valid_days	number	Yes	Number of valid days for the authorization
referred_at	string	Yes	Timestamp when the request was referred
referral_remarks	string	Yes	Remarks for referral
internal_referral_notes	string	Yes	Internal referral notes
internal_notes	string	Yes	Internal notes
is_referred	boolean	No	Flag indicating the request is a referral (defaults to false)
assign_to_erp_id	string	Yes	ERP ID of the assigned user
approval_remarks	string	Yes	Remarks for approval
additional_remarks	string	Yes	Additional remarks or notes
request_alerts	array	No	Array of alert and note strings generated during processing
total_recovery_utilized	number	No	Total recovery amount utilized (defaults to 0)
total_exgratia_utilized	number	No	Total ex-gratia amount utilized (defaults to 0)
benefit_code	string	Yes	The benefit code associated with the request

Encounter Object

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	string	Yes	Encounter start date
encounter_end_date	string	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	string	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 the items_decisions array represents the AI Engine's decision for a specific item in the pre-authorization request.

Parameter	Type	Nullable	Description
Warning message associated with the pricelist validations	string	Yes	The ERP item ID submitted in the original request
service_code	string	Yes	Service code of the item
duration	string	Yes	Approved duration
frequency	string	Yes	Frequency of the item
admission_date	string	Yes	Admission date
discharge_date	string	Yes	Discharge date
approved_quantity	number	Yes	The approved quantity for this item
approved_amount	number	Yes	The approved amount for this item
price	number	Yes	Price list price for the item
request_amount	number	Yes	The originally requested amount
provider_deductible_amount	number	Yes	Provider deductible amount
net_request_amount	number	Yes	Net requested amount after deductions
rejected_amount	number	Yes	The rejected amount for this item
price_rejected_amount	number	Yes	The price-based rejected amount
net_payable	number	Yes	Net payable amount
approval_remarks	string	Yes	Remarks for approval
decision	string	Yes	The decision status for this item
warning_message	string	Yes	Warning message associated with the pricelist validations
benefit_code	number	Yes	Benefit code of the item
sub_benefit_code	number	Yes	Sub benefit code of the item
reason_code	array	No	Array of reason objects explaining the decision (see below)
najeeb_ai_alert	string	No	A system-generated note attached to this item indicating an AI-driven flag or observation.
najeeb_ai_score	number	Yes	Najeeb AI confidence score
pbm_drug_info	object	Yes	PBM drug information if the item is a pharmaceutical (see below)

Reason Code Object

Each entry in the reason_code array provides a detailed reason for the item decision.

Parameter	Type	Nullable	Description
najeeb_ai_code	string	Yes	Najeeb internal reason code
najeeb_ai_description	string	Yes	Najeeb internal reason description
najeeb_ai_message	string	Yes	The cause or detailed message from the AI Engine
nphies_code	string	Yes	The NPHIES-mapped reason code
nphies_description	string	Yes	The NPHIES-mapped reason description
special_case_amount	number	Yes	Amount associated with special case handling
is_approved	boolean	Yes	true if the reason code starts with 00, indicating an approval reason
source	string	Yes	Source of the reason (e.g., AI, RULES, MANUAL)

PBM Drug Info Object

Present only when the item is a pharmaceutical product. Contains drug details from the PBM module.

Parameter	Type	Nullable	Description
sfda_code	string	No	Saudi FDA drug code
name	string	No	Drug name
scientific_name	string	Yes	Scientific (generic) name of the drug
manufacture_name	string	Yes	Manufacturer name
pharmaceutical_form	string	Yes	Pharmaceutical form (e.g., 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

Example Webhook Payload

See the PRE_AUTH_RESULT example payload on the Webhook page. You must register a webhook with hook_type set to PRE_AUTH_RESULT to receive the decision result.