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

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.

Module Overview

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.

HeaderTypeRequiredDescription
access-keystringYesYour unique API key for authentication
Content-TypestringYesMust 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.


Endpoints​

MethodTitleDescription
PATCHUpdate Prior AuthorizationUpdate prior authorization status and items
POSTCreate Prior AuthorizationCreate a new prior authorization
GETGet One Prior AuthorizationRetrieve a prior authorization by transaction ID
PATCHSync BundleSync NPHIES bundle by transaction ID
PATCHReopen Prior AuthorizationReopen a previously processed prior authorization
PATCHCancel Prior AuthorizationCancel 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.

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.

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 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 404 APPROVAL_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 404 STANDARD_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 422 REFERRAL_CCHI_CODE_REQUIRED. When a code is sent, it must match a medical provider, otherwise the API returns 404 E_EMP_01. A referral_cchi_code sent on a non-referral request is ignored.
  • Doctor checks: a missing or null doctor_check keeps the saved list. An empty list clears it. Any other list replaces it. Repeated values are rejected.

Path Parameters​

ParameterTypeRequiredDescription
transaction_idstringYesThe unique transaction ID of the prior authorization

Request Body Parameters​

Root Level Parameters​

ParameterTypeRequiredDescriptionAccepted Values
status *EnumYesNew status of the prior authorizationACCEPTED, PARTIALLY_ACCEPTED, REJECTED, REFERRED
erp_reviewer_id *stringYesERP ID of the reviewer performing the update. Must match an existing userString, 1-255 characters
approval_remarksstringNoRemarks from the reviewerString, 1-255 characters
refferal_remarksstringNoRemarks for the referral. Used when the status is REFERREDString, 1-255 characters
internal_referral_notesstringNoInternal notes for the referralString, 1-255 characters
internal_notesstringNoInternal notesString, 1-255 characters
referral_cchi_codestringConditionalCCHI code of the referral provider. Required for referral requests unless the status is REJECTEDString, 1-255 characters
referral_valid_daysnumberNoNumber of days the referral is validInteger, 1-365
doctor_checkarrayNoDoctor 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.
itemsarrayNoItem-level decisions. When sent, at least one item is requiredSee Update Item Object
settled_drgobjectNoThe 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 DRGSee DRG Reference Object. drg_code must be a valid AR-DRG V9.0 code (422 E_DRG_020)

Update Item Object​

ParameterTypeRequiredDescriptionAccepted Values
erp_item_id *stringYesERP ID of the item in the request. Used to match the itemString, 1-255 characters
status *EnumYesDecision for the itemACCEPTED, PARTIALLY_ACCEPTED, REJECTED
approved_quantity *numberYesApproved quantity of the item. Use 0 when nothing is approvedNumber, 0-1,000,000,000
approved_amount *numberYesApproved amount of the itemNumber, 0-1,000,000,000
reasonsarrayNoRejection reasons of the item. Replaces the item's existing reasons. See Reason ObjectArray
service_codestringNoService code of the itemString, 1-255 characters
nphies_codestringNoNPHIES code of the itemString, 1-255 characters
benefit_codenumberNoBenefit code of the item. Created if it does not existInteger, 0-9999999
sub_benefit_codenumberNoSub-benefit code of the item. Created if it does not existInteger, 0-9999999

Reason Object​

ParameterTypeRequiredDescriptionAccepted Values
code *stringYesStandard rejection reason code. Must exist, otherwise 404String, 1-255 characters
acceptance_commentstringNoComment stored as the reason's cause. Takes precedence over remarksString, 1-255 characters
remarksstringNoRemarks stored as the reason's cause when acceptance_comment is emptyString, 1-255 characters
special_case_amountnumberNoAmount for a special caseNumber, 0-1,000,000,000
doctor_remarkstringNoDoctor's remark for this reasonString, 1-255 characters, or null

Example Request​

curl -X PATCH "https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/update/550e8400-e29b-41d4-a716-446655440000" \
-H "access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"status": "PARTIALLY_ACCEPTED",
"erp_reviewer_id": "reviewer.username",
"approval_remarks": "Partially approved - adjusted quantities",
"items": [
{
"erp_item_id": "ITEM-001",
"status": "PARTIALLY_ACCEPTED",
"approved_quantity": 30,
"approved_amount": 150.00
},
{
"erp_item_id": "ITEM-002",
"status": "REJECTED",
"approved_quantity": 0,
"approved_amount": 0,
"reasons": [
{
"code": "REJ-001",
"remarks": "Service not covered under current benefit plan"
}
]
}
]
}'

Success Response (200 OK)​

{
"message": "Approval request updated successfully"
}

Error Responses​

HTTP StatusError CodeDescription
400E_BAD_REQUEST_400Request validation failed. The details array lists the invalid fields
404E_EPA_064No prior authorization exists for the transaction_id
404USER_NOT_FOUNDNo user matches the erp_reviewer_id
404APPROVAL_REQUEST_ITEM_NOT_FOUNDAn erp_item_id does not belong to the request
404STANDARD_REJECTION_REASON_NOT_FOUNDA reason code is not a standard rejection reason
404E_EMP_01The referral_cchi_code does not match a medical provider
422APPROVAL_REQUEST_STATUS_NOT_ALLOWEDThe request already has a decision. Reopen it before updating
422REFERRAL_CCHI_CODE_REQUIREDThe request is a referral, referral_cchi_code was not sent, and the status is not REJECTED

2. Create Prior Authorization​

API Endpoint​

POST /approval-request/create

Creates a new prior authorization. The request is validated, processed by the Najeeb AI Engine, and an acknowledgement is returned synchronously.

For the full request payload, field definitions, and examples, see:

When Policy Sync Is Not Required

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.

3. Get One Prior Authorization​

GET /approval-request/get-one/:transaction_id

Retrieves a single prior authorization by its transaction_id. Returns the full prior authorization details including status, items, and adjudication results.

Path Parameters​

ParameterTypeRequiredDescription
transaction_idstringYesThe unique transaction ID of the prior authorization

Example Request​

curl -X GET "https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/get-one/550e8400-e29b-41d4-a716-446655440000" \
-H "access-key: YOUR_API_KEY" \
-H "Content-Type: application/json"

Success Response (200 OK)​

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.

Error Responses​

HTTP StatusError CodeDescription
404E_EPA_09Prior authorization not found for the given transaction_id
Example Error Response​
{
"ErrorCode": "E_EPA_09",
"message": "Prior authorization not found",
"details": []
}

4. Sync Bundle​

PATCH /approval-request/bundle/sync/:transaction_id

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.

Path Parameters​

ParameterTypeRequiredDescription
transaction_idstringYesThe unique transaction ID of the prior authorization

Request Body Parameters​

ParameterTypeRequiredDescriptionAccepted Values
response_bundle_id *stringYesThe NPHIES response bundle IDAlphanumeric string, max 255 characters
response_bundle_status *EnumYesStatus of the NPHIES response bundleEnum: COMPLETED, PENDING, PROCESSING, REFERRED
response_bundle_date *dateYesDate of the NPHIES response bundleISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ

Example Request​

curl -X PATCH "https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/bundle/sync/550e8400-e29b-41d4-a716-446655440000" \
-H "access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "response_bundle_id": "BUNDLE-12345",
  "response_bundle_status": "Enum Response Bundle Status",
  "response_bundle_date": "2025-02-15T12:00:00.000Z"
}'

Success Response (200 OK)​

{
"message": "Bundle synced successfully"
}

Error Responses​

HTTP StatusError CodeDescription
400E_BAD_REQUEST_400Request validation failed
404E_EPA_09Prior authorization not found for the given transaction_id

5. Reopen Prior Authorization​

PATCH /approval-request/reopen/:transaction_id

Reopens a previously processed prior authorization. This allows a prior authorization that has been completed (approved, rejected, etc.) to be sent back for reprocessing.

Path Parameters​

ParameterTypeRequiredDescription
transaction_idstringYesThe unique transaction ID of the prior authorization

Request Body Parameters​

ParameterTypeRequiredDescriptionAccepted Values
nphies_reopen_reason *EnumYesReason for reopening the prior authorizationEnum: CORRECTION, ADJUDICATION, MISCALCULATION, BENEFIT, AUDIT, CANCEL, OTHER
nphies_reopen_at *stringYesDate and time of the reopen actionISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
username *stringYesUsername of the user who reopened the requestString

Example Request​

curl -X PATCH "https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/reopen/550e8400-e29b-41d4-a716-446655440000" \
-H "access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "nphies_reopen_reason": "Enum NPHIES Reopen Reason",
  "nphies_reopen_at": "2025-02-16T09:00:00.000Z",
  "username": "admin.user"
}'

Success Response (200 OK)​

{
"message": "Prior authorization reopened successfully"
}

Error Responses​

HTTP StatusError CodeDescription
400E_BAD_REQUEST_400Request validation failed
404E_EPA_10User not found for the given username
404E_EPA_09Prior authorization not found for the given transaction_id

6. Cancel Prior Authorization​

PATCH /approval-request/cancel/:transaction_id

Cancels a pre-authorization request. Once cancelled, the prior authorization cannot be processed further.

Path Parameters​

ParameterTypeRequiredDescription
transaction_idstringYesThe unique transaction ID of the prior authorization to cancel

Example Request​

curl -X PATCH "https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/cancel/550e8400-e29b-41d4-a716-446655440000" \
-H "access-key: YOUR_API_KEY" \
-H "Content-Type: application/json"

Success Response (200 OK)​

{
"message": "Pre auth cancelled successfully"
}

Error Responses​

HTTP StatusError CodeDescription
404E_EPA_09Prior authorization not found for the given transaction_id
409E_EPA_17Pre-authorization has already been cancelled

Enums Reference​

Member Gender​

ValueDescription
MALEMale
FEMALEFemale

Marital Status​

ValueDescription
SINGLESingle
MARRIEDMarried
ENGAGEDEngaged
UNKNOWNUnknown
WIDOWEDWidowed
DIVORCEDDivorced
SEPARATEDSeparated

Claim Type​

ValueDescription
INSTITUTIONALInstitutional services for inpatients
PROFESSIONALProfessional services for outpatients
PHARMACYPharmacy services
DENTALDental services
OPTICALOptical services

Claim Sub-Type​

ValueDescription
IN_PATIENTInpatient services
OUT_PATIENTOutpatient services
EMERGENCYEmergency services

Prior Authorization Status​

ValueDescription
ACCEPTEDFully approved
PARTIALLY_ACCEPTEDPartially approved with item-level adjustments
REJECTEDRejected
REFERREDReferred to another provider or specialist

Advanced Prior Authorization Status​

ValueDescription
ACCEPTEDAdvanced prior authorization accepted
REJECTEDAdvanced prior authorization rejected

Response Bundle Status​

ValueDescription
COMPLETEDBundle processing completed
PENDINGBundle is pending processing
PROCESSINGBundle is currently being processed
REFERREDBundle has been referred

Diagnosis Type​

ValueDescription
primaryPrimary diagnosis
secondarySecondary diagnosis

Doctor Check​

ValueDescription
CHRONICChronic condition
CONGENITALCongenital condition
RTARoad traffic accident
WORK_RELATEDWork-related injury or condition
VACCINATIONVaccination
PSYCHIATRICPsychiatric condition
CHECKUPCheck-up
INFERTILITYInfertility
PREGNANCYPregnancy

  • Member -- Managing patients and member records
  • Medical Provider -- Managing medical providers
  • Policy -- Policy management and benefit templates
  • Supporting Info -- Attaching supporting documents to prior authorizations
  • Communication -- Creating communications related to prior authorizations
  • Webhook -- Registering webhooks for event notifications