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.

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
`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

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.

Important

This API is essential for the Prior Authorization workflow. You must call this endpoint to update the authorization status so the service accepts it and records it in the transaction history. Without calling this API, the prior authorization will remain in a pending state and will not be reflected in the historical records.

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
JavaScript
Python

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"
          }
        ]
      }
    ]
  }'

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);

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`

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

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

Example Request

cURL
JavaScript
Python

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"

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);

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": []
}

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

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
JavaScript
Python

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"
  }'

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);

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`

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
JavaScript
Python

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"
  }'

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);

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
JavaScript
Python

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"

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);

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

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

Base URL​

Authentication​

Authentication​

Endpoints​

1. Update Prior Authorization​

Path Parameters​

Request Body Parameters​

Root Level Parameters​

Update Item Object​

Example Request​

Success Response (200 OK)​

Error Responses​

2. Create Prior Authorization​

API Endpoint​

3. Get One Prior Authorization​

Path Parameters​

Example Request​

Success Response (200 OK)​

Error Responses​

Example Error Response​

4. Sync Bundle​

Path Parameters​

Request Body Parameters​

Example Request​

Success Response (200 OK)​

Error Responses​

5. Reopen Prior Authorization​

Path Parameters​

Request Body Parameters​

Example Request​

Success Response (200 OK)​

Error Responses​

6. Cancel Prior Authorization​

Path Parameters​

Example Request​

Success Response (200 OK)​

Error Responses​

Enums Reference​

Member Gender​

Marital Status​

Claim Type​

Claim Sub-Type​

Prior Authorization Status​

Advanced Prior Authorization Status​

Response Bundle Status​

Diagnosis Type​

Related Documentation​

Base URL

Authentication

Authentication

Endpoints

1. Update Prior Authorization

Path Parameters

Request Body Parameters

Root Level Parameters

Update Item Object

Example Request

Success Response (200 OK)

Error Responses

2. Create Prior Authorization

API Endpoint

3. Get One Prior Authorization

Path Parameters

Example Request

Success Response (200 OK)

Error Responses

Example Error Response

4. Sync Bundle

Path Parameters

Request Body Parameters

Example Request

Success Response (200 OK)

Error Responses

5. Reopen Prior Authorization

Path Parameters

Request Body Parameters

Example Request

Success Response (200 OK)

Error Responses

6. Cancel Prior Authorization

Path Parameters

Example Request

Success Response (200 OK)

Error Responses

Enums Reference

Member Gender

Marital Status

Claim Type

Claim Sub-Type

Prior Authorization Status

Advanced Prior Authorization Status

Response Bundle Status

Diagnosis Type

Related Documentation