Najeeb PBM Lightweight as a Service

Najeeb PBM Lightweight as a Service (Pharmacy Benefit Management) is a comprehensive pharmacy claims processing solution designed to streamline and automate the adjudication of prescription drug claims 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.

PBM MODES

The "PBM Lightweight" flow differs from the "PBM Full-Mode" flow primarily in its validation logic. Unlike Full-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 PBM Lightweight as a Service provides a seamless API integration that enables insurance companies to submit pharmacy claims from their core systems (or directly from network pharmacies) and receive adjudicated results in real time. The service handles the entire prescription claim lifecycle, from formulary and drug utilization checks to final approval or rejection, with all processing happening ephemerally within your dedicated, isolated Najeeb instance.

Key Features

• Adjudication: Receive instant responses to pharmacy claim submissions
• Ephemeral Data Processing: All data is processed temporarily and securely within your isolated Najeeb instance
• Formulary Management: Automated checks against the insurance plan's drug formulary
• Drug Utilization Review (DUR): Built-in checks for drug interactions, duplicate therapy, and quantity limits
• Automated Validation: Built-in validation for drug codes and prescriber information
• KSA Compliance: Fully compliant with Saudi healthcare and pharmaceutical 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
• Contractual rejections due to the lack of price list information

How It Works

1. Request Submission: Your core system or dispensing pharmacy sends a pharmacy claim to the Najeeb API
2. Processing: The request is processed within your isolated Najeeb instance with ephemeral data handling
3. Validation: Automated validation of drug codes, formulary status, and prescriber credentials
4. Response: Adjudicated result is returned to your system with approval, rejection, or additional requirements

Requirements Prior to Integration

Before integrating with Najeeb PBM 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, transaction type, 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)
• Diagnosis codes (ICD-10 format)

Data Preparation

Ensure your system can provide:

• Transaction Data: authorization number, a unique transaction ID, transaction type (PREAUTH or CLAIM)
• 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, price, 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 PBM 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 PBM integration is accomplished through a single API endpoint that receives a PBM (pharmacy benefit management) prior authorization 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 PBM Request

POST /approval-request/create-pbm-request

This endpoint receives a PBM prior authorization 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",
  "erp_id": "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",
      "price": "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
erp_id	string	No	ERP identifier for this request (may not be unique)	Alphanumeric string, max 255 characters
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: PHARMACEUTICAL, DEVICE
service_type *	string	Yes	Service type of the item	Enum: PHARMACEUTICAL, DEVICE
claimed_quantity	number	No	Quantity of the item (defaults to 1 if not sent)	Integer, 1-1000000000
price	number	No	Price of the item (set by the PBM service)	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-pbm-request" \
  -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": "CLAIM",
    "erp_id": "123",
    "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": "PHARMACY",
    "claim_sub_type": "OUT_PATIENT",
    "diagnoses": [
      {
        "type": "primary",
        "code": "E11.9",
        "name": "Type 2 diabetes mellitus without complications"
      }
    ],
    "items": [
      {
        "service_code": "SFDA-778812",
        "service_description": "Glucophage 500mg",
        "nphies_code": "SFDA-778812",
        "nphies_type": "Metformin",
        "service_type": "PHARMACY",
        "claimed_quantity": 60,
        "justification": ""
      }
    ],
    "approval_remarks": "This is a test prior authorization",
    "additional_remarks": "Routine refill",
    "currency": "SAR",
    "currency_rate": 1,
    "provider_system_id": "Provider System ID",
    "provider_comment": "Provider Comment"
  }'

Note: claim_type accepts PHARMACY for prescription/pharmacy claims — adjust to the value that matches the claim 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": "0810246017",
      "approved": true,
      "approved_quantity": 30,
      "approved_duration": "30",
      "najeeb_ai_alert": "",
      "rejection_reason": []
    },
    {
      "service_code": "1012258766",
      "approved": false,
      "approved_quantity": 10,
      "approved_duration": "7",
      "najeeb_ai_alert": "Drug interaction detected",
      "rejection_reason": [
        {
          "code": "PBM-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 prescribed therapy. 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. Caching: Cache formulary 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. 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-pbm-request" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "authorization_number": "AU-12sdfghj2",
    "transaction_id": "transaction_id3",
    "transaction_type": "PREAUTH",
    "erp_id": "123",
    "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": "Neuroendoscopy"
      }
    ]
  }'

JavaScript

const response = await fetch('https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/create-pbm-request', {
  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',
    erp_id: '123',
    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: 'Neuroendoscopy',
      },
    ],
  }),
});

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-pbm-request',
    headers={
        'access-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'authorization_number': 'AU-12sdfghj2',
        'transaction_id': 'transaction_id3',
        'transaction_type': 'PREAUTH',
        'erp_id': '123',
        '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': 'Neuroendoscopy',
            },
        ],
    },
)

result = response.json()
print(result)