إنتقل إلى المحتوى الرئيسي

Prior Authorization Workflow

This document describes the end-to-end workflow for processing prior authorization requests through the Najeeb AI Engine. It covers the complete lifecycle from data synchronization through request submission, AI-powered adjudication, and final decision handling.

Workflow Overview​

The Prior Authorization workflow follows an asynchronous processing model. Your core system submits a request via the API, the Najeeb AI Engine processes it, and the final decision is delivered via a webhook. A reviewer then updates the authorization status, which records it in the transaction history.

Prior Authorization / Standard Processes preauth requests and validates data against predefined entities for policy holders, policies, members, and medical providers. Failure to sync any of these entities results in errors and prevents creating the request.

Prior Authorization / Lightweight Processes preauth requests without validating predefined entities. Najeeb does not check for the existence of policy holders, policies, members, or medical providers, and automatically creates them while validating the request data.

Phase 1: Data Synchronization - Required only for Standard Preauth​

Before submitting any prior authorization request, all reference data must be synchronized with your Najeeb instance. Missing data will result in 404 Not Found errors at submission time.

Required Entities​

OrderEntityAPI ReferenceWhy It's Needed
1Policy HolderPOST /policy-holder/createParent entity for all policies
2PolicyPOST /policy/createDefines benefits, sub-benefits, and coverage rules
3MemberPOST /policy/patients/addThe patient must be registered and assigned to a policy
4Medical ProviderPOST /medical-provider/createThe provider's CCHI number must exist in the system
5WebhookPOST /webhook/createRequired to receive asynchronous AI decisions
Sync Before Submitting Requests

Failure to sync any of these entities will result in errors such as E_EPH_01 (Policy holder not found), E_EPA_014 (Policy not found), E_EPA_01 (Patient not found), or E_EMP_01 (Medical provider not found).

Phase 2: Request Submission & AI Processing​

Once reference data is synchronized, your core system can submit prior authorization requests. The processing is asynchronous: the API returns an acknowledgment immediately, and the AI Engine delivers the final decision via webhook.

What the AI Engine Evaluates​

During processing, the Najeeb AI Engine performs the following checks:

  • Diagnosis validation -- verifies ICD-10 codes against the Electronic Code List
  • Policy check -- validates member enrollment, and coverage rules
  • Medical necessity -- evaluates service-diagnosis consistency
  • Price list validation -- compares claimed amounts against the configured price list (only if the Price List Module has been activated and synced beforehand)
  • Patient history -- reviews the preceding year of approved authorizations (when with_patient_history: true)
  • Fraud detection -- identifies duplicate requests, suspicious patterns, and inconsistencies
  • Pharmacy (PBM) -- for pharmaceutical items, validates drug codes against the SFDA registry

Webhook Decision Payload​

The AI Engine delivers results with item-level decisions, each containing:

  • decision -- the status for each item (ACCEPTED, REJECTED,PARTIALLY_ACCEPTED )
  • reason_code -- array of detailed reasons with Najeeb AI codes and NPHIES-mapped codes
  • najeeb_ai_alert -- system-generated flags or observations
  • najeeb_ai_score -- AI confidence score
  • approved_quantity / approved_amount -- adjusted values
  • pbm_drug_info -- pharmaceutical details (for drug items)

Phase 3: Review & Update​

After receiving the AI decision via webhook, a reviewer in your system must call the Update Prior Authorization API to finalize the status.

Critical Step

You must call the Update Prior Authorization endpoint to set the final status. This is what records the authorization in the transaction history. Without this call, the prior authorization remains in a pending state and is not reflected in historical records.

Update Status Options​

StatusDescriptionRequired Fields
ACCEPTEDFully approved, all items acceptedstatus, erp_reviewer_id
PARTIALLY_ACCEPTEDSome items approved, some rejectedstatus, erp_reviewer_id, items with individual statuses
REJECTEDEntire authorization rejectedstatus, erp_reviewer_id
REFERREDReferred to another provider or specialiststatus, erp_reviewer_id, referral_cchi_code

Phase 4: Post-Decision Operations​

After a prior authorization has been processed and updated, additional lifecycle operations are available.

Reopen Prior Authorization​

Reopening sends a completed authorization back for reprocessing. Valid reasons include:

ReasonDescription
CORRECTIONCorrecting previously submitted data
ADJUDICATIONRe-adjudication required
MISCALCULATIONFixing a calculation error
BENEFITBenefit-related changes
AUDITAudit-triggered reprocessing
CANCELCancellation-related reopen
OTHEROther reasons

Cancel Prior Authorization​

Cancellation is permanent. Once cancelled, the prior authorization cannot be processed further. Attempting to cancel an already-cancelled authorization returns a 409 Conflict error.

Complete End-to-End Flow​

The following diagram shows the full lifecycle of a prior authorization from start to finish, including all possible paths.

Referral Workflow​

When a prior authorization is referred to another provider, a follow-up request can be submitted linking back to the original authorization.

Key Integration Points​

StepAPI EndpointDocumentation
Prior Authorization / Standard"POST /approval-request/createPrior Authorization
Prior Authorization / Lightweight"POST /approval-request/createPrior Authorization
Retrieve statusGET /approval-request/get-one/:idAPI Reference
Sync NPHIES bundlePATCH /approval-request/bundle/sync/:idAPI Reference
Update decisionPATCH /approval-request/update/:idAPI Reference
ReopenPATCH /approval-request/reopen/:idAPI Reference
CancelPATCH /approval-request/cancel/:idAPI Reference
Sync price list OptionalPOST /price-list/createPrice List
Send Supporting info, including attachments-----Supporting Info APIs Page
Send communications-----Communication APIs Page
Receive decisionsRegister with hook_type: PRE_AUTH_RESULTWebhooks Page