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.

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.

---

Endpoints

Method	Title	Description
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	Update Prior Authorization	Update prior authorization status and items
PATCH	Reopen Prior Authorization	Reopen a previously processed prior authorization
PATCH	Cancel Prior Authorization	Cancel a pre-authorization

---

1. 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.

2. 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

Parameter	Type	Required	Description
transaction_id	string	Yes	The unique transaction ID of the prior authorization

Example Request

cURL

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"

JavaScript

const response = await fetch(
  'https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/get-one/550e8400-e29b-41d4-a716-446655440000',
  {
    method: 'GET',
    headers: {
      'access-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
  }
);

const result = await response.json();
console.log(result);

Python

import requests

response = requests.get(
    'https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/get-one/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'access-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
)

result = response.json()
print(result)

Success Response (200 OK)

Returns the full prior authorization object including all submitted fields, current status, item-level decisions, and processing metadata.

Error Responses

HTTP Status	Error Code	Description
404	E_EPA_09	Prior authorization not found for the given transaction_id

Example Error Response

{
  "ErrorCode": "E_EPA_09",
  "message": "Prior authorization not found",
  "details": []
}

---

3. 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

Parameter	Type	Required	Description
transaction_id	string	Yes	The unique transaction ID of the prior authorization

Request Body Parameters

Parameter	Type	Required	Description	Accepted Values
response_bundle_id *	string	Yes	The NPHIES response bundle ID	Alphanumeric string, max 255 characters
response_bundle_status *	string	Yes	Status of the NPHIES response bundle	Enum: COMPLETED, PENDING, PROCESSING, REFERRED
response_bundle_date *	string	Yes	Date of the NPHIES response bundle	ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ

Example Request

cURL

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": "COMPLETED",
    "response_bundle_date": "2025-02-15T12:00:00.000Z"
  }'

JavaScript

const response = await fetch(
  'https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/bundle/sync/550e8400-e29b-41d4-a716-446655440000',
  {
    method: 'PATCH',
    headers: {
      'access-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      response_bundle_id: 'BUNDLE-12345',
      response_bundle_status: 'COMPLETED',
      response_bundle_date: '2025-02-15T12:00:00.000Z',
    }),
  }
);

const result = await response.json();
console.log(result);

Python

import requests

response = requests.patch(
    'https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/bundle/sync/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'access-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'response_bundle_id': 'BUNDLE-12345',
        'response_bundle_status': 'COMPLETED',
        'response_bundle_date': '2025-02-15T12:00:00.000Z',
    },
)

result = response.json()
print(result)

Success Response (200 OK)

{
  "message": "Bundle synced successfully"
}

Error Responses

HTTP Status	Error Code	Description
400	E_BAD_REQUEST_400	Request validation failed
404	E_EPA_09	Prior authorization not found for the given transaction_id

---

4. Update Prior Authorization

PATCH /approval-request/update/:transaction_id

Updates the status and item-level decisions of an existing prior authorization. This endpoint is used by reviewers to approve, partially approve, reject, or refer a prior authorization.

Path Parameters

Parameter	Type	Required	Description
transaction_id	string	Yes	The unique transaction ID of the prior authorization

Request Body Parameters

Root Level Parameters

Parameter	Type	Required	Description	Accepted Values
status *	string	Yes	New status of the prior authorization	Enum: ACCEPTED, PARTIALLY_ACCEPTED, REJECTED, REFERRED
erp_reviewer_id *	string	Yes	Username of the reviewer performing the update	String
approval_remarks	string	No	Remarks from the reviewer	Free text
refferal_remarks	string	No	Remarks for referral (applicable when status is REFERRED)	Free text
internal_referral_notes	string	No	Internal notes for referral	Free text
internal_notes	string	No	Internal notes	Free text
referral_cchi_code	string	Conditional	CCHI code for referral provider. Required when status is REFERRED	Alphanumeric string
referral_valid_days	number	No	Number of days the referral is valid	Integer, 1-365
items	array	No	Array of item-level updates	See Update Item Object

Update Item Object

Parameter	Type	Required	Description	Accepted Values
status	string	No	Item-level status	Enum: ACCEPTED, REJECTED
approved_quantity	number	No	Approved quantity for the item	Integer, minimum 0
approved_amount	number	No	Approved amount for the item	Decimal, minimum 0
erp_item_id	string	No	ERP item identifier	Alphanumeric string
reasons	array	No	Array of rejection reason objects	See below

Referral Requirements

When the status is set to REFERRED, the referral_cchi_code field is required. Omitting it will result in a 422 Unprocessable Entity error.

Example Request

cURL

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": "ACCEPTED",
        "approved_quantity": 30,
        "approved_amount": 150.00
      },
      {
        "erp_item_id": "ITEM-002",
        "status": "REJECTED",
        "approved_quantity": 0,
        "reasons": [
          {
            "code": "REJ-001",
            "message": "Service not covered under current benefit plan"
          }
        ]
      }
    ]
  }'

JavaScript

const response = await fetch(
  'https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/update/550e8400-e29b-41d4-a716-446655440000',
  {
    method: 'PATCH',
    headers: {
      'access-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      status: 'PARTIALLY_ACCEPTED',
      erp_reviewer_id: 'reviewer.username',
      approval_remarks: 'Partially approved - adjusted quantities',
      items: [
        {
          erp_item_id: 'ITEM-001',
          status: 'ACCEPTED',
          approved_quantity: 30,
          approved_amount: 150.0,
        },
        {
          erp_item_id: 'ITEM-002',
          status: 'REJECTED',
          approved_quantity: 0,
          reasons: [
            {
              code: 'REJ-001',
              message: 'Service not covered under current benefit plan',
            },
          ],
        },
      ],
    }),
  }
);

const result = await response.json();
console.log(result);

Python

import requests

response = requests.patch(
    'https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/update/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'access-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'status': 'PARTIALLY_ACCEPTED',
        'erp_reviewer_id': 'reviewer.username',
        'approval_remarks': 'Partially approved - adjusted quantities',
        'items': [
            {
                'erp_item_id': 'ITEM-001',
                'status': 'ACCEPTED',
                'approved_quantity': 30,
                'approved_amount': 150.00,
            },
            {
                'erp_item_id': 'ITEM-002',
                'status': 'REJECTED',
                'approved_quantity': 0,
                'reasons': [
                    {
                        'code': 'REJ-001',
                        'message': 'Service not covered under current benefit plan',
                    },
                ],
            },
        ],
    },
)

result = response.json()
print(result)

Success Response (200 OK)

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

Error Responses

HTTP Status	Error Code	Description
400	E_BAD_REQUEST_400	Request validation failed
404	E_EPA_09	Prior authorization not found
404	E_EPA_10	User not found for the given erp_reviewer_id
404	E_EPA_11	Item not found
404	E_EPA_12	Benefit not found for item
404	E_EPA_13	Sub-benefit not found for item
404	E_EPA_14	Rejection reason not found
422	E_EPA_15	Status transition not allowed
422	E_EPA_16	Referral CCHI code is required when status is REFERRED

---

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

Parameter	Type	Required	Description
transaction_id	string	Yes	The unique transaction ID of the prior authorization

Request Body Parameters

Parameter	Type	Required	Description	Accepted Values
nphies_reopen_reason *	string	Yes	Reason for reopening the prior authorization	Enum: CORRECTION, ADJUDICATION, MISCALCULATION, BENEFIT, AUDIT, CANCEL, OTHER
nphies_reopen_at *	string	Yes	Date and time of the reopen action	ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
username *	string	Yes	Username of the user who reopened the request	String

Example Request

cURL

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": "CORRECTION",
    "nphies_reopen_at": "2025-02-16T09:00:00.000Z",
    "username": "admin.user"
  }'

JavaScript

const response = await fetch(
  'https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/reopen/550e8400-e29b-41d4-a716-446655440000',
  {
    method: 'PATCH',
    headers: {
      'access-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      nphies_reopen_reason: 'CORRECTION',
      nphies_reopen_at: '2025-02-16T09:00:00.000Z',
      username: 'admin.user',
    }),
  }
);

const result = await response.json();
console.log(result);

Python

import requests

response = requests.patch(
    'https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/reopen/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'access-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'nphies_reopen_reason': 'CORRECTION',
        'nphies_reopen_at': '2025-02-16T09:00:00.000Z',
        'username': 'admin.user',
    },
)

result = response.json()
print(result)

Success Response (200 OK)

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

Error Responses

HTTP Status	Error Code	Description
400	E_BAD_REQUEST_400	Request validation failed
404	E_EPA_10	User not found for the given username
404	E_EPA_09	Prior 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

Parameter	Type	Required	Description
transaction_id	string	Yes	The unique transaction ID of the prior authorization to cancel

Example Request

cURL

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"

JavaScript

const response = await fetch(
  'https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/cancel/550e8400-e29b-41d4-a716-446655440000',
  {
    method: 'PATCH',
    headers: {
      'access-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
  }
);

const result = await response.json();
console.log(result);

Python

import requests

response = requests.patch(
    'https://api.{client_namespace}.najeeb.ai/v4.0/health/approval-request/cancel/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'access-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
)

result = response.json()
print(result)

Success Response (200 OK)

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

Error Responses

HTTP Status	Error Code	Description
404	E_EPA_09	Prior authorization not found for the given transaction_id
409	E_EPA_17	Pre-authorization has already been cancelled

---

Enums Reference

Member Gender

Value	Description
MALE	Male
FEMALE	Female

Marital Status

Value	Description
SINGLE	Single
MARRIED	Married
ENGAGED	Engaged
UNKNOWN	Unknown
WIDOWED	Widowed
DIVORCED	Divorced
SEPARATED	Separated

Claim Type

Value	Description
INSTITUTIONAL	Institutional services for inpatients
PROFESSIONAL	Professional services for outpatients
PHARMACY	Pharmacy services
DENTAL	Dental services
OPTICAL	Optical services

Claim Sub-Type

Value	Description
IN_PATIENT	Inpatient services
OUT_PATIENT	Outpatient services
EMERGENCY	Emergency services

Prior Authorization Status

Value	Description
ACCEPTED	Fully approved
PARTIALLY_ACCEPTED	Partially approved with item-level adjustments
REJECTED	Rejected
REFERRED	Referred to another provider or specialist

Advanced Prior Authorization Status

Value	Description
ACCEPTED	Advanced prior authorization accepted
REJECTED	Advanced prior authorization rejected

Response Bundle Status

Value	Description
COMPLETED	Bundle processing completed
PENDING	Bundle is pending processing
PROCESSING	Bundle is currently being processed
REFERRED	Bundle has been referred

Diagnosis Type

Value	Description
primary	Primary diagnosis
secondary	Secondary diagnosis

---

Related Documentation

• 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