Skip to main content

Prior Authorization / Lightweight

Najeeb Prior Authorization Lightweight as a Service is a comprehensive pre-authorization processing solution designed to streamline and automate the pre-authorization workflow for insurance companies in the Kingdom of Saudi Arabia.

Service Model

This Service enables the utilization of the AI Engine capabilities without having to store any sensitive data outside the Insurance Company Network, as all the data submitted is processed ephemerally.

Prior Authorization MODES

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

Service Description​

Najeeb Prior Authorization Lightweight as a Service provides a seamless API integration that enables insurance companies to submit pre-authorization requests from their core systems and receive adjudicated results in real time. The service handles the entire pre-authorization lifecycle, from initial request submission to AI-powered adjudication, with all processing happening ephemerally within your dedicated, isolated Najeeb instance.

Key Features​

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

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

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

How It Works​

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

Requirements Prior to Integration​

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

Technical Requirements​

  1. API Access Credentials
  • Valid API key (access-key) provided by Najeeb
  • Access to your dedicated Najeeb instance endpoint
  • Network connectivity to the Najeeb API infrastructure
  1. Data Requirements
  • Transaction data (authorization number, unique transaction ID, treatment date)
  • Policy data (policy number, policy holder ERP ID)
  • Medical provider data (CCHI number). For reporting purposes, we recommend sending a list of medical providers (including names and CCHI codes) to the Najeeb technical team in advance.
  • Member data (member ID, date of birth, gender, marital status)
  • Prescriber information (doctor ID, speciality, name)
  • Item/service details (service code, description, NPHIES code and type, quantity, amount)
  • Diagnosis codes (ICD-10 format)

Data Preparation​

Ensure your system can provide:

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

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

member_id

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

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

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

Integration Guide​

The Najeeb Prior Authorization Lightweight integration is accomplished through a single API endpoint that receives a pre-authorization request from your insurance company core system. All data processing is ephemeral and handled entirely within your isolated Najeeb instance.

Historical Data Synch

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

Base URL​

https://api.{client_namespace}.najeeb.ai/v4.0/health

Authentication​

All API requests are authenticated using an API key passed in a dedicated header:

access-key: YOUR_API_KEY

For access key provisioning, please contact Najeeb support.

API Endpoint​

Create Prior Authorization Lightweight Request​

POST /approval-request/create

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

Request Headers​
HeaderTypeRequiredDescription
access-keystringYesAPI key for authentication
Content-TypestringYesMust 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​
ParameterTypeRequiredDescriptionAccepted Values
authorization_number *stringYesThe 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 OVERWRITTENAlphanumeric string, 1-255 characters
transaction_id *stringYesUnique transaction ID for this request (idempotency key). A duplicate value returns 409 E_EPA_069Alphanumeric string, 1-255 characters
policy_no *stringYesThe policy number of the prior authorizationAlphanumeric string, 1-255 characters
ph_erp_id *stringYesThe ERP ID of the policy holder.String, 1-255 characters
related_authorization_numberstringNoThe related authorization number of the prior authorizationAlphanumeric string, max 255 characters
medical_provider_cchi_no *stringYesThe CCHI number of the medical providerAlphanumeric string, 1-255 characters
member_id *stringYesThe member ID of the prior authorizationAlphanumeric string, 1-255 characters
member_dob *stringYesMember date of birthISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
member_gender *EnumYesThe gender of the memberEnum: MALE, FEMALE
marital_status *EnumYesThe marital status of the memberEnum: SINGLE, MARRIED, ENGAGED, UNKNOWN, WIDOWED, DIVORCED, SEPARATED
request_date *dateYesThe request date of the prior authorizationISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
claim_type *EnumYesThe claim type of the prior authorizationEnum: INSTITUTIONAL, PROFESSIONAL, PHARMACY, DENTAL, OPTICAL
claim_sub_type *EnumYesThe claim sub type of the prior authorizationEnum: IN_PATIENT, OUT_PATIENT, EMERGENCY
is_emergencybooleanNoFlag indicating an emergency casetrue, false
is_maternitybooleanNoFlag indicating a maternity casetrue, false
is_new_bornbooleanNoFlag indicating a newborn casetrue, false
declared_diagnosesarrayNoICD-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 noneArray of unique strings, max 255 characters each
declaration_attachmentobjectNoThe 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 noneObject: see Declaration Attachment Object
diagnoses *arrayYesArray of diagnosis objectsMinimum 1 diagnosis required
items *arrayYesArray of item objectsMinimum one item is required
doctor_idstringNoThe doctor ID of the prior authorizationAlphanumeric string, max 255 characters
doctor_specialitystringNoThe doctor's medical specialtyString, max 255 characters
doctor_namestringNoThe doctor's nameString, max 255 characters
approval_remarksstringNoRemarks for approvalFree text, max 255 characters
additional_remarksstringNoAdditional remarks or notesFree text, max 255 characters
currencystringNoCurrency codeString, max 255 characters
currency_ratenumberNoCurrency exchange rateDecimal, minimum 0
nphies_bundle_idstringNoThe NPHIES bundle ID of the prior authorizationAlphanumeric string, max 255 characters
provider_system_idstringNoProvider system identifierAlphanumeric string, max 255 characters
provider_commentstringNoProvider commentsFree text, max 255 characters
erp_user_idstringNoThe ERP user ID of the prior authorizationAlphanumeric string, max 255 characters
price_list_levelstringNoThe price list level of the prior authorizationAlphanumeric string, max 255 characters
Diagnosis Object​
ParameterTypeRequiredDescriptionAccepted Values
type *EnumYesType of diagnosisEnum: primary, secondary (upper-case PRIMARY, SECONDARY also accepted)
code *stringYesICD-10 diagnosis codeValid ICD-10 code format, max 255 characters
namestringNoDiagnosis name/descriptionString, max 255 characters
Item Object​
ParameterTypeRequiredDescriptionAccepted Values
service_code *stringYesService code of the itemAlphanumeric string, 1-255 characters
service_description *stringYesService description of the itemString, 1-255 characters
nphies_code *stringYesNPHIES code of the itemAlphanumeric string, 1-255 characters
nphies_type *stringYesNPHIES type of the itemString, max 255 characters
service_type *stringYesService type of the itemString, max 255 characters
claimed_quantity *numberYesQuantity of the itemDecimal, minimum 0
claimed_amount *numberYesClaimed amount/price of the itemDecimal
agreed_pricenumberNoAgreed 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 0Decimal
durationstringNoDuration of the itemFree text
frequencystringNoFrequency of the itemFree text (for example OD, BID, TID)
treatment_datedateNoTreatment 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
justificationstringNoMedical justification for the itemFree text, max 255 characters
erp_item_idstringNoERP item ID of the itemAlphanumeric string, max 255 characters
related_diagnosis_codesarrayNoCodes 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 400Array of unique strings, max 255 characters each
benefit_codenumberNoBenefit code of the itemInteger, 0-9999999
benefit_descriptionstringNoBenefit description. Used to auto-create the benefit if the code does not exist in the systemString, max 255 characters
sub_benefit_codenumberNoSub benefit code of the itemInteger, 0-9999999
sub_benefit_descriptionstringNoSub-benefit description. Used to auto-create the sub-benefit if the code does not exist in the systemString, max 255 characters
serial_numberstringNoSerial number of the itemAlphanumeric string, max 255 characters
Optional Fields

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​
ParameterTypeRequiredDescriptionAccepted Values
type *EnumYesHow value is readEnum: BASE64, URL
value *stringYesBase64 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 400String, non-empty
file_name *stringYesFile name shown in the portal and exports. For BASE64, an extension is added from the content when it has noneString, max 255 characters
Enums​

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 (upper-case values are also accepted):

  • primary - Primary diagnosis
  • secondary - Secondary diagnosis
Example Request​
curl -X POST "https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/create" \
-H "access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "authorization_number": "AU-12345",
  "transaction_id": "550e8400-e29b-41d4-a716-446655440001",
  "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_type accepts INSTITUTIONAL, PROFESSIONAL, PHARMACY, DENTAL, or OPTICAL — 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​
FieldTypeDescription
approval_request_internal_idnumberInternal identifier assigned to the request
authorization_numberstringEchoes the submitted authorization number
transaction_idstringEchoes the submitted transaction ID
codenumberHTTP status code (201)
messagestringSuccess 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"
}
Decision Delivery

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 CodeHTTP StatusDescription
E_BAD_REQUEST_400400Request validation failed — see the details array for field-level errors
E_EPA_02404Diagnosis not found
E_EPA_069409A prior authorization already exists with this transaction_id
401 Unauthorized401Missing 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​

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

Code Examples​

curl -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"
    }
  ]
}'

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.

Webhook Configuration

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 processingAfter a reviewer decision in the Najeeb portal
WhenThe AI Engine finishes processing the request, including after a retryA reviewer submits the decision for the request in the Najeeb portal
statusThe AI decision for the request (ACCEPTED, PARTIALLY_ACCEPTED or REJECTED). Falls back to the request status while no AI decision existsThe reviewer's final status for the request
items_decisions[].decisionThe AI decision for the item. An item sent on create with a predefined reason_code keeps its own decisionThe reviewer's status for the item
items_decisions[].statusSame value as decisionnull
Automation fieldsSet by the automation rules (see Automation Fields)is_request_automated and is_item_automated are false; both notes are null
reason_codeThe 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 enabledAll reasons of the item
Envelope

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​

ParameterTypeNullableDescription
event_typestringNoWebhook event identifier. Always PRE_AUTH_RESULT. Sent only with the default envelope
pre_auth_internal_idnumberNoNajeeb internal identifier of the prior authorization
transaction_idstringYesThe transaction_id sent on create
authorization_numberstringYesThe authorization_number sent on create
nphies_reopen_atstringYesDate-time the request was reopened through NPHIES
nphies_reopen_reasonstringYesReason for reopening through NPHIES
submitter_erp_idstringYesERP ID of the reviewer of the request
approval_remarksstringYesApproval remarks of the request
referral_remarksstringYesReferral remarks of the request
internal_referral_notesstringYesInternal referral notes
is_referredbooleanYesThe is_referred flag of the request
is_request_automatedbooleanNotrue only when every item of the request is automated. See Automation Fields
request_automation_notestringYesExplains the request's automation. Sent only when is_request_automated is true, otherwise null
internal_notesstringYesInternal notes of the request
request_alertsarray of stringsNoRequest-level alerts and notes generated during processing
statusstringYesDecision status of the request. See When It Is Sent
reviewer_erp_idstringYesERP ID of the reviewer of the request
member_idstringYesThe member ID
sourcestringYesSource of the request, when recorded. null for requests created through the integration API
is_emergencybooleanYesEmergency flag of the request
is_new_bornbooleanYesNewborn flag of the request
is_maternitybooleanYesMaternity flag of the request
related_authorization_numberstringYesThe related_authorization_number sent on create
claim_typestringYesReserved; currently always null
treatment_datedateYesTreatment date of the request (the treatment date of its first item)
period_start_datedateYesThe period_start_date sent on create
doctor_idstringYesThe doctor ID
doctor_namestringYesThe doctor's name
doctor_specialitystringYesThe doctor's medical specialty
nphies_bundle_idstringYesThe NPHIES bundle ID
provider_system_idstringYesProvider system identifier
provider_commentstringYesProvider comments
ERP_user_idstringYesThe erp_user_id sent on create
price_list_levelstringYesThe price list level
patient_idstringYesThe member ID (same value as member_id)
medical_provider_cchi_nostringYesCCHI number of the medical provider
ph_erp_idstringYesERP ID of the policy holder
currencystringYesCurrency code
currency_ratenumberYesCurrency exchange rate
is_reviewer_accepted_as_road_traffic_accidentbooleanYesWhether the reviewer accepted the case as a road traffic accident
is_traffic_accidentbooleanYesWhether the case is flagged as a road traffic accident
assign_to_erp_idstringYesERP ID of the user the request is assigned to
additional_remarksstringYesAdditional remarks of the request
total_recovery_utilizednumberNoTotal recovery amount utilized (0 when none)
total_exgratia_utilizednumberNoTotal ex-gratia amount utilized (0 when none)
benefit_codenumberYesReserved; currently always null. Benefit codes are sent per item
visit_typestringYesVisit type of the request: NewVisit, FollowUp, Refill, WalkIn or Referral
is_referralbooleanNoWhether the request is linked to a referral provider
referral_provider_cchi_codestringYesCCHI code of the referral provider when the request is referred
valid_daysnumberYesReferral validity in days
referred_atstringYesDate-time the request was referred
encounterobjectYesEncounter details (see Encounter Object)
items_decisionsarrayNoOne decision per item (see Item Decision Object)

Encounter Object​

Echoes the encounter fields sent on create; each is null when not sent.

ParameterTypeNullableDescription
encounter_idstringYesEncounter identifier
encounter_statusstringYesEncounter status
encounter_classstringYesEncounter class
encounter_prioritystringYesEncounter priority
encounter_start_datedateYesEncounter start date
encounter_end_datedateYesEncounter end date
encounter_arrival_codestringYesEncounter arrival code
encounter_departmentstringYesEncounter department
encounter_triage_categorystringYesEncounter triage category
encounter_triage_datedateYesEncounter triage date
encounter_death_causestringYesEncounter death cause
encounter_admit_sourcestringYesEncounter admit source
encounter_length_of_staystringYesEncounter length of stay
encounter_admissionstringYesEncounter admission details
encounter_dischargestringYesEncounter discharge details

Item Decision Object​

Each entry in items_decisions is the decision for one item of the request.

ParameterTypeNullableDescription
idnumberNoNajeeb internal identifier of the item
item_erp_idstringYesThe erp_item_id sent on create
service_codestringYesService code of the item. When the AI mapped the item to another service, the mapped service's code
durationstringYesApproved duration
frequencystringYesFrequency of the item
admission_datedateYesKept for compatibility; always null
discharge_datedateYesKept for compatibility; always null
approved_quantitynumberYesThe approved quantity for this item
approved_amountnumberYesThe approved amount for this item
pricenumberYesPrice list price for the item
request_amountnumberYesThe originally requested amount
provider_deductible_amountnumberYesProvider deductible amount
net_request_amountnumberYesNet requested amount after deductions
rejected_amountnumberYesThe rejected amount for this item
price_rejected_amountnumberYesThe price-based rejected amount
net_payablenumberYesNet payable amount
approval_remarksstringYesRemarks for approval
statusstringYesSame value as decision after AI processing; null after a reviewer decision in the portal
warning_messagestringYesReserved; currently always null
benefit_codenumberYesBenefit code of the item
sub_benefit_codenumberYesSub-benefit code of the item
reason_codearrayYesReasons for the decision (see Reason Code Object). Empty array when the item has none
najeeb_ai_alertstringNoAI alerts and notes for the item, joined with commas. Empty string when there are none
najeeb_ai_scorenumberYesNajeeb AI score for the item
is_item_automatedbooleanNotrue when the automation rules let you apply this item's decision without review. See Automation Fields
item_automation_notestringYesExplains the item's automation. Sent only when is_item_automated is true, otherwise null
pbm_drug_infoobjectYesDrug details when the item is a pharmaceutical product (see PBM Drug Info Object), otherwise null
treatment_datedateYesReserved; currently always null. Use the root treatment_date

Reason Code Object​

Each entry in reason_code is one reason for the item decision.

ParameterTypeNullableDescription
najeeb_ai_codestringYesNajeeb reason code
najeeb_ai_descriptionstringYesDescription of the reason
najeeb_ai_messagestringYesDetailed message explaining why the reason applies to this item
nphies_codestringYesNPHIES reason code the Najeeb reason maps to
nphies_descriptionstringYesDescription of the NPHIES reason
special_case_amountnumberYesAmount linked to the reason, when the reason concerns an amount
erp_codestringYesYour ERP code for the reason, when one is mapped
is_approvedbooleanYestrue when the reason code starts with 00 (an approval reason)
severitystringYesSeverity level of the reason, as returned by the AI (PBM checks)
sourcestringYesWhere 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.

ParameterTypeNullableDescription
idnumberNoNajeeb internal identifier of the drug
sfda_codestringNoSFDA drug code
namestringNoDrug name
scientific_namestringYesScientific (generic) name
manufacture_namestringYesManufacturer name
pharmaceutical_formstringYesPharmaceutical form (for example tablet, capsule, injection)
strengthstringYesDrug strength
unitstringYesUnit of measurement
package_sizestringYesPackage size
pricenumberYesDrug price

Automation Fields​

The automation rules configured for your instance decide, per item, whether you can apply the decision without a manual review.

LevelFlagNote when the flag is trueNote when the flag is false
Itemis_item_automateditem_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
Requestis_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.