Full API for Prior Authorization
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.
This module handles the full lifecycle of a prior authorization: creation, status retrieval, bundle synchronization, status updates, reopening, and cancellation.
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.
Replace {client_namespace} with your organization's assigned namespace.
Authentication
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 |
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.
Endpoints
| Method | Title | Description |
|---|---|---|
PATCH | Update Prior Authorization | Update prior authorization status and items |
POST | Create Prior Authorization | Create a new prior authorization |
GET | Get One Prior Authorization | Retrieve a prior authorization by transaction ID |
PATCH | Sync Bundle | Sync NPHIES bundle by transaction ID |
PATCH | Reopen Prior Authorization | Reopen a previously processed prior authorization |
PATCH | Cancel Prior Authorization | Cancel a pre-authorization |
1. Update Prior Authorization
PATCH /approval-request/update/:transaction_id
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.
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.
Behavior
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
PENDINGin Najeeb core system. For any other status, the API returns422 APPROVAL_REQUEST_STATUS_NOT_ALLOWED. To change a decided request, reopen it first with Reopen Prior Authorization. - Reviewer:
erp_reviewer_idmust match an existing user's ERP ID. - Items: each entry in
itemsis matched to an item of the request byerp_item_id. An unknown item returns404APPROVAL_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
reasonsin the request. - Reason codes: each
reasons[].codemust exist as a standard rejection reason. Otherwise the API returns404STANDARD_REJECTION_REASON_NOT_FOUND. - Benefit codes: if
benefit_codeorsub_benefit_codeis sent, the benefit or sub-benefit is created when it does not exist yet. If omitted, the code is stored as0. - Referral: the referral rules apply only to requests that are referrals (
is_referralistrue). For those requests,referral_cchi_codeis required unlessstatusisREJECTED; otherwise the API returns422REFERRAL_CCHI_CODE_REQUIRED. When a code is sent, it must match a medical provider, otherwise the API returns404E_EMP_01. Areferral_cchi_codesent on a non-referral request is ignored. - Doctor checks: a missing or
nulldoctor_checkkeeps the saved list. An empty list clears it. Any other list replaces it. Repeated values are rejected.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
transaction_id | string | Yes | The unique transaction ID of the prior authorization |