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.

Phase 1: Data Synchronization

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

Order	Entity	API Reference	Why It's Needed
1	Policy Holder	POST /policy-holder/create	Parent entity for all policies
2	Policy	POST /policy/create	Defines benefits, sub-benefits, and coverage rules
3	Member	POST /policy/patients/add	The patient must be registered and assigned to a policy
4	Medical Provider	POST /medical-provider/create	The provider's CCHI number must exist in the system
5	Price List	POST /price-list/create	Optional -- enables price validation of claimed amounts against configured pricing
6	Webhook	POST /webhook/create	Required 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 & benefit checks -- 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 has been 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 (PENDING, ACCEPTED, REJECTED)
• 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

Status	Description	Required Fields
ACCEPTED	Fully approved, all items accepted	status, erp_reviewer_id
PARTIALLY_ACCEPTED	Some items approved, some rejected	status, erp_reviewer_id, items with individual statuses
REJECTED	Entire authorization rejected	status, erp_reviewer_id
REFERRED	Referred to another provider or specialist	status, 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:

Reason	Description
CORRECTION	Correcting previously submitted data
ADJUDICATION	Re-adjudication required
MISCALCULATION	Fixing a calculation error
BENEFIT	Benefit-related changes
AUDIT	Audit-triggered reprocessing
CANCEL	Cancellation-related reopen
OTHER	Other 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

Step	API Endpoint	Documentation
Create request	POST /approval-request/create	Prior Authorization
Retrieve status	GET /approval-request/get-one/:id	API Reference
Sync NPHIES bundle	PATCH /approval-request/bundle/sync/:id	API Reference
Update decision	PATCH /approval-request/update/:id	API Reference
Reopen	PATCH /approval-request/reopen/:id	API Reference
Cancel	PATCH /approval-request/cancel/:id	API Reference
Sync price list	POST /price-list/create	Price List
Attach documents	Supporting Info API	Supporting clinical documents
Send communications	Communication API	Messages related to authorizations
Receive decisions	Webhook	Register with hook_type: PRE_AUTH_RESULT