Najeeb Pre-auth as a Service

Najeeb Pre-auth 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 witout having to store any sensitive data outside the Insurance Company Network as all the data submitted is processed Ephemeraly.

Service Description

Najeeb Pre-auth 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 in real-time. The service handles the entire pre-authorization lifecycle, from initial request submission to final approval or rejection, with all processing happening ephemerally through the API gateway offered by ELM.

Key Features

• Real-time Processing: Receive instant responses to pre-authorization requests
• Ephemeral Data Processing: All data is processed temporarily and securely through the ELM API gateway
• Automated Validation: Built-in validation for medical codes, provider information, and patient eligibility
• Comprehensive Coverage: Support for all types of medical procedures and services
• KSA Compliance: Fully compliant with Saudi healthcare regulations and standards
• Scalable Architecture: Handles high volumes of requests with reliable performance

this is a ligtweigt 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
• Contractual rejections Due to the lack of Price List Information
• Patient History Checking
• Service Frequescny checking
• member Data Consistancy checks

How It Works

1. Request Submission: Your core system sends pre-authorization data to the Najeeb API
2. Processing: The request is processed through the ELM API gateway with ephemeral data handling
3. Validation: Automated validation of medical codes, provider credentials, and patient eligibility
4. Response: Processed result is returned to your system with approval, rejection, or additional requirements

Requirements Prior to Integration

Before integrating with Najeeb Pre-auth as a Service, ensure you have the following:

Technical Requirements

1. API Access Credentials

   • Valid Client ID and Client Secret provided by Najeeb
   • Access to the ELM API gateway endpoint
   • Network connectivity to the Najeeb API infrastructure

2. System Capabilities

   • Ability to make HTTPS REST API calls
   • Support for JSON request/response format
   • Error handling and retry logic implementation
   • Secure credential storage

3. Data Requirements

   • Patient information (no personaly identifiable data is needed, insurance details)
   • encounter information (in-patient, dates, refferal ....)
   • Provider information (provider type)
   • Service details (Medical codes, procedure descriptions)
   • Diagnosis codes (ICD-10 format)

Business Requirements

1. Insurance Company Registration

   • Valid insurance company license in KSA
   • Active provider network agreements
   • Compliance with KSA healthcare regulations

2. Integration Agreement

   • Signed service agreement with Najeeb
   • Defined service level agreements (SLAs)
   • Support and maintenance terms

3. Testing Environment

   • Access to sandbox/test environment for integration testing
   • Test data and scenarios prepared
   • UAT (User Acceptance Testing) plan

Data Preparation

Ensure your system can provide:

• Patient Data: date of birth, gender, martial status, insurance policy details
• Provider Data: type, specialties
• Service Data: Medical procedure codes (CPT, HCPCS), descriptions, quantities
• Diagnosis Data: ICD-10 diagnosis codes
• Authorization Details: Requested service date, urgency level, clinical notes, dates

System Architecture

The following diagram illustrates the system architecture and data flow for Najeeb Pre-auth as a Service:

Architecture Components

1. Insurance Company Core System

   • Your internal system that initiates pre-authorization requests
   • Handles business logic and data preparation
   • Manages API integration and response handling

2. ELM API Gateway

   • Provides secure API gateway services
   • Handles authentication and authorization
   • Manages routing and load balancing
   • Ensures ephemeral data processing
   • handles billing and rate limiting

3. Najeeb Pre-auth Service

   • Core processing engine for pre-authorization requests
   • Medical code validation and mapping
   • Provider and patient eligibility verification
   • Business rule engine for approval/rejection logic

4. External Systems

   • Provider databases
   • Medical code repositories
   • Regulatory compliance systems
   • GPU Servers "TBD"

Integration Guide

The Najeeb Pre-auth as a Service integration is accomplished through a single API endpoint that receives pre-authorization data from your insurance company core system and returns the processed result. All data processing is ephemeral and handled through the ELM API gateway.

Base URL

https://api.elm.sa/najeeb/v1

Authentication

All API requests require OAuth 2.0 authentication. Include the access token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

For authentication details, please contact Najeeb support.

API Endpoint

Submit Pre-authorization Request

POST /pre-auth/process

This endpoint receives pre-authorization data from your core system, processes it ephemerally through the ELM API gateway, and returns the processed result.

Request Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	Must be application/json
X-Request-ID	string	No	Unique request identifier for tracking

Request Body Parameters

The request body is a JSON object with the following structure:

{
  "authorization_number": "string",
  "advanced_preauth": "boolean",
  "advanced_preauth_status": "string",
  "related_authorization_number": "string",
  "medical_provider_type": "string",
  "member_dob": "string",
  "member_gender": "string",
  "marital_status": "string",
  "is_vip": "boolean",
  "policy_start_date": "string",
  "addition_date": "string",
  "treatment_date": "string",
  "request_date": "string",
  "hcp_appointed_flag": "boolean",
  "hcp_moh_flag": "boolean",
  "claim_type": "string",
  "claim_sub_type": "string",
  "is_emergency": "boolean",
  "is_maternity": "boolean",
  "is_new_born": "boolean",
  "is_referral": "boolean",
  "diagnoses": ["object"],
  "items": ["object"],
  "doctor_speciality": "string",
  "approval_remarks": "string",
  "additional_remarks": "string",
  "currency": "string",
  "currency_rate": "number",
  "provider_system_id": "string",
  "provider_comment": "string",
  "encounter_status": "string",
  "encounter_start_date": "string",
  "encounter_end_date": "string",
  "encounter_arrival_code": "string",
  "encounter_department": "string",
  "encounter_death_cause": "string",
  "encounter_admit_source": "string",
  "encounter_length_of_stay": "string",
  "encounter_admission": "string",
  "encounter_discharge": "string",
  "supporting_info": ["object"]
}

Parameter Details

Root Level Parameters

Parameter	Type	Required	Description	Accepted Values
authorization_number	string	No	Pre-existing authorization number for related requests	Alphanumeric string
advanced_preauth	boolean	No	Flag indicating if this is an advanced pre-authorization	true, false
advanced_preauth_status	string	No	Status of advanced pre-authorization	Enum: ACCEPTED, REJECTED, PENDING
related_authorization_number	string	No	Related authorization number for linked requests	Alphanumeric string
medical_provider_type	string	Yes	Type of medical provider	Enum: CLINIC, HOSPITAL, PHARMACY, LABORATORY, RADIOLOGY
member_dob	string	Yes	Member date of birth	ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
member_gender	string	Yes	Member gender	Enum: MALE, FEMALE
marital_status	string	No	Member marital status	Enum: SINGLE, MARRIED, DIVORCED, WIDOWED
is_vip	boolean	No	Flag indicating VIP member status	true, false
policy_start_date	string	Yes	Insurance policy start date	ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
addition_date	string	Yes	Date when member was added to policy	ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
treatment_date	string	Yes	Proposed treatment/service date	ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
request_date	string	Yes	Date of pre-authorization request	ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
hcp_appointed_flag	boolean	No	Flag indicating if HCP is appointed	true, false
hcp_moh_flag	boolean	No	Flag indicating if HCP is MOH registered	true, false
claim_type	string	Yes	Type of claim	Enum: PROFESSIONAL, INSTITUTIONAL
claim_sub_type	string	Yes	Sub-type of claim	Enum: OUT_PATIENT, IN_PATIENT, EMERGENCY
is_emergency	boolean	No	Flag indicating emergency case	true, false
is_maternity	boolean	No	Flag indicating maternity case	true, false
is_new_born	boolean	No	Flag indicating new born case	true, false
is_referral	boolean	No	Flag indicating referral case	true, false
diagnoses	array	Yes	Array of diagnosis objects	Minimum 1 diagnosis required
items	array	Yes	Array of service/item objects	Minimum 1 item required
doctor_speciality	string	No	Doctor's medical specialty	String (e.g., "Cardiology", "Orthopedics")
approval_remarks	string	No	Remarks for approval	Free text, max 2000 characters
additional_remarks	string	No	Additional remarks or notes	Free text, max 2000 characters
currency	string	No	Currency code	ISO 4217 format (default: SAR)
currency_rate	number	No	Currency exchange rate	Decimal, default: 1
provider_system_id	string	No	Provider system identifier	Alphanumeric string
provider_comment	string	No	Provider comments	Free text, max 2000 characters
encounter_status	string	No	Encounter status	Enum: active, completed, cancelled
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 (e.g., "A01")
encounter_department	string	No	Encounter department	String (e.g., "Cardiology")
encounter_death_cause	string	No	Cause of death (if applicable)	Free text
encounter_admit_source	string	No	Admission source	String (e.g., "Referral", "Emergency")
encounter_length_of_stay	string	No	Length of stay	String (e.g., "5 days")
encounter_admission	string	No	Admission details	Free text
encounter_discharge	string	No	Discharge details	Free text
supporting_info	array	No	Array of supporting information objects	See Supporting Info Object below

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	Yes	Diagnosis name/description	String, max 500 characters

Item Object

Parameter	Type	Required	Description	Accepted Values
claimed_quantity	number	Yes	Quantity of items claimed	Integer, minimum 1
claimed_amount	number	Yes	Claimed amount per unit	Decimal, minimum 0, 2 decimal places
duration	string	No	Duration of treatment	String (e.g., "10 days")
admission_date	string	No	Admission date (for in-patient)	ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
frequency	string	No	Frequency of service	String (e.g., "10 times", "daily")
discharge_date	string	No	Discharge date (for in-patient)	ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
justification	string	No	Medical justification for service	Free text, max 2000 characters
erp_item_id	string	No	ERP system item identifier	Alphanumeric string
service_code	string	Yes	Service code identifier	Alphanumeric string
service_description	string	Yes	Service description	String, max 500 characters
nphies_code	string	No	NPHIES code	Alphanumeric string format
nphies_type	string	No	NPHIES type/category	String (e.g., "UNMAPPED CATEGORY")
service_type	string	No	Service type/category	String (e.g., "UNMAPPED CATEGORY")
tooth_id	string	No	Tooth identifier (for dental services)	Alphanumeric string (e.g., "1001")

Supporting Info Object

Parameter	Type	Required	Description	Accepted Values
sequence_number	number	Yes	Sequence number for ordering	Integer, minimum 1
type	string	Yes	Type of supporting information	Enum: MEDICAL_RECORD, LAB_RESULT, IMAGING, PRESCRIPTION, OTHER
code	string	No	Code identifier	Alphanumeric string
value	string	No	Value or description	Free text
unit	string	No	Unit of measurement	String (e.g., "mmHg", "mg/dL")
start_date	string	No	Start date of information	ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
end_date	string	No	End date of information	ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
value_url	string	No	URL to supporting document	Valid URL format

Enums

Advanced Pre-auth Status Enum:

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

Medical Provider Type Enum:

• CLINIC - Clinic
• HOSPITAL - Hospital
• PHARMACY - Pharmacy
• LABORATORY - Laboratory
• RADIOLOGY - Radiology center

Member Gender Enum:

• MALE - Male
• FEMALE - Female

Marital Status Enum:

• SINGLE - Single
• MARRIED - Married
• DIVORCED - Divorced
• WIDOWED - Widowed

Claim Type Enum:

• PROFESSIONAL - Professional services
• INSTITUTIONAL - Institutional services

Claim Sub Type Enum:

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

Diagnosis Type Enum:

• primary - Primary diagnosis
• secondary - Secondary diagnosis

Encounter Status Enum:

• active - Active encounter
• completed - Completed encounter
• cancelled - Cancelled encounter

Supporting Info Type Enum:

• MEDICAL_RECORD - Medical record
• LAB_RESULT - Laboratory result
• IMAGING - Imaging study
• PRESCRIPTION - Prescription
• OTHER - Other supporting information

Example Request

curl -X POST "https://api.elm.sa/najeeb/v1/pre-auth/process" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: req-123456789" \
  -d '{
    "authorization_number": "AU-12345",
    "advanced_preauth": false,
    "advanced_preauth_status": "ACCEPTED",
    "related_authorization_number": "AU-12344",
    "medical_provider_type": "CLINIC",
    "member_dob": "1990-01-15T00:00:00.000Z",
    "member_gender": "MALE",
    "marital_status": "SINGLE",
    "is_vip": false,
    "policy_start_date": "2024-01-01T00:00:00.000Z",
    "addition_date": "2024-01-01T00:00:00.000Z",
    "treatment_date": "2024-02-15T10:00:00.000Z",
    "request_date": "2024-01-16T10:04:20.346Z",
    "hcp_appointed_flag": false,
    "hcp_moh_flag": true,
    "claim_type": "PROFESSIONAL",
    "claim_sub_type": "OUT_PATIENT",
    "is_emergency": false,
    "is_maternity": false,
    "is_new_born": false,
    "is_referral": 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,
        "duration": "10 days",
        "admission_date": "2024-02-15T08:00:00.000Z",
        "frequency": "10 times",
        "discharge_date": "2024-02-25T18:00:00.000Z",
        "justification": "Patient requires pharmacological stress echocardiography for cardiac assessment",
        "erp_item_id": "16562",
        "service_code": "FMCARS0008",
        "service_description": "Pharmacological Stress Echocardiography",
        "nphies_code": "55113-00-00",
        "nphies_type": "UNMAPPED CATEGORY",
        "service_type": "UNMAPPED CATEGORY",
        "tooth_id": null
      }
    ],
    "doctor_speciality": "Cardiology",
    "approval_remarks": "This is a test approval request",
    "additional_remarks": "Patient has been experiencing chest pain and requires cardiac evaluation",
    "currency": "SAR",
    "currency_rate": 1,
    "provider_system_id": "Provider System ID",
    "provider_comment": "Provider Comment",
    "encounter_status": "active",
    "encounter_start_date": "2024-02-15T08:00:00.000Z",
    "encounter_end_date": "2024-02-15T12:00:00.000Z",
    "encounter_arrival_code": "A01",
    "encounter_department": "Cardiology",
    "encounter_death_cause": null,
    "encounter_admit_source": "Referral",
    "encounter_length_of_stay": "4 hours",
    "encounter_admission": "Patient admitted for cardiac evaluation",
    "encounter_discharge": "Patient discharged after successful evaluation",
    "supporting_info": [
      {
        "sequence_number": 1,
        "type": "MEDICAL_RECORD",
        "code": "MR001",
        "value": "Blood pressure reading: 120/80 mmHg",
        "unit": "mmHg",
        "start_date": "2024-01-01T00:00:00.000Z",
        "end_date": "2024-12-31T23:59:59.000Z",
        "value_url": "https://example.com/document.pdf"
      }
    ]
  }'

Response

Success Response

The API returns a processed result with approval, rejection, or conditional approval status.

Response Structure

{
  "request_id": "string",
  "authorization_number": "string",
  "status": "string",
  "decision_date": "string",
  "approved_services": [
    {
      "code": "string",
      "description": "string",
      "quantity": "number",
      "approved_quantity": "number",
      "approved_cost": "number",
      "coverage_percentage": "number"
    }
  ],
  "rejected_services": [
    {
      "code": "string",
      "description": "string",
      "rejection_reason": "string"
    }
  ],
  "conditions": [
    {
      "type": "string",
      "description": "string",
      "required_action": "string"
    }
  ],
  "authorization_valid_until": "string",
  "notes": "string",
  "processing_time_ms": "number"
}

Response Fields

Field	Type	Description
request_id	string	The original request ID
authorization_number	string	Unique authorization number if approved
status	string	Processing status (see Status Enum below)
decision_date	string	Date and time of decision (ISO 8601)
approved_services	array	Array of approved service objects
rejected_services	array	Array of rejected service objects
conditions	array	Array of conditions or requirements
authorization_valid_until	string	Expiration date of authorization (ISO 8601)
notes	string	Additional notes or comments
processing_time_ms	number	Processing time in milliseconds

Status Enum

• approved - Request fully approved
• partially_approved - Some services approved, others rejected
• rejected - Request rejected
• pending_review - Requires manual review
• requires_additional_info - Additional information needed

Example Success Response

{
  "request_id": "req-123456789",
  "authorization_number": "AUTH-2024-001234",
  "status": "approved",
  "decision_date": "2024-01-16T10:30:00Z",
  "approved_services": [
    {
      "code": "CPT-27447",
      "description": "Total knee arthroplasty",
      "quantity": 1,
      "approved_quantity": 1,
      "approved_cost": 50000.00,
      "coverage_percentage": 80
    }
  ],
  "rejected_services": [],
  "conditions": [
    {
      "type": "provider_verification",
      "description": "Provider must verify patient identity before procedure",
      "required_action": "Verify patient ID at time of service"
    }
  ],
  "authorization_valid_until": "2024-03-15T23:59:59Z",
  "notes": "Authorization approved. Patient must present valid ID at time of service.",
  "processing_time_ms": 1250
}

Error Responses

Error Response Structure

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {
      "field": "string",
      "reason": "string",
      "accepted_values": ["string"]
    }
  },
  "request_id": "string",
  "timestamp": "string"
}

Error Codes

Error Code	HTTP Status	Description	Resolution
INVALID_REQUEST	400	Request validation failed	Check request parameters and format
MISSING_REQUIRED_FIELD	400	Required field is missing	Include all required fields
INVALID_FIELD_VALUE	400	Field value is invalid	Check accepted values and enums
INVALID_DATE_FORMAT	400	Date format is invalid	Use ISO 8601 format with timezone (YYYY-MM-DDTHH:mm:ss.sssZ)
INVALID_SERVICE_CODE	400	Service code is invalid or not recognized	Verify service code format
INVALID_DIAGNOSIS_CODE	400	Diagnosis code is invalid	Use valid ICD-10 format
INVALID_ENUM_VALUE	400	Enum value is not accepted	Check enum values in documentation
INVALID_NPHIES_CODE	400	NPHIES code format is invalid	Verify NPHIES code format
MISSING_DIAGNOSIS	400	At least one diagnosis is required	Include at least one primary diagnosis
MISSING_ITEMS	400	At least one item is required	Include at least one item in items array
INVALID_DIAGNOSIS_TYPE	400	Diagnosis type must be 'primary' or 'secondary'	Use valid diagnosis type
UNAUTHORIZED	401	Authentication failed	Verify access token
FORBIDDEN	403	Insufficient permissions	Contact support for access
PROVIDER_NOT_FOUND	404	Provider not found or inactive	Verify provider information
POLICY_EXPIRED	422	Insurance policy has expired	Verify policy dates
POLICY_NOT_ACTIVE	422	Insurance policy is not active	Check policy start date
SERVICE_NOT_COVERED	422	Service is not covered under policy	Review policy coverage
INVALID_ENCOUNTER_STATUS	422	Encounter status is invalid	Use valid encounter status
RATE_LIMIT_EXCEEDED	429	Too many requests	Implement rate limiting
INTERNAL_ERROR	500	Internal server error	Retry request or contact support
SERVICE_UNAVAILABLE	503	Service temporarily unavailable	Retry after delay

Example Error Responses

Invalid Enum Value:

{
  "error": {
    "code": "INVALID_ENUM_VALUE",
    "message": "Invalid medical provider type value",
    "details": {
      "field": "medical_provider_type",
      "reason": "Value must be one of: CLINIC, HOSPITAL, PHARMACY, LABORATORY, RADIOLOGY",
      "accepted_values": ["CLINIC", "HOSPITAL", "PHARMACY", "LABORATORY", "RADIOLOGY"]
    }
  },
  "request_id": "req-123456789",
  "timestamp": "2024-01-16T10:30:00Z"
}

Missing Required Field:

{
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "Required field is missing",
    "details": {
      "field": "medical_provider_type",
      "reason": "Medical provider type is required"
    }
  },
  "request_id": "req-123456789",
  "timestamp": "2024-01-16T10:30:00Z"
}

Invalid Date Format:

{
  "error": {
    "code": "INVALID_DATE_FORMAT",
    "message": "Date format is invalid",
    "details": {
      "field": "member_dob",
      "reason": "Date must be in ISO 8601 format with timezone (YYYY-MM-DDTHH:mm:ss.sssZ)",
      "accepted_values": ["ISO 8601 format: 2024-01-15T10:04:20.346Z"]
    }
  },
  "request_id": "req-123456789",
  "timestamp": "2024-01-16T10:30:00Z"
}

Missing Diagnosis:

{
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "At least one diagnosis is required",
    "details": {
      "field": "diagnoses",
      "reason": "Diagnoses array must contain at least one diagnosis object with type 'primary'"
    }
  },
  "request_id": "req-123456789",
  "timestamp": "2024-01-16T10:30:00Z"
}

Missing Items:

{
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "At least one item is required",
    "details": {
      "field": "items",
      "reason": "Items array must contain at least one item object"
    }
  },
  "request_id": "req-123456789",
  "timestamp": "2024-01-16T10:30:00Z"
}

Data Processing

All data processing is ephemeral, meaning:

• Data is processed temporarily through the ELM API gateway
• No persistent storage of request data (except for audit logs)
• Results are returned immediately after processing
• Data is securely handled and encrypted in transit
• Compliance with KSA data protection regulations

Rate Limits

• Standard Tier: 100 requests per minute
• Enterprise Tier: Custom limits based on agreement

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1642248000

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: Include at least one primary diagnosis; secondary diagnoses are optional but recommended
3. Items: Ensure all required item fields are provided, especially service_code and service_description
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. Caching: Cache authorization results when appropriate to reduce API calls
7. Monitoring: Monitor response times and error rates
8. Logging: Log all requests and responses for audit and debugging purposes
9. Supporting Info: Include relevant supporting information (medical records, lab results) when available to improve approval chances

Next Steps

• Getting Started Guide - Begin your integration
• Error Handling - Handle errors properly