Najeeb Prior Authorization as a Service / Standard

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

Service Description

Najeeb Prior Authorization as a Service 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.)
• KSA Compliance: Fully compliant with Saudi healthcare and pharmaceutical regulations
• Scalable Architecture: Handles high volumes of requests with reliable performance

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 diagnoses, provider credentials, policy, and member information
4. AI Analysis: The request is sent to the AI Engine for intelligent adjudication
5. 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 as a Service, ensure you have the following:

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

Sync Before Submitting Requests

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:

1. Policy Holder — must be created first as the parent entity for policies
2. Policy — must be linked to the policy holder, with category, benefits, and sub-benefits configured
3. Member — must be registered and assigned to the policy
4. 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:

1. 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_description and sub_benefit_description in each item of the pre-authorization request so that Najeeb can auto-create the records.

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

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

tip

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.

member_id

If a member already exists in the system, the existing record will be retained — no duplicate will be created and no overwrite will occur.

History Processing

Please ensure a unique member ID is always selected and transmitted to Najeeb for history processing. The system/Najeeb requires this to process the preceding one year of approved pre-authorizations.

To activate member history, you must include "with_patient_history": true in create pre-auth payload.

Request Unique Identifier

• transaction_id is the primary idempotency key and must be unique per request; a duplicate value returns a conflict error.
• authorization_number is 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.

Asynchronous Processing

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",
  "referred_authorization_number": "string",
  "is_referred": "boolean",
  "medical_provider_cchi_no": "string",
  "member_id": "string",
  "member_dob": "string",
  "member_gender": "string",
  "marital_status": "string",
  "visit_type": "string",
  "treatment_date": "string",
  "request_date": "string",
  "addition_date": "string",
  "claim_type": "string",
  "claim_sub_type": "string",
  "is_emergency": "boolean",
  "is_maternity": "boolean",
  "is_new_born": "boolean",
  "is_referral": "boolean",
  "hcp_appointed_flag": "boolean",
  "hcp_moh_flag": "boolean",
  "advanced_preauth": "boolean",
  "advanced_preauth_status": "string",
  "with_patient_history": "boolean",
  "diagnoses": [
    {
      "type": "PRIMARY",
      "code": "string",
      "name": "string"
    }
  ],
  "items": [
    {
      "claimed_quantity": "number",
      "claimed_amount": "number",
      "provider_deductible_amount": "number",
      "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",
      "duration": "string",
      "frequency": "string",
      "admission_date": "string",
      "discharge_date": "string",
      "justification": "string",
      "erp_item_id": "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",
  "source": "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",
      "unit": "string",
      "start_date": "string",
      "end_date": "string",
      "value_url": "string"
    }
  ],
  "retry": "boolean"
}

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 across related requests	Alphanumeric string, 1-255 characters
transaction_id *	string	Yes	Unique transaction ID for this request; a duplicate value returns an error	Alphanumeric string, 1-255 characters
retry	boolean	No	When true, retries the pipeline for an existing request identified by transaction_id instead of creating a new one	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
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	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 *	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
visit_type	string	No	The visit type of the prior authorization	Enum: NEW_VISIT, FOLLOW_UP, REFILL, WALK_IN, REFERRAL
treatment_date *	string	Yes	The treatment date of the prior authorization	ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
request_date *	string	Yes	The request date of the prior authorization	ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
addition_date *	string	Yes	The member policy addition date	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
is_referral	boolean	No	Flag indicating the request is a referred request from a previous one.	true, false
hcp_appointed_flag	boolean	No	Flag indicating the healthcare provider is appointed to the member	true, false
hcp_moh_flag	boolean	No	Flag indicating the healthcare provider is registered in the Ministry of Health.	true, false
advanced_preauth	boolean	No	Flag indicating advanced pre-authorization	true, false
advanced_preauth_status	string	Conditional	Required when advanced_preauth is true	Enum: ACCEPTED, REJECTED
with_patient_history	boolean	No	Include patient history within the last one year in AI processing. The flag must be "true" in order to process history.	true, false (default: false)
period_start_date	string	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
source	string	No	The source of the prior authorization	String, 1-255 characters
supporting_info	array	No	Array of supporting information objects	See Supporting 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	string	No	Encounter start date	ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
encounter_end_date	string	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	string	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

Diagnosis Object

Parameter	Type	Required	Description	Accepted Values
type *	string	Yes	Type of diagnosis	Enum: PRIMARY, SECONDARY
code *	string	Yes	ICD-10 diagnosis code	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	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	Yes	Quantity of the item	Decimal, minimum 0.0
claimed_amount *	number	Yes	Claimed amount/price of the item	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
admission_date	string	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	string	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
reason_code	string	Conditional	Sent in the request when a prior decision exists. A non-empty value prevents the Najeeb engine from processing the current request, Required when is_referred is true	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
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

Benefit and Sub-Benefit Descriptions

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	String, max 255 characters
code	string	No	Supporting information code	Enum: 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, 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
value	string	No	Value of the supporting information	String, max 1000 characters
unit	string	No	Unit of measurement	String, max 50 characters
start_date	string	No	Start date of the information	ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
end_date	string	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

Enums

Visit Type Enum:

• NEW_VISIT - New visit
• FOLLOW_UP - Follow-up visit
• REFILL - Refill
• WALK_IN - Walk-in visit
• REFERRAL - Referral visit

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

Advanced Prior Authorization Status Enum:

• ACCEPTED - Advanced pre-authorization accepted
• REJECTED - Advanced pre-authorization rejected

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": "MALE",
    "marital_status": "SINGLE",
    "visit_type": "NEW_VISIT",
    "treatment_date": "2024-02-15T10:00:00.000Z",
    "request_date": "2024-02-15T10:04:20.346Z",
    "addition_date": "2024-01-01T00:00:00.000Z",
    "claim_type": "PROFESSIONAL",
    "claim_sub_type": "OUT_PATIENT",
    "is_emergency": false,
    "is_maternity": false,
    "is_new_born": false,
    "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,
        "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_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"
      }
    ]
  }'

Response

Success Response (201 Created)

{
  "approval_request_internal_id": "number",
  "authorization_number": "string",
  "transaction_id": "string",
  "code": 201,
  "message": "Prior authorization 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": "Prior authorization created successfully"
}

Asynchronous Decision

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	Prior authorization already exists with this 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:[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": "Prior authorization 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

1. 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.
2. Diagnoses: A single primary diagnosis is required to support the requested services. You may also send one or multiple secondary diagnoses.
3. Items: Ensure all required item fields are provided, especially service_code, service_description, nphies_code, nphies_type, service_type, claimed_quantity, and claimed_amount
4. Referred Requests: When is_referred is true, every item must include a non-empty reason_code
5. Error Handling: Implement retry logic with exponential backoff for transient errors
6. Validation: Validate data before sending requests to avoid unnecessary API calls
7. Monitoring: Monitor response times and error rates
8. Logging: Log all requests and responses for audit and debugging purposes
9. Timeout Configuration: Set your HTTP client timeout to 50 seconds to accommodate processing time.
10. Supporting Info: Include relevant supporting information (vital signs, lab results, clinical notes) when available to improve AI decision accuracy
11. Retry: Use the retry flag to re-trigger AI processing for an existing request instead of creating a duplicate

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-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",
    "treatment_date": "2024-02-15T10:00:00.000Z",
    "request_date": "2024-02-15T10:04:20.346Z",
    "addition_date": "2024-01-01T00:00:00.000Z",
    "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,
        "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"
  }'

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-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',
    treatment_date: '2024-02-15T10:00:00.000Z',
    request_date: '2024-02-15T10:04:20.346Z',
    addition_date: '2024-01-01T00:00:00.000Z',
    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,
        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);

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-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',
        'treatment_date': '2024-02-15T10:00:00.000Z',
        'request_date': '2024-02-15T10:04:20.346Z',
        'addition_date': '2024-01-01T00:00:00.000Z',
        '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,
                '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 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.