The Prior Authorization module provides endpoints for creating, retrieving, updating, and managing pre-authorization (pre-auth) requests. It serves as the core transactional interface for submitting healthcare service requests for adjudication by the Najeeb AI Engine.
Module Overview
This module handles the full lifecycle of a prior authorization: creation, status retrieval, bundle synchronization, status updates, reopening, and cancellation.
All endpoints require the access-key header for authentication. Requests must be made over HTTPS.
Header
Type
Required
Description
access-key
string
Yes
Your unique API key for authentication
Content-Type
string
Yes
Must be application/json
Security
Keep your API key confidential. Do not expose it in client-side code, public repositories, or insecure channels. If you suspect your key has been compromised, contact the Najeeb support team immediately to rotate it.
Records the reviewer's decision on an existing prior authorization. A decision can set the overall status, add remarks and referral details, and set a decision for each item: its status, approved quantity and approved amount, and the rejection reasons.
Important
This API is essential for the Prior Authorization workflow. You must call this endpoint to record the reviewer's decision so the request is reflected in the transaction history. Without it, the prior authorization stays pending and is not reflected in the historical records.
You should update all requests that have been submitted to Najeeb with the reviewer decision. Requests that have already been updated cannot be updated directly; to change a decided request, reopen it first with Reopen Prior Authorization, then update it with the new status.
Allowed statuses: Only requests that have not yet received a decision can be updated, meaning the current status is PENDING in Najeeb core system. For any other status, the API returns 422 APPROVAL_REQUEST_STATUS_NOT_ALLOWED. To change a decided request, reopen it first with Reopen Prior Authorization.
Reviewer:erp_reviewer_id must match an existing user's ERP ID.
Items: each entry in items is matched to an item of the request by erp_item_id. An unknown item returns 404APPROVAL_REQUEST_ITEM_NOT_FOUND, and the update is not applied.
Rejection reasons are replaced: for every item sent, all reasons previously recorded on that item are removed and replaced by the reasons in the request.
Reason codes: each reasons[].code must exist as a standard rejection reason. Otherwise the API returns 404STANDARD_REJECTION_REASON_NOT_FOUND.
Benefit codes: if benefit_code or sub_benefit_code is sent, the benefit or sub-benefit is created when it does not exist yet. If omitted, the code is stored as 0.
Referral: the referral rules apply only to requests that are referrals (is_referral is true). For those requests, referral_cchi_code is required unless status is REJECTED; otherwise the API returns 422REFERRAL_CCHI_CODE_REQUIRED. When a code is sent, it must match a medical provider, otherwise the API returns 404E_EMP_01. A referral_cchi_code sent on a non-referral request is ignored.
Doctor checks: a missing or nulldoctor_check keeps the saved list. An empty list clears it. Any other list replaces it. Repeated values are rejected.
ERP ID of the reviewer performing the update. Must match an existing user
String, 1-255 characters
approval_remarks
string
No
Remarks from the reviewer
String, 1-255 characters
refferal_remarks
string
No
Remarks for the referral. Used when the status is REFERRED
String, 1-255 characters
internal_referral_notes
string
No
Internal notes for the referral
String, 1-255 characters
internal_notes
string
No
Internal notes
String, 1-255 characters
referral_cchi_code
string
Conditional
CCHI code of the referral provider. Required for referral requests unless the status is REJECTED
String, 1-255 characters
referral_valid_days
number
No
Number of days the referral is valid
Integer, 1-365
doctor_check
array
No
Doctor manual checks for the request. When doctors flag a case manually using one of these predefined flags while reviewing and updating the decision for a specific case (for example, a WORK_RELATED case), Najeeb saves this case for the member in history and considers it for upcoming requests. See Behavior for how a missing, empty, or non-empty list is applied.
items
array
No
Item-level decisions. When sent, at least one item is required
The DRG and weight the payer and provider settled on. null clears it; leaving the key out keeps it. Setting it alone recalculates nothing. Added with the DRG release; see Settled DRG
See DRG Reference Object. drg_code must be a valid AR-DRG V9.0 code (422E_DRG_020)
If your client does not need policy validation or synchronized policy/member data, use Prior Authorization / Lightweight. The Lightweight flow does not require syncing policy holders, policies, or members before submission.
Retrieves a single prior authorization by its transaction_id. Returns the full prior authorization details including status, items, and adjudication results.
Returns the full prior authorization object including all submitted fields, current status, item-level decisions, and processing metadata. It includes the root issues list on every request and, for requests sent with drg_enabled: true, provider_drg, settled_drg and drg. See the Pre-auth DRG Coder result.
Synchronizes an NPHIES response bundle with an existing prior authorization. Use this endpoint to update the prior authorization with the NPHIES response data after receiving a bundle from the NPHIES platform.
Reopens a previously processed prior authorization. This allows a prior authorization that has been completed (approved, rejected, etc.) to be sent back for reprocessing.