Skip to main content

Prior Authorization / Standard

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

Service Model

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

Service Description​

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

Key Features​

  • AI-Powered Adjudication: Leverage Najeeb's AI Engine for intelligent pre-authorization processing
  • Ephemeral Data Processing: All data is processed temporarily and securely within your isolated Najeeb instance
  • Comprehensive Validation: Built-in validation for diagnoses, medical providers, policies, and benefits
  • Policy Business Logic: Configurable policy validation including member enrollment, network, and benefit checks
  • Patient History: Optional patient history retrieval for more accurate decisions
  • Encounter Details: Full encounter tracking for inpatient and outpatient services
  • Supporting Information: Attach clinical supporting information (vital signs, lab results, etc.)
  • DRG Coding: optionally calculate the claimed and approved AR-DRGs of inpatient requests, check the provider's DRG, and record the settled DRG, with the Pre-auth DRG Coder (drg_enabled)
  • KSA Compliance: Fully compliant with Saudi healthcare and pharmaceutical regulations
  • Scalable Architecture: Handles high volumes of requests with reliable performance

How It Works​

  1. Request Submission: Your core system sends a pre-authorization request to the Najeeb API
  2. Processing: The request is processed within your isolated Najeeb instance with ephemeral data handling
  3. Validation: Automated validation of diagnoses, provider credentials, policy, and member information
  4. AI Analysis: The request is sent to the AI Engine for intelligent adjudication
  5. Response: An acknowledgment is returned with the internal ID and authorization number. The final decision is delivered asynchronously via your configured webhook

Requirements Prior to Integration​

Before integrating with Najeeb Prior Authorization, ensure you have the following:

A. Technical Requirements​

  1. API Access Credentials
  • Valid API key (access-key) provided by Najeeb
  • Access to your dedicated Najeeb instance endpoint
  • Network connectivity to the Najeeb API infrastructure
  1. Data Synchronization Prerequisites

The typical integration flow follows a logical sequence of data setup before transactional operations can begin.

Refer to the Integration Interfaces documentation for detailed API endpoints to create and manage each of these entities.

Sync Before Submitting Requests

Before creating a pre-authorization request, ensure all related entities data has been synchronized with your Najeeb instance. The following entities must exist in the system to process requests without errors:

  1. Policy Holder — must be created first as the parent entity for policies
  2. Policy — must be linked to the policy holder, with category, benefits, and sub-benefits configured
  3. Member — must be registered and assigned to the policy
  4. Medical Provider — the provider's CCHI number must be registered in the system

Failure to sync any of these entities will result in 404 Not Found errors (e.g., E_EPH_01, E_EPA_014, E_EMP_01, E_EPA_015) when submitting a pre-authorization request. See the Error Codes table for the full list.

B. Providing Reference Data Lists​

To ensure accurate processing, the following reference data lists should be shared with the Najeeb technical team before going live:

  1. Medical Providers (preferred) — a list of medical providers including their names and CCHI codes. While providers can be created via the Medical Provider API, sharing the list in advance enables the Najeeb team to pre-load provider data for reporting and validation purposes.History Processing

  2. Policy Categories (Classes) — A coded list of category descriptions ranked by order of importance (priority). These categories are assigned to members upon policy enrollment and are used during claims adjudication to determine applicable benefits and coverage rules.

  3. Benefits and Sub-Benefits (preferred) — a complete list of benefit codes and descriptions, along with their sub-benefit codes and descriptions. These are used during policy template configuration and item-level validation. If not provided in advance, you should include benefit_description and sub_benefit_description in each item of the pre-authorization request so that Najeeb can auto-create the records.

tip

Providing these lists upfront reduces integration friction and avoids runtime errors caused by missing reference data. Contact the Najeeb support team to coordinate the data exchange.

member_id

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

History Processing

To activate member history:

1- you must include "with_patient_history": true in create pre-auth payload.

2- you must update the preauth with the doctor's decision, using the "Auditor Synch Prior Authorization API".z

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

Integration Guide​

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

Asynchronous Processing

The Prior Authorization create endpoint processes requests asynchronously. The API returns an acknowledgment with the internal ID immediately. The Najeeb AI Engine then processes the request, and the final decision is delivered via your configured webhook endpoint.

Base URL​

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

Authentication​

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

access-key: YOUR_API_KEY

For access key provisioning, please contact Najeeb support.

API Endpoint​

Create Prior Authorization Request​

POST /approval-request/create

This endpoint receives a pre-authorization request from your core system and processes it within your isolated Najeeb instance.

Request Headers​
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",
"related_request_date": "date",
"referred_authorization_number": "string",
"is_referred": "boolean",
"medical_provider_cchi_no": "string",
"member_id": "string",
"member_dob": "string",
"member_gender": "Enum Member Gender",
"marital_status": "Enum Marital Status",
"visit_type": "Enum Visit Type",
"request_date": "string",
"claim_type": "Enum Claim Type",
"claim_sub_type": "Enum Claim Sub Type",
"is_emergency": "boolean",
"is_maternity": "boolean",
"is_new_born": "boolean",
"is_referral": "boolean",
"referral_cchi_code": "string",
"referral_valid_days": "number",
"hcp_appointed_flag": "boolean",
"hcp_appointed_as_referred": "boolean",
"hcp_moh_flag": "boolean",
"is_declaration_requested": "boolean",
"is_declaration_clean": "boolean",
"declared_diagnoses": ["string"],
"declaration_attachment": {
  "type": "Enum Attachment Type",
  "value": "string",
  "file_name": "string"
},
"doctor_check": "Enum [Doctor Check"],
"advanced_preauth": "boolean",
"advanced_preauth_status": "Enum Advanced Prior Authorization Status",
"with_patient_history": "boolean",
"diagnoses": 
  {
    "type": "Enum [Diagnosis Type",
    "code": "string",
    "name": "string"
  }
],
"items": [
  {
    "claimed_quantity": "number",
    "claimed_amount": "number",
    "agreed_price": "number",
    "provider_deductible_amount": "number",
    "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",
    "duration": "string",
    "frequency": "OD",
    "treatment_date": "string",
    "justification": "string",
    "erp_item_id": "string",
    "related_diagnosis_codes": ["string"],
    "reason_code": "string",
    "tooth_id": "string",
    "serial_number": "string",
    "nphies_description": "string"
  }
],
"doctor_id": "string",
"doctor_speciality": "string",
"doctor_name": "string",
"approval_remarks": "string",
"referral_remarks": "string",
"additional_remarks": "string",
"internal_referral_notes": "string",
"internal_notes": "string",
"currency": "string",
"currency_rate": "number",
"nphies_bundle_id": "string",
"provider_system_id": "string",
"provider_comment": "string",
"erp_user_id": "string",
"price_list_level": "string",
"period_start_date": "string",
"encounter_id": "string",
"encounter_status": "string",
"encounter_class": "string",
"encounter_priority": "string",
"encounter_start_date": "string",
"encounter_end_date": "string",
"encounter_arrival_code": "string",
"encounter_department": "string",
"encounter_triage_category": "string",
"encounter_triage_date": "string",
"encounter_death_cause": "string",
"encounter_admit_source": "string",
"encounter_length_of_stay": "string",
"encounter_admission": "string",
"encounter_discharge": "string",
"supporting_info": [
  {
    "sequence_number": "number",
    "type": "string",
    "code": "string",
    "value": "string",
    "file_name": "string",
    "unit": "string",
    "start_date": "string",
    "end_date": "string",
    "value_url": "string",
    "related_erp_item_ids": ["string"]
  }
],
"drg_enabled": "boolean",
"provider_drg": {
  "drg_version": "string",
  "drg_code": "string",
  "drg_weight": "number"
},
"drg_info": {
  "separation_mode": "Enum Separation Mode",
  "leave_days": "number",
  "length_of_stay": "number",
  "same_day_flag": "boolean",
  "admission_weight": "number",
  "mechanical_ventilation_hours": "number"
},
"retry": "boolean"
}
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
retrybooleanNoWhen true, re-runs AI processing for the existing request identified by transaction_id instead of creating a new one. The body is still validated in full. Returns 200 (see Retry Response); an unknown transaction_id returns 404 E_EPA_064true, false (default: false)
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 for follow-up requestsAlphanumeric string, max 255 characters
related_request_datedateNoRequest date of the related request (related_authorization_number). Shown in the portal and the prior authorization export; not used in AI processingISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
referred_authorization_numberstringNoThe referred authorization numberAlphanumeric string, max 255 characters
is_referredbooleanNoFlag indicating the request is a referred request from a previous one. When true, all items must include reason_code. Please compare with is_referral
true, false
internal_referral_notesstringNoInternal referral notesAlphanumeric, max 255 characters
internal_notesstringNoInternal notesAlphanumeric, 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
visit_typeEnumNoThe visit type of the prior authorizationEnum: NEW_VISIT, FOLLOW_UP, REFILL, WALK_IN, REFERRAL
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
is_referralbooleanNoFlag indicating the member is requested to be referred to another provider. When true and referral_cchi_code is sent, the request is linked to that referral provider. Please compare with is_referredtrue, false
referral_cchi_codestringNoCCHI code of the referral provider. Used only when is_referral is true: the request is linked to this provider as a referral. An unknown code is rejected with 404 MEDICAL_PROVIDER_NOT_FOUND and nothing is createdAlphanumeric string, max 255 characters
referral_valid_daysnumberNoReferral validity in days, used in AI processing. When is_referral is true and referral_cchi_code is sent, it is also stored as the referral's valid days (0 when absent)Integer, minimum 0
hcp_appointed_flagbooleanNoFlag indicating the healthcare provider is appointed to the membertrue, false
hcp_appointed_as_referredbooleanNoFlag indicating the provider was appointed to the member based on a doctor's referral request (also covers acute medications dispensed at outside pharmacies). Used in AI processingtrue, false (default: false)
hcp_moh_flagbooleanNoFlag indicating the healthcare provider is registered in the Ministry of Health.true, false
is_declaration_requestedbooleanNoFlag indicating a health declaration was requested from the member. When true, the AI applies the declaration check for pre-existing conditions that were not disclosedtrue, false (default: false)
is_declaration_cleanbooleanNoFlag indicating the member's declaration is clean. Evaluated only when is_declaration_requested is truetrue, false (default: 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
doctor_checkarrayNoDoctor manual checks are populated after the doctor reviews the request. This field should be provided in Create Preauth only if the request is advanced; otherwise, it should be supplied in Update Preauth whenever available. Doctor checks are used for AI processing based on historical requests. An empty list or a missing key both mean none, and unknown or repeated values return 400.Array of Doctor Check values: CHRONIC, CONGENITAL, RTA, WORK_RELATED, VACCINATION, PSYCHIATRIC, CHECKUP, INFERTILITY, PREGNANCY
advanced_preauthbooleanNoFlag indicating advanced pre-authorization. For advanced preauth, all services must come with predefined reason codes.true, false
advanced_preauth_statusEnumConditionalRequired when advanced_preauth is trueEnum: ACCEPTED, REJECTED
with_patient_historybooleanNoInclude the member's history in AI processing: previously accepted and partially accepted prior authorizations within the look-back window (365 days by default) ending at the treatment date of the first item. Must be true for history to be processedtrue, false (default: false)
period_start_datedateNoThe period start date of the prior authorizationISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
diagnoses *arrayYesArray of diagnosis objectsA single primary diagnosis is required
items *arrayYesArray of item objectsMinimum one item is required
doctor_idstringNoThe doctor IDAlphanumeric string, 1-255 characters
doctor_specialitystringNoThe doctor's medical specialtyString, 1-255 characters
doctor_namestringNoThe doctor's nameString, 1-255 characters
approval_remarksstringNoDoctor's remarks for prior authorizationFree text, 1-255 characters
referral_remarksstringNoDoctor's remarks for referral requestFree text, 1-255 characters
additional_remarksstringNoDoctor's additional remarks or notesFree text, 1-255 characters
currencystringNoCurrency codeString, 1-255 characters
currency_ratenumberNoCurrency exchange rateDecimal, minimum 0
nphies_bundle_idstringNoThe NPHIES bundle IDAlphanumeric string, 1-255 characters
provider_system_idstringNoProvider system identifierAlphanumeric string, 1-255 characters
provider_commentstringNoProvider commentsFree text, 1-255 characters
erp_user_idstringNoThe ERP user ID who requested the preauthAlphanumeric string, 1-255 characters
price_list_levelstringNoThe price list levelString, 1-255 characters
supporting_infoarrayNoArray of supporting information objectsSee Supporting Info Object
drg_enabledbooleanNoCalculate the claimed and approved AR-DRGs of this request with the Pre-auth DRG Coder. Runs only when claim_sub_type is IN_PATIENT and the Pre-auth DRG Coder is enabled for your account. Never rejects or delays the request. Added with the DRG releasetrue, false (default). null is false
provider_drgobjectNoThe DRG the provider billed. Stored even without drg_enabled. A DRG billed as an item is also found: see Provider DRG on an item. Added with the DRG releaseSee DRG Reference Object
drg_infoobjectNoDRG grouping inputs. Used only when drg_enabled is true. Added with the DRG releaseSee DRG Info Object
Encounter Parameters​
ParameterTypeRequiredDescriptionAccepted Values
encounter_idstringNoEncounter identifierAlphanumeric string, 1-255 characters
encounter_statusstringNoEncounter statusString, 1-255 characters
encounter_classstringNoEncounter classString, 1-255 characters
encounter_prioritystringNoEncounter priorityString, 1-255 characters
encounter_start_datedateNoEncounter start dateISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
encounter_end_datedateNoEncounter end dateISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
encounter_arrival_codestringNoEncounter arrival codeAlphanumeric string, 1-255 characters
encounter_departmentstringNoEncounter departmentString, 1-255 characters
encounter_triage_categorystringNoEncounter triage categoryString, 1-255 characters
encounter_triage_datedateNoEncounter triage dateISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
encounter_death_causestringNoEncounter death causeString, 1-255 characters
encounter_admit_sourcestringNoEncounter admit sourceString, 1-255 characters
encounter_length_of_staystringNoEncounter length of stayString, 1-255 characters
encounter_admissionstringNoEncounter admission detailsString, 1-255 characters
encounter_dischargestringNoEncounter discharge detailsString, 1-255 characters
Encounter dates for DRG coding

When drg_enabled is true and claim_sub_type is IN_PATIENT, send encounter_start_date and encounter_end_date: they are the admission and separation dates the DRG is calculated from. Without them the request is still accepted and processed, but it is not DRG-coded (drg.status ERROR, issue E_DRG_003). encounter_length_of_stay is free text and is not used for DRG coding. See Pre-auth DRG Coder.

Diagnosis Object​
ParameterTypeRequiredDescriptionAccepted Values
type *EnumYesType of diagnosisEnum: PRIMARY, SECONDARY
code *stringYesICD-10 diagnosis code. Items reference it through related_diagnosis_codesValid ICD-10 code format
namestringNoDiagnosis name/descriptionString
Item Object​
ParameterTypeRequiredDescriptionAccepted Values
service_code *stringYesService code of the itemAlphanumeric string, max 255 characters
service_description *stringYesService description of the itemString, max 255 characters
nphies_code *stringYesNPHIES code of the itemAlphanumeric string, max 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 when available, used in AI processing. Without a price list configured by Najeeb, each item is capped at agreed_price as the maximum allowed to be requested from the provider. Send null if undefined (default); sending "0" means it conflicts with the provider contract and is not equivalent to null.Decimal
provider_deductible_amountnumberNoProvider deductible amountDecimal, minimum 0
nphies_descriptionstringNoNPHIES description of the itemString, max 255 characters
durationstringNoDuration of the itemFree text, max 255 characters
frequencystringNoFrequency of the itemFree text (for example OD, BID, TID)
treatment_datedateNoTreatment date of the item.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 item. Supporting information references it through related_erp_item_idsAlphanumeric 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
reason_codestringConditionalreason_code string Conditional — Should be null in standard requests. Required when is_referred or advanced_preauth is true. A non-empty value prevents the Najeeb engine from processing the current request.Alphanumeric string, max 255 characters
benefit_codenumberNoBenefit code of the itemInteger,
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,
sub_benefit_descriptionstringNoSub-benefit description. Used to auto-create the sub-benefit if the code does not exist in the systemString, max 255 characters
tooth_idstringNoTooth identifier (for dental services)Alphanumeric string, max 255 characters
serial_numberstringNoSerial number of the itemAlphanumeric string, max 255 characters
Benefit and Sub-Benefit Descriptions

If benefits and sub-benefits lists have not been provided by the client to the Najeeb team in advance, you must include benefit_description and sub_benefit_description alongside the corresponding codes. Najeeb will use these descriptions to auto-create the benefit or sub-benefit records when the codes do not yet exist in the system.

Supporting Info Object​
ParameterTypeRequiredDescriptionAccepted Values
sequence_numbernumberNoSequence number for orderingInteger, minimum 1
typestringNoType of supporting information. Use ATTACHMENT to upload a file in valueString, max 255 characters
codestringNoSupporting information codeSee Supporting Info Code
valuestringNoValue of the supporting information. When type is ATTACHMENT, send the base64-encoded file content (a data URL is also accepted); the file is stored and its URL is saved insteadString
file_namestringNoOriginal file name when type is ATTACHMENT, used to infer the file extensionString, max 255 characters
unitstringNoUnit of measurementString, max 50 characters
start_datedateNoStart date of the informationISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
end_datedateNoEnd date of the informationISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
value_urlstringNoURL to supporting documentValid HTTP/HTTPS URL, max 500 characters
related_erp_item_idsarrayNoERP item IDs of the items this supporting information relates to, used in AI processing. Every ID must be an items[].erp_item_id of the same request, otherwise the request is rejected with 400Array of unique strings, max 255 characters each
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​

Visit Type Enum:

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

Member Gender Enum:

  • MALE - Male
  • FEMALE - Female

Marital Status Enum:

  • SINGLE - Single
  • MARRIED - Married
  • ENGAGED - Engaged
  • UNKNOWN - Unknown
  • WIDOWED - Widowed
  • DIVORCED - Divorced
  • SEPARATED - Separated

Claim Type Enum:

  • INSTITUTIONAL - Institutional services for inpatients
  • PROFESSIONAL - Professional services for outpatients
  • PHARMACY - Pharmacy services
  • DENTAL - Dental services
  • OPTICAL - Optical services

Claim Sub Type Enum:

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

Diagnosis Type Enum (lower-case values are also accepted):

  • PRIMARY - Primary diagnosis
  • SECONDARY - Secondary diagnosis

Advanced Prior Authorization Status Enum:

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

Doctor Check Enum (doctor_check):

  • CHRONIC - Chronic condition
  • CONGENITAL - Congenital condition
  • RTA - Road traffic accident
  • WORK_RELATED - Work-related injury or condition
  • VACCINATION - Vaccination
  • PSYCHIATRIC - Psychiatric condition
  • CHECKUP - Check-up
  • INFERTILITY - Infertility
  • PREGNANCY - Pregnancy

Supporting Info Code (supporting_info[].code):

Always send the code in upper-case:

Code
INFO
ONSET
ATTACHMENT
MISSING_TOOTH
EMPLOYMENT_IMPACTED
LAB_TEST
REASON_FOR_VISIT
DAYS_SUPPLY
VITAL_SIGN_WEIGHT
VITAL_SIGN_SYSTOLIC
VITAL_SIGN_DIASTOLIC
ICU_HOURS
VENTILATION_HOURS
VITAL_SIGN_HEIGHT
CHIEF_COMPLAINT
CHIEF_COMPLAINTS
BIRTH_WEIGHT
TEMPERATURE
PULSE
OXYGEN_SATURATION
RESPIRATORY_RATE
MORPHOLOGY
LAST_MENSTRUAL_PERIOD
TREATMENT_PLAN
PATIENT_HISTORY
PHYSICAL_EXAMINATION
HISTORY_OF_PRESENT_ILLNESS
ADMISSION_WEIGHT
ESTIMATED_LENGTH_OF_STAY
INVESTIGATION_RESULT
SIGNIFICANT_SIGNS
GENERAL_EXAMINATION
VITAL_INFORMATION
OTHER
Example Request​
curl -X POST "https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/create" \
-H "access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "authorization_number": "AU-12345",
  "transaction_id": "550e8400-e29b-41d4-a716-446655440001",
  "policy_no": "no-01",
  "ph_erp_id": "UAT-policy-id-01",
  "medical_provider_cchi_no": "22697412",
  "member_id": "uat-a-002",
  "member_dob": "1990-01-15T00:00:00.000Z",
  "member_gender": "Enum Member Gender",
  "marital_status": "Enum Marital Status",
  "visit_type": "Enum Visit Type",
  "request_date": "2024-02-15T10:04:20.346Z",
  "claim_type": "Enum Claim Type",
  "claim_sub_type": "Enum Claim Sub Type",
  "is_emergency": false,
  "is_maternity": false,
  "is_new_born": false,
  "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": [
    {
      "claimed_quantity": 1,
      "claimed_amount": 100,
      "treatment_date": "2024-02-15T10:00:00.000Z",
      "provider_deductible_amount": 0,
      "service_code": "FMCARS0008",
      "service_description": "Pharmacological Stress Echocardiography",
      "nphies_code": "55113-00-00",
      "nphies_type": "UNMAPPED CATEGORY",
      "service_type": "UNMAPPED CATEGORY",
      "justification": "Patient requires cardiac assessment",
      "erp_item_id": "ITEM-001",
      "related_diagnosis_codes": ["E40"]
    }
  ],
  "doctor_id": "1",
  "doctor_speciality": "Cardiology",
  "doctor_name": "Dr. Ahmed",
  "approval_remarks": "This is a test prior authorization",
  "additional_remarks": "Patient requires cardiac evaluation",
  "currency": "SAR",
  "currency_rate": 1,
  "provider_system_id": "Provider System ID",
  "provider_comment": "Provider Comment",
  "encounter_status": "active",
  "encounter_class": "outpatient",
  "encounter_department": "Cardiology",
  "supporting_info": [
    {
      "sequence_number": 1,
      "type": "MEDICAL_RECORD",
      "code": "VITAL_SIGN_SYSTOLIC",
      "value": "120",
      "unit": "mmHg",
      "related_erp_item_ids": ["ITEM-001"]
    }
  ]
}'

Response​

Success Response (201 Created)​

{
"approval_request_internal_id": "number",
"authorization_number": "string",
"transaction_id": "string",
"code": 201,
"message": "Approval request created successfully"
}
Response Fields​
FieldTypeDescription
approval_request_internal_idnumberInternal identifier assigned to the request
authorization_numberstringThe authorization number assigned to the request
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"
}

Retry Response (200 OK)​

Returned when the request is sent with "retry": true for an existing transaction_id.

{
"approval_request_internal_id": 12345,
"authorization_number": "AU-12345",
"transaction_id": "550e8400-e29b-41d4-a716-446655440001",
"code": 200,
"message": "Pipeline retry initiated successfully"
}
Asynchronous Decision

The success response confirms the request has been accepted for processing. The AI Engine will process the request asynchronously, and the final decision (approval, rejection, or partial approval) will be delivered via your configured webhook endpoint.

Error Responses​

Error Response Structure​

{
"ErrorCode": "string",
"message": "string",
"details": ["string"]
}

Error Codes​

Error CodeHTTP StatusDescription
E_BAD_REQUEST_400400Request validation failed — see the details array for field-level errors
E_EPH_01404Policy holder not found
E_EPA_014404Policy not found
E_EPA_015404Network not found
E_EPA_02404Diagnosis not found
E_EBA_01404Benefit not found
E_EBA_02404Sub benefit not found
E_EPA_01404Patient not found
E_EMP_01404Medical provider not found
E_EPA_021422Patient not joined to policy
E_EPA_069409A prior authorization already exists with this transaction_id
E_EPA_064404retry is true but no prior authorization exists with this transaction_id
MEDICAL_PROVIDER_NOT_FOUND404is_referral is true and referral_cchi_code does not match a medical provider; nothing is created
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"
]
}

Unknown In-Request Reference:

{
"ErrorCode": "E_BAD_REQUEST_400",
"message": "Bad request",
"details": [
"items[0].related_diagnosis_codes[0] (Z99) must match a diagnoses[].code of the same request",
"supporting_info[0].related_erp_item_ids[0] (ITEM-404) must match an items[].erp_item_id of the same request"
]
}

Referral Provider Not Found:

{
"ErrorCode": "MEDICAL_PROVIDER_NOT_FOUND",
"message": "Medical provider with CCHI code 10000000 not found",
"details": []
}

Diagnosis Not Found:

{
"ErrorCode": "E_EPA_02",
"message": "Diagnosis not found, The codes of the diagnosis are:[Z99]",
"details": []
}

Policy Holder Not Found:

{
"ErrorCode": "E_EPH_01",
"message": "Policy holder not found",
"details": []
}

Policy Not Found:

{
"ErrorCode": "E_EPA_014",
"message": "Policy not found",
"details": []
}

Medical Provider Not Found:

{
"ErrorCode": "E_EMP_01",
"message": "Medical provider not found, The identifier of the medical provider is: 99999",
"details": []
}

Patient Not Joined to Policy:

{
"ErrorCode": "E_EPA_021",
"message": "Patient not joined to policy",
"details": []
}

Duplicate Transaction ID:

{
"ErrorCode": "E_EPA_069",
"message": "Approval request already exists with this transaction_id: 550e8400-e29b-41d4-a716-446655440001",
"details": []
}

Unauthorized:

{
"ErrorCode": "API key is required",
"message": "Unauthorized",
"details": []
}

Data Processing​

All data processing is ephemeral, meaning:

  • Data is processed temporarily within your isolated Najeeb instance
  • No persistent storage of request data (except for audit logs)
  • Data is securely handled and encrypted in transit
  • Compliance with KSA data protection regulations

Best Practices​

  1. Date Formats: Use ISO 8601 format with timezone for all date fields (e.g., 2024-01-15T10:04:20.346Z). All date fields must include the full datetime with timezone — date-only values will be rejected.
  2. Diagnoses: A single primary diagnosis is required to support the requested services. You may also send one or multiple secondary diagnoses.
  3. Items: Ensure all required item fields are provided, especially service_code, service_description, nphies_code, nphies_type, service_type, claimed_quantity, and claimed_amount
  4. Referred Requests: When is_referred is true, every item must include a non-empty reason_code
  5. Error Handling: Implement retry logic with exponential backoff for transient errors
  6. Validation: Validate data before sending requests to avoid unnecessary API calls
  7. Monitoring: Monitor response times and error rates
  8. Logging: Log all requests and responses for audit and debugging purposes
  9. Timeout Configuration: Set your HTTP client timeout to 50 seconds to accommodate processing time.
  10. Supporting Info: Include relevant supporting information (vital signs, lab results, clinical notes) when available to improve AI decision accuracy
  11. Retry: Use the retry flag to re-trigger AI processing for an existing request instead of creating a duplicate
  12. In-Request References: items[].related_diagnosis_codes must point to codes sent in diagnoses, and supporting_info[].related_erp_item_ids must point to erp_item_id values sent in items; send erp_item_id on every item you want to reference
  13. Treatment Date: Send treatment_date on every item. The first item's treatment date is used as the request's treatment date: patient history is evaluated against it and it is returned as treatment_date in PRE_AUTH_RESULT

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-12345",
  "transaction_id": "550e8400-e29b-41d4-a716-446655440001",
  "policy_no": "no-01",
  "ph_erp_id": "UAT-policy-id-01",
  "medical_provider_cchi_no": "22697412",
  "member_id": "uat-a-002",
  "member_dob": "1990-01-15T00:00:00.000Z",
  "member_gender": "Enum Member Gender",
  "marital_status": "Enum Marital Status",
  "visit_type": "Enum Visit Type",
  "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": [
    {
      "claimed_quantity": 1,
      "claimed_amount": 100,
      "treatment_date": "2024-02-15T10:00:00.000Z",
      "provider_deductible_amount": 0,
      "service_code": "FMCARS0008",
      "service_description": "Pharmacological Stress Echocardiography",
      "nphies_code": "55113-00-00",
      "nphies_type": "UNMAPPED CATEGORY",
      "service_type": "UNMAPPED CATEGORY",
      "justification": "Patient requires cardiac assessment"
    }
  ],
  "doctor_speciality": "Cardiology",
  "doctor_name": "Dr. Ahmed",
  "approval_remarks": "This is a test prior authorization",
  "currency": "SAR",
  "currency_rate": 1,
  "provider_system_id": "Provider System ID",
  "provider_comment": "Provider Comment"
}'

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."
  ],
  "issues": [
    {
      "level": "WARNING",
      "code": "SIMILAR_REJECTED_REQUESTS",
      "message": "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": "Enum Visit Type",
  "is_referral": false,
  "referral_provider_cchi_code": null,
  "valid_days": null,
  "referred_at": null,
  "encounter": {
    "encounter_id": null,
    "encounter_status": "active",
    "encounter_class": "outpatient",
    "encounter_priority": null,
    "encounter_start_date": null,
    "encounter_end_date": null,
    "encounter_arrival_code": null,
    "encounter_department": "Cardiology",
    "encounter_triage_category": null,
    "encounter_triage_date": null,
    "encounter_death_cause": null,
    "encounter_admit_source": null,
    "encounter_length_of_stay": null,
    "encounter_admission": null,
    "encounter_discharge": null
  },
  "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.",
      "issues": [],
      "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,
      "decision": "REJECTED",
      "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,
      "issues": [],
      "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
issuesarrayNoRequest-level issues, on every request. Repeats the information of notes and request_alerts in a structured form; both are kept. See Request Issues. Added with the DRG release
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)
provider_drgobjectNoThe provider DRG, with source and validity. Present when one was sent or found. Added with the DRG release
settled_drgobjectNoThe settled DRG, with settled_at. Present when set. Added with the DRG release
drgobjectNomode, and the current claimed and approved DRG results. Present only when the request was sent with drg_enabled: true and is inpatient. See Pre-auth DRG Coder result. Added with the DRG release
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_quantitynumberNoApproved quantity (0 when none)
approved_amountnumberNoApproved amount (0 when none)
pricenumberYesPrice list price of the item. null when your instance runs without a price list
request_amountnumberYesRequested amount
provider_deductible_mountnumberYesProvider deductible amount (the key is spelled provider_deductible_mount)
net_request_amountnumberYesNet requested amount after deductions
rejected_amountnumberNoReserved; currently always 0
price_rejected_amountnumberNoReserved; currently always 0
net_payablenumberYesNet payable amount
decisionstringYesDecision for the item, for example ACCEPTED or REJECTED. See When It Is Sent
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
issuesarrayNoIssues about this item, for example a procedure left out of DRG grouping. Present on every item. Added with the DRG release
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.