Prior Authorization / Lightweight
Najeeb Prior Authorization Lightweight as a Service is a comprehensive pre-authorization processing solution designed to streamline and automate the pre-authorization workflow for insurance companies in the Kingdom of Saudi Arabia.
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.
The "Prior Authorization Lightweight" flow differs from the "Prior Authorization Standard" flow primarily in its validation logic. Unlike Standard mode, the Lightweight flow does not validate member policies, consumption limits, or existing entitlements. Furthermore, it omits pre-creation checks for members, policies, and policy holders, as well as membership join validations. Consequently, if a member or policy does not already exist in Lightweight mode, the system automatically creates it on the fly.
Service Description
Najeeb Prior Authorization Lightweight as a Service provides a seamless API integration that enables insurance companies to submit pre-authorization requests from their core systems and receive adjudicated results in real time. The service handles the entire pre-authorization lifecycle, from initial request submission to AI-powered adjudication, with all processing happening ephemerally within your dedicated, isolated Najeeb instance.
Key Features
- Adjudication: Receive instant responses to pre-authorization submissions
- Ephemeral Data Processing: All data is processed temporarily and securely within your isolated Najeeb instance
- AI-Powered Processing: Leverage Najeeb's AI Engine for intelligent pre-authorization adjudication
- Comprehensive Validation: Built-in validation for diagnoses, medical providers, and service codes
- Automated Validation: Built-in validation for diagnosis codes, service codes, and prescriber information
- KSA Compliance: Fully compliant with Saudi healthcare regulations
- Scalable Architecture: Handles high volumes of requests with reliable performance
Due to this, some capabilities of the full version of the AI Engine will be dropped under this request like:
- Policy and benefits validation
- Network validation
- Member enrollment and join checks
- Contractual rejections due to the lack of price list information
How It Works
- Request Submission: Your core system sends a pre-authorization request to the Najeeb API
- Processing: The request is processed within your isolated Najeeb instance with ephemeral data handling
- Validation: Automated validation of diagnosis codes, service codes, and provider credentials
- Response: Adjudicated result is returned to your system with approval, rejection, or additional requirements
Requirements Prior to Integration
Before integrating with Najeeb Prior Authorization Lightweight as a Service, ensure you have the following:
Technical Requirements
- API Access Credentials
- Valid API key (
access-key) provided by Najeeb - Access to your dedicated Najeeb instance endpoint
- Network connectivity to the Najeeb API infrastructure
- Data Requirements
- Transaction data (authorization number, unique transaction ID, treatment date)
- Policy data (policy number, policy holder ERP ID)
- Medical provider data (CCHI number). For reporting purposes, we recommend sending a list of medical providers (including names and CCHI codes) to the Najeeb technical team in advance.
- Member data (member ID, date of birth, gender, marital status)
- Prescriber information (doctor ID, speciality, name)
- Item/service details (service code, description, NPHIES code and type, quantity, amount)
- Diagnosis codes (ICD-10 format)
Data Preparation
Ensure your system can provide:
- Transaction Data: authorization number, a unique transaction ID
- Policy Data: policy number, policy holder ERP ID
- Member Data: member ID, date of birth, gender, marital status
- Provider Data: medical provider CCHI number, doctor ID/specialty/name
- Item Data: service code, service description, NPHIES code and type, quantity, amount, benefit/sub-benefit codes
- Diagnosis Data: ICD-10 diagnosis codes (primary/secondary)
For the ph_erp_id field, provide your internal policyholder identifier. If this identifier is not available, send the value "default" for all requests.:::
If the member_id was not defined earlier in Najeeb, then Najeeb will create a new member record with the demographics defined in the request member_dob & member_gender.
Important note:
If a member already exists in the system, the existing record will be retained—no duplicate will be created and no overwrite will occur.
However, if you send subsequent requests with the same member_id but differing demographic information, the system will flag a member information inconsistency warning.
transaction_idis the primary idempotency key and must be unique per request; a duplicate value returns an error.authorization_numberis not required to be unique; it can be reused across follow-up requests related to the same authorization.
service_code, service_description, nphies_code, nphies_type, and service_type are all required on every item.
Integration Guide
The Najeeb Prior Authorization Lightweight integration is accomplished through a single API endpoint that receives a pre-authorization request from your insurance company core system. All data processing is ephemeral and handled entirely within your isolated Najeeb instance.
Najeeb offers additional endpoints for synchronizing historical claims and requests made by the member. While integration with these APIs is optional, it allows Najeeb to make more accurate decisions by leveraging the member's past data.
Base URL
https://api.{client_namespace}.najeeb.ai/v4.0/health
Authentication
All API requests are authenticated using an API key passed in a dedicated header:
access-key: YOUR_API_KEY
For access key provisioning, please contact Najeeb support.
API Endpoint
Create Prior Authorization Lightweight Request
POST /approval-request/create
This endpoint receives a prior authorization request from your core system and processes it ephemerally within your isolated Najeeb instance. The request is validated and acknowledged synchronously.
Request Headers
| Header | Type | Required | Description |
|---|---|---|---|
access-key | string | Yes | API key for authentication |
Content-Type | string | Yes | Must be application/json |
Request Body Parameters
The request body is a JSON object with the following structure:
{
"authorization_number": "string",
"transaction_id": "string",
"policy_no": "string",
"ph_erp_id": "string",
"related_authorization_number": "string",
"medical_provider_cchi_no": "string",
"member_id": "string",
"member_dob": "string",
"member_gender": "Enum Member Gender",
"marital_status": "Enum Marital Status",
"request_date": "date",
"claim_type": "Enum Claim Type",
"claim_sub_type": "Enum Claim Sub Type",
"is_emergency": "boolean",
"is_maternity": "boolean",
"is_new_born": "boolean",
"declared_diagnoses": ["string"],
"declaration_attachment": {
"type": "Enum Attachment Type",
"value": "string",
"file_name": "string"
},
"diagnoses":
{
"type": "Enum [Attachment Type",
"code": "string",
"name": "string"
},
{
"type": "Enum Diagnosis Type",
"code": "string",
"name": "string"
}
],
"items": [
{
"claimed_quantity": "number",
"claimed_amount": "number",
"agreed_price": "number",
"duration": "string",
"frequency": "OD",
"treatment_date": "string",
"justification": "string",
"erp_item_id": "string",
"related_diagnosis_codes": ["string"],
"service_code": "string",
"service_description": "string",
"nphies_code": "string",
"nphies_type": "PHARMACEUTICAL",
"service_type": "PHARMACEUTICAL",
"benefit_code": "number",
"benefit_description": "string",
"sub_benefit_code": "number",
"sub_benefit_description": "string",
"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. It can repeat across requests: a new request (new transaction_id) that reuses an existing authorization_number supersedes the earlier request(s), which are marked OVERWRITTEN | Alphanumeric string, 1-255 characters |
transaction_id * | string | Yes | Unique transaction ID for this request (idempotency key). A duplicate value returns 409 E_EPA_069 | Alphanumeric string, 1-255 characters |
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 * | Enum | Yes | The gender of the member | Enum: MALE, FEMALE |
marital_status * | Enum | Yes | The marital status of the member | Enum: SINGLE, MARRIED, ENGAGED, UNKNOWN, WIDOWED, DIVORCED, SEPARATED |
request_date * | date | Yes | The request date of the prior authorization | ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ |
claim_type * | Enum | Yes | The claim type of the prior authorization | Enum: INSTITUTIONAL, PROFESSIONAL, PHARMACY, DENTAL, OPTICAL |
claim_sub_type * | Enum | Yes | The claim sub type of the prior authorization | Enum: IN_PATIENT, OUT_PATIENT, EMERGENCY |
is_emergency | boolean | No | Flag indicating an emergency case | true, false |
is_maternity | boolean | No | Flag indicating a maternity case | true, false |
is_new_born | boolean | No | Flag indicating a newborn case | true, false |
declared_diagnoses | array | No | ICD-10 codes the member declared on the health declaration, independent of diagnoses. Each code must exist in the diagnosis table; an unknown code returns 404 and nothing is created. An empty list or a missing key means none | Array of unique strings, max 255 characters each |
declaration_attachment | object | No | The member's health-declaration document. You can submit files in one of two ways: as a Base64-encoded string, or via a file URL accessible by our server. Null or missing means none | Object: see Declaration Attachment Object |
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 (upper-case PRIMARY, SECONDARY also accepted) |
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 | String, max 255 characters |
service_type * | string | Yes | Service type of the item | String, max 255 characters |
claimed_quantity * | number | Yes | Quantity of the item | Decimal, minimum 0 |
claimed_amount * | number | Yes | Claimed amount/price of the item | Decimal |
agreed_price | number | No | Agreed unit price of the item, used in AI processing. When your instance runs without a price list (configured by Najeeb), each item is priced at agreed_price, and an item without it is priced at 0 | Decimal |
duration | string | No | Duration of the item | Free text |
frequency | string | No | Frequency of the item | Free text (for example OD, BID, TID) |
treatment_date | date | No | Treatment date of the item. Send it on every item: the first item's treatment date is used as the request's treatment date (patient history window and the treatment_date returned in PRE_AUTH_RESULT) | 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 |
related_diagnosis_codes | array | No | Codes of the diagnoses this item relates to, used in AI processing. Every code must be a diagnoses[].code of the same request, otherwise the request is rejected with 400 | Array of unique strings, max 255 characters each |
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 |
The Lightweight request uses the same endpoint as Standard and accepts the same optional fields (for example doctor_check, is_referral with referral_cchi_code, hcp_appointed_as_referred, is_declaration_requested, with_patient_history and supporting_info). See Prior Authorization / Standard for the full list.
Declaration Attachment Object
| Parameter | Type | Required | Description | Accepted Values |
|---|---|---|---|---|
type * | Enum | Yes | How value is read | Enum: BASE64, URL |
value * | string | Yes | Base64 file content (bare, or as a data: URL) when type is BASE64; the file URL when type is URL. Invalid base64 or an empty file returns 400 | String, non-empty |
file_name * | string | Yes | File name shown in the portal and exports. For BASE64, an extension is added from the content when it has none | String, max 255 characters |
Enums
Member Gender Enum:
MALE- MaleFEMALE- Female
Marital Status Enum:
SINGLE- SingleMARRIED- MarriedENGAGED- EngagedUNKNOWN- UnknownWIDOWED- WidowedDIVORCED- DivorcedSEPARATED- Separated
Claim Type Enum:
INSTITUTIONAL- Institutional services for inpatientsPROFESSIONAL- Professional services for outpatientsPHARMACY- Pharmacy servicesDENTAL- Dental servicesOPTICAL- Optical services
Claim Sub Type Enum:
IN_PATIENT- Inpatient servicesOUT_PATIENT- Outpatient servicesEMERGENCY- Emergency services
Diagnosis Type Enum (upper-case values are also accepted):
primary- Primary diagnosissecondary- Secondary diagnosis
Example Request
curl -X POST "https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/create" \
-H "access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"authorization_number": "AU-12345",
"transaction_id": "550e8400-e29b-41d4-a716-446655440001",
"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": "Enum Member Gender",
"marital_status": "Enum Marital Status",
"request_date": "2024-02-15T10:04:20.346Z",
"claim_type": "Enum Claim Type",
"claim_sub_type": "Enum Claim Sub Type",
"diagnoses":
{
"type": "Enum [Diagnosis Type",
"code": "E40",
"name": "Kwashiorkor"
},
{
"type": "Enum Diagnosis Type",
"code": "Z24",
"name": "Need for immunisation against certain single viral diseases"
}
],
"items": [
{
"service_code": "FMCARS0008",
"service_description": "Pharmacological Stress Echocardiography",
"nphies_code": "55113-00-00",
"nphies_type": "AMBULATORY",
"service_type": "AMBULATORY",
"claimed_quantity": 1,
"claimed_amount": 100,
"treatment_date": "2024-02-15T10:00:00.000Z",
"justification": "Patient requires cardiac assessment"
}
],
"doctor_id": "1",
"doctor_speciality": "Cardiology",
"doctor_name": "Dr. Ahmed",
"approval_remarks": "This is a test prior authorization",
"additional_remarks": "Patient requires cardiac evaluation",
"currency": "SAR",
"currency_rate": 1,
"provider_system_id": "Provider System ID",
"provider_comment": "Provider Comment"
}'Note:
claim_typeacceptsINSTITUTIONAL,PROFESSIONAL,PHARMACY,DENTAL, orOPTICAL— adjust to the value that matches the service being submitted.
Response
Success Response (201 Created)
{
"approval_request_internal_id": "number",
"authorization_number": "string",
"transaction_id": "string",
"code": 201,
"message": "string"
}
Response Fields
| Field | Type | Description |
|---|---|---|
approval_request_internal_id | number | Internal identifier assigned to the request |
authorization_number | string | Echoes the submitted authorization number |
transaction_id | string | Echoes the submitted transaction ID |
code | number | HTTP status code (201) |
message | string | Success message |
Example Success Response
{
"approval_request_internal_id": 12345,
"authorization_number": "AU-12345",
"transaction_id": "550e8400-e29b-41d4-a716-446655440001",
"code": 201,
"message": "Approval request created successfully"
}
The success response confirms the request was accepted for processing. The AI Engine then processes it, and the decision (request alerts, item decisions and rejection reasons) is delivered to your configured webhook endpoint. See Webhook Response.
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 | A 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:[0]",
"details": []
}
Duplicate Prior Authorization:
{
"ErrorCode": "E_EPA_069",
"message": "Approval request already exists with this transaction_id: 550e8400-e29b-41d4-a716-446655440001",
"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
- Date Formats: Use ISO 8601 format with timezone for all date fields (e.g.,
2024-01-15T10:04:20.346Z) - Diagnoses: A single primary diagnosis is required to support the requested services. You may also send one or multiple additional diagnoses.
- Items: Ensure all required item fields are provided:
service_code,service_description,nphies_code,nphies_type,service_type,claimed_quantityandclaimed_amount - Error Handling: Implement retry logic with exponential backoff for transient errors
- Validation: Validate data before sending requests to avoid unnecessary API calls
- Monitoring: Monitor response times and error rates
- Logging: Log all requests and responses for audit and debugging purposes
- Timeout Configuration: Set your HTTP client timeout to 50 seconds to accommodate AI Engine processing time.
Code Examples
- cURL
- JavaScript
- Python
curl -X POST "https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/create" \
-H "access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"authorization_number": "AU-12sdfghj2",
"transaction_id": "transaction_id3",
"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": "Enum Member Gender",
"marital_status": "Enum Marital Status",
"request_date": "2025-12-29T11:41:30.625Z",
"claim_type": "Enum Claim Type",
"claim_sub_type": "Enum Claim Sub Type",
"diagnoses":
{
"type": "Enum [Diagnosis Type",
"code": "E40"
},
{
"type": "Enum Diagnosis Type",
"code": "Z24",
"name": "Need for immunisation against certain single viral diseases"
}
],
"items": [
{
"service_code": "40903-00-00",
"service_description": "Neuroendoscopy",
"service_type": "AMBULATORY",
"nphies_code": "40903-00-00",
"nphies_type": "AMBULATORY",
"claimed_quantity": 1,
"claimed_amount": 500,
"treatment_date": "2025-12-29T11:41:30.625Z"
}
]
}'const response = await fetch('https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/create', {
method: 'POST',
headers: {
'access-key': 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
authorization_number: 'AU-12sdfghj2',
transaction_id: 'transaction_id3',
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',
request_date: '2025-12-29T11:41:30.625Z',
claim_type: 'PROFESSIONAL',
claim_sub_type: 'OUT_PATIENT',
diagnoses: [
{ type: 'primary', code: 'E40' },
{ type: 'secondary', code: 'Z24', name: 'Need for immunisation against certain single viral diseases' },
],
items: [
{
service_code: '40903-00-00',
service_description: 'Neuroendoscopy',
service_type: 'AMBULATORY',
nphies_code: '40903-00-00',
nphies_type: 'AMBULATORY',
claimed_quantity: 1,
claimed_amount: 500,
treatment_date: '2025-12-29T11:41:30.625Z',
},
],
}),
});
const result = await response.json();
console.log(result);
import requests
response = requests.post(
'https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/create',
headers={
'access-key': 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
json={
'authorization_number': 'AU-12sdfghj2',
'transaction_id': 'transaction_id3',
'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',
'request_date': '2025-12-29T11:41:30.625Z',
'claim_type': 'PROFESSIONAL',
'claim_sub_type': 'OUT_PATIENT',
'diagnoses': [
{'type': 'primary', 'code': 'E40'},
{'type': 'secondary', 'code': 'Z24', 'name': 'Need for immunisation against certain single viral diseases'},
],
'items': [
{
'service_code': '40903-00-00',
'service_description': 'Neuroendoscopy',
'service_type': 'AMBULATORY',
'nphies_code': '40903-00-00',
'nphies_type': 'AMBULATORY',
'claimed_quantity': 1,
'claimed_amount': 500,
'treatment_date': '2025-12-29T11:41:30.625Z',
},
],
},
)
result = response.json()
print(result)
Webhook Response (Najeeb Decision Result)
After the Najeeb Engine finishes processing a prior authorization request, Najeeb delivers the decision to your configured webhook endpoint as an HTTP POST. This is the asynchronous response referenced in the Integration Guide.
To receive the Najeeb decision, register a webhook with hook_type set to PRE_AUTH_RESULT. See Webhook for registration details.
When It Is Sent
The PRE_AUTH_RESULT webhook is sent in two cases. The payload shape is the same; the values differ as follows.
| After AI processing | After a reviewer decision in the Najeeb portal | |
|---|---|---|
| When | The AI Engine finishes processing the request, including after a retry | A reviewer submits the decision for the request in the Najeeb portal |
status | The AI decision for the request (ACCEPTED, PARTIALLY_ACCEPTED or REJECTED). Falls back to the request status while no AI decision exists | The reviewer's final status for the request |
items_decisions[].decision | The AI decision for the item. An item sent on create with a predefined reason_code keeps its own decision | The reviewer's status for the item |
items_decisions[].status | Same value as decision | null |
| Automation fields | Set by the automation rules (see Automation Fields) | is_request_automated and is_item_automated are false; both notes are null |
reason_code | The item's reasons whose source is enabled for push in your instance settings. Reasons sent on create with a predefined reason_code are returned unchanged when that setting is enabled | All reasons of the item |
By default the payload is wrapped in an envelope: event_type (always PRE_AUTH_RESULT) at the root and the result under data. A webhook configured with the flat response type receives the data object only. Contact Najeeb support to change the response type.
Response Payload Structure
The example below is a result sent after AI processing: the first item was accepted and automated, the second was rejected and needs review, so the request is not automated.
{
"event_type": "PRE_AUTH_RESULT",
"data": {
"pre_auth_internal_id": 161081,
"transaction_id": "550e8400-e29b-41d4-a716-446655440001",
"authorization_number": "AU-12345",
"nphies_reopen_at": null,
"nphies_reopen_reason": null,
"submitter_erp_id": null,
"approval_remarks": "This is a test prior authorization",
"referral_remarks": null,
"internal_referral_notes": null,
"is_referred": false,
"is_request_automated": false,
"request_automation_note": null,
"internal_notes": null,
"request_alerts": [
"A prior authorization for the same diagnosis and service was previously submitted and rejected."
],
"status": "PARTIALLY_ACCEPTED",
"reviewer_erp_id": null,
"member_id": "uat-a-002",
"source": null,
"is_emergency": false,
"is_new_born": false,
"is_maternity": false,
"related_authorization_number": null,
"claim_type": null,
"treatment_date": "2024-02-15T10:00:00.000Z",
"period_start_date": null,
"doctor_id": "1",
"doctor_name": "Dr. Ahmed",
"doctor_speciality": "Cardiology",
"nphies_bundle_id": null,
"provider_system_id": "Provider System ID",
"provider_comment": "Provider Comment",
"ERP_user_id": null,
"price_list_level": null,
"patient_id": "uat-a-002",
"medical_provider_cchi_no": "22697412",
"ph_erp_id": "UAT-policy-id-01",
"currency": "SAR",
"currency_rate": 1,
"is_reviewer_accepted_as_road_traffic_accident": false,
"is_traffic_accident": false,
"assign_to_erp_id": null,
"additional_remarks": "Patient requires cardiac evaluation",
"total_recovery_utilized": 0,
"total_exgratia_utilized": 0,
"benefit_code": null,
"visit_type": "NewVisit",
"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": [
{
"id": 501,
"item_erp_id": "ITEM-001",
"service_code": "FMCARS0008",
"duration": null,
"frequency": null,
"admission_date": null,
"discharge_date": null,
"approved_quantity": 1,
"approved_amount": 100,
"price": 100,
"request_amount": 100,
"provider_deductible_mount": 0,
"net_request_amount": 100,
"rejected_amount": 0,
"price_rejected_amount": 0,
"net_payable": 100,
"decision": "ACCEPTED",
"status": "ACCEPTED",
"warning_message": null,
"benefit_code": 10,
"sub_benefit_code": 1001,
"reason_code": [],
"najeeb_ai_alert": "",
"najeeb_ai_score": null,
"is_item_automated": true,
"item_automation_note": "This item was accepted automatically by the system.",
"pbm_drug_info": null,
"treatment_date": null
},
{
"id": 502,
"item_erp_id": "ITEM-002",
"service_code": "9-420-05",
"duration": null,
"frequency": "OD",
"admission_date": null,
"discharge_date": null,
"approved_quantity": 0,
"approved_amount": 0,
"price": 1871.95,
"request_amount": 1871.95,
"provider_deductible_mount": 0,
"net_request_amount": 1871.95,
"rejected_amount": 0,
"price_rejected_amount": 0,
"net_payable": 0,
"status": "REJECTED",
"warning_message": null,
"benefit_code": 10,
"sub_benefit_code": 1001,
"reason_code": [
{
"najeeb_ai_code": "AD-2-5",
"najeeb_ai_description": "Time limit for submission has expired",
"najeeb_ai_message": "The time difference between the treatment date and the request date is more than 24 hours.",
"nphies_code": "AD-2-5",
"nphies_description": "Time limit for submission has expired",
"special_case_amount": null,
"erp_code": null,
"is_approved": false,
"severity": null,
"source": "RULES"
}
],
"najeeb_ai_alert": "Diagnosis \"Z24\" is invalid / inactive as per the ICD AM 10th Ed. Electronic Code List Edits.",
"najeeb_ai_score": 0,
"is_item_automated": false,
"item_automation_note": null,
"pbm_drug_info": {
"id": 3210,
"sfda_code": "9-420-05",
"name": "Hepsera 10 mg tablet",
"scientific_name": "adefovir dipivoxil",
"manufacture_name": "Hepsera",
"pharmaceutical_form": "Tablet",
"strength": "10",
"unit": "mg",
"package_size": "30.000",
"price": 1871.95
},
"treatment_date": null
}
]
}
}
Parameter Details
All date-time values are ISO 8601 strings in UTC (for example 2024-02-15T10:00:00.000Z).
Root Level Parameters
| Parameter | Type | Nullable | Description |
|---|---|---|---|
event_type | string | No | Webhook event identifier. Always PRE_AUTH_RESULT. Sent only with the default envelope |
pre_auth_internal_id | number | No | Najeeb internal identifier of the prior authorization |
transaction_id | string | Yes | The transaction_id sent on create |
authorization_number | string | Yes | The authorization_number sent on create |
nphies_reopen_at | string | Yes | Date-time the request was reopened through NPHIES |
nphies_reopen_reason | string | Yes | Reason for reopening through NPHIES |
submitter_erp_id | string | Yes | ERP ID of the reviewer of the request |
approval_remarks | string | Yes | Approval remarks of the request |
referral_remarks | string | Yes | Referral remarks of the request |
internal_referral_notes | string | Yes | Internal referral notes |
is_referred | boolean | Yes | The is_referred flag of the request |
is_request_automated | boolean | No | true only when every item of the request is automated. See Automation Fields |
request_automation_note | string | Yes | Explains the request's automation. Sent only when is_request_automated is true, otherwise null |
internal_notes | string | Yes | Internal notes of the request |
request_alerts | array of strings | No | Request-level alerts and notes generated during processing |
status | string | Yes | Decision status of the request. See When It Is Sent |
reviewer_erp_id | string | Yes | ERP ID of the reviewer of the request |
member_id | string | Yes | The member ID |
source | string | Yes | Source of the request, when recorded. null for requests created through the integration API |
is_emergency | boolean | Yes | Emergency flag of the request |
is_new_born | boolean | Yes | Newborn flag of the request |
is_maternity | boolean | Yes | Maternity flag of the request |
related_authorization_number | string | Yes | The related_authorization_number sent on create |
claim_type | string | Yes | Reserved; currently always null |
treatment_date | date | Yes | Treatment date of the request (the treatment date of its first item) |
period_start_date | date | Yes | The period_start_date sent on create |
doctor_id | string | Yes | The doctor ID |
doctor_name | string | Yes | The doctor's name |
doctor_speciality | string | Yes | The doctor's medical specialty |
nphies_bundle_id | string | Yes | The NPHIES bundle ID |
provider_system_id | string | Yes | Provider system identifier |
provider_comment | string | Yes | Provider comments |
ERP_user_id | string | Yes | The erp_user_id sent on create |
price_list_level | string | Yes | The price list level |
patient_id | string | Yes | The member ID (same value as member_id) |
medical_provider_cchi_no | string | Yes | CCHI number of the medical provider |
ph_erp_id | string | Yes | ERP ID of the policy holder |
currency | string | Yes | Currency code |
currency_rate | number | Yes | Currency exchange rate |
is_reviewer_accepted_as_road_traffic_accident | boolean | Yes | Whether the reviewer accepted the case as a road traffic accident |
is_traffic_accident | boolean | Yes | Whether the case is flagged as a road traffic accident |
assign_to_erp_id | string | Yes | ERP ID of the user the request is assigned to |
additional_remarks | string | Yes | Additional remarks of the request |
total_recovery_utilized | number | No | Total recovery amount utilized (0 when none) |
total_exgratia_utilized | number | No | Total ex-gratia amount utilized (0 when none) |
benefit_code | number | Yes | Reserved; currently always null. Benefit codes are sent per item |
visit_type | string | Yes | Visit type of the request: NewVisit, FollowUp, Refill, WalkIn or Referral |
is_referral | boolean | No | Whether the request is linked to a referral provider |
referral_provider_cchi_code | string | Yes | CCHI code of the referral provider when the request is referred |
valid_days | number | Yes | Referral validity in days |
referred_at | string | Yes | Date-time the request was referred |
encounter | object | Yes | Encounter details (see Encounter Object) |
items_decisions | array | No | One decision per item (see Item Decision Object) |
Encounter Object
Echoes the encounter fields sent on create; each is null when not sent.
| Parameter | Type | Nullable | Description |
|---|---|---|---|
encounter_id | string | Yes | Encounter identifier |
encounter_status | string | Yes | Encounter status |
encounter_class | string | Yes | Encounter class |
encounter_priority | string | Yes | Encounter priority |
encounter_start_date | date | Yes | Encounter start date |
encounter_end_date | date | Yes | Encounter end date |
encounter_arrival_code | string | Yes | Encounter arrival code |
encounter_department | string | Yes | Encounter department |
encounter_triage_category | string | Yes | Encounter triage category |
encounter_triage_date | date | Yes | Encounter triage date |
encounter_death_cause | string | Yes | Encounter death cause |
encounter_admit_source | string | Yes | Encounter admit source |
encounter_length_of_stay | string | Yes | Encounter length of stay |
encounter_admission | string | Yes | Encounter admission details |
encounter_discharge | string | Yes | Encounter discharge details |
Item Decision Object
Each entry in items_decisions is the decision for one item of the request.
| Parameter | Type | Nullable | Description |
|---|---|---|---|
id | number | No | Najeeb internal identifier of the item |
item_erp_id | string | Yes | The erp_item_id sent on create |
service_code | string | Yes | Service code of the item. When the AI mapped the item to another service, the mapped service's code |
duration | string | Yes | Approved duration |
frequency | string | Yes | Frequency of the item |
admission_date | date | Yes | Kept for compatibility; always null |
discharge_date | date | Yes | Kept for compatibility; always null |
approved_quantity | number | 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 |
status | string | Yes | Same value as decision after AI processing; null after a reviewer decision in the portal |
warning_message | string | Yes | Reserved; currently always null |
benefit_code | number | Yes | Benefit code of the item |
sub_benefit_code | number | Yes | Sub-benefit code of the item |
reason_code | array | Yes | Reasons for the decision (see Reason Code Object). Empty array when the item has none |
najeeb_ai_alert | string | No | AI alerts and notes for the item, joined with commas. Empty string when there are none |
najeeb_ai_score | number | Yes | Najeeb AI score for the item |
is_item_automated | boolean | No | true when the automation rules let you apply this item's decision without review. See Automation Fields |
item_automation_note | string | Yes | Explains the item's automation. Sent only when is_item_automated is true, otherwise null |
pbm_drug_info | object | Yes | Drug details when the item is a pharmaceutical product (see PBM Drug Info Object), otherwise null |
treatment_date | date | Yes | Reserved; currently always null. Use the root treatment_date |
Reason Code Object
Each entry in reason_code is one reason for the item decision.
| Parameter | Type | Nullable | Description |
|---|---|---|---|
najeeb_ai_code | string | Yes | Najeeb reason code |
najeeb_ai_description | string | Yes | Description of the reason |
najeeb_ai_message | string | Yes | Detailed message explaining why the reason applies to this item |
nphies_code | string | Yes | NPHIES reason code the Najeeb reason maps to |
nphies_description | string | Yes | Description of the NPHIES reason |
special_case_amount | number | Yes | Amount linked to the reason, when the reason concerns an amount |
erp_code | string | Yes | Your ERP code for the reason, when one is mapped |
is_approved | boolean | Yes | true when the reason code starts with 00 (an approval reason) |
severity | string | Yes | Severity level of the reason, as returned by the AI (PBM checks) |
source | string | Yes | Where the reason came from, for example AI, RULES, PBM, PORTAL or INTEGRATION |
PBM Drug Info Object
Present only when the item is a pharmaceutical product.
| Parameter | Type | Nullable | Description |
|---|---|---|---|
id | number | No | Najeeb internal identifier of the drug |
sfda_code | string | No | SFDA drug code |
name | string | No | Drug name |
scientific_name | string | Yes | Scientific (generic) name |
manufacture_name | string | Yes | Manufacturer name |
pharmaceutical_form | string | Yes | Pharmaceutical form (for example tablet, capsule, injection) |
strength | string | Yes | Drug strength |
unit | string | Yes | Unit of measurement |
package_size | string | Yes | Package size |
price | number | Yes | Drug price |
Automation Fields
The automation rules configured for your instance decide, per item, whether you can apply the decision without a manual review.
| Level | Flag | Note when the flag is true | Note when the flag is false |
|---|---|---|---|
| Item | is_item_automated | item_automation_note, for example This item was rejected automatically by the system. Due to [ AD-2-5 | Time limit for submission has expired ] (one bracket per reason; no "Due to" part when the item has no reason) | null |
| Request | is_request_automated (true only when every item is automated) | request_automation_note, for example This request was accepted automatically by the system, as all items were accepted. | null |
Each item's note follows that item's own flag, so an automated item still carries its note when the request as a whole is not automated.
Example Webhook Payload
See also the PRE_AUTH_RESULT example on the Webhook page.