Najeeb V4.0 API Integration

The Najeeb V4.0 Health API Integration is a comprehensive REST API platform designed for insurance companies operating in the Kingdom of Saudi Arabia (KSA) to integrate with the Najeeb AI Engine. This API provides a full suite of endpoints for managing the healthcare insurance lifecycle, from policy creation and member registration through pre-authorization, claims processing, and real-time event notifications.

API Version

This documentation covers V4.0 of the Najeeb Health API. If you are migrating from an earlier version, please contact the Najeeb technical team for migration guidance.

Base URL

All API requests are made to your dedicated Najeeb instance using the following base URL format:

https://api.{client_namespace}.najeeb.ai/v4.0/health

Replace {client_namespace} with your organization's assigned namespace provided during onboarding.

Authentication

All API requests must include a valid API key in the request headers. The API key is provided by the Najeeb team during the onboarding process.

Header	Type	Required	Description
access-key	string	Yes	Your unique API key for authentication

Example request:

curl -X GET "https://api.{client_namespace}.najeeb.ai/v4.0/health/members" \
  -H "access-key: your-api-key-here" \
  -H "Content-Type: 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 API key has been compromised, contact the Najeeb support team immediately to rotate it.

Available Modules

The Najeeb V4.0 Health API is organized into the following modules. Each module provides a set of endpoints for managing a specific domain of the healthcare insurance workflow.

Module	Description
Policy Holder	Manage insurance policy holders
Policy	Create and manage insurance policies, templates, and patient consumption
Member (Patient)	Register and manage members/patients
Medical Provider	Register and manage medical providers
Network	Create and manage medical networks
Prior Authorization	Submit pre-authorization and PBM requests
Communication	Create communications related to prior authorizations
Supporting Info	Attach supporting information to pre-auths and claims
Price List	Manage price lists and items
Webhook	Register webhooks for event notifications
Health Declaration	Submit health declarations

Getting Started

The typical integration flow follows a logical sequence of data setup before transactional operations can begin. Below is the recommended order of integration:

Step 1: Create Policy Holder

Register your organization or client entities as policy holders in the Najeeb system. Policy holders are the top-level entities that own insurance policies.

Step 2: Create Policies with Templates

Define insurance policies under each policy holder. Policies include benefit templates that specify coverage rules, limits, and entitlements for members.

Step 3: Register Members

Register individual members (patients) and associate them with the appropriate policies. Member records include demographic information such as date of birth, gender, and membership details.

Step 4: Register Medical Providers

Register the medical providers (hospitals, clinics, pharmacies) that will submit claims and pre-authorization requests on behalf of members.

Step 5: Create Networks

Define medical networks that link policies to specific sets of medical providers. Networks determine which providers are eligible to serve members under a given policy.

Step 6: Submit Prior Authorizations

Once the foundational data is in place, begin submitting pre-authorization and PBM (Pharmacy Benefit Management) requests for adjudication by the Najeeb AI Engine.

Step 7: Register Webhooks for Notifications

Configure webhook endpoints to receive real-time notifications about events such as approval status changes, claim updates, and other system events.

Integration Support

The Najeeb technical team is available to assist throughout the integration process. Reach out for sandbox access, test data, and hands-on support during development.

Error Response Format

All API endpoints return errors in a consistent JSON format. When a request fails, the response body contains the following structure:

{
  "ErrorCode": "string",
  "message": "string",
  "details": ["string"]
}

Field	Type	Description
ErrorCode	string	A machine-readable error code identifying the type of failure
message	string	A human-readable description of the error
details	string[]	An array of detailed error messages providing additional context

HTTP Status Codes

The following HTTP status codes are used consistently across all API endpoints:

Status Code	Name	Description
200	OK	The request was successful.
201	Created	The resource was created successfully.
400	Bad Request	The request body is malformed or contains invalid data. Check the details array for specifics.
401	Unauthorized	The access-key header is missing, invalid, or expired. Verify your API key.
404	Not Found	The requested resource does not exist. Verify the resource identifier in the request path or body.
409	Conflict	The request conflicts with the current state of the resource (e.g., duplicate identifiers).
422	Unprocessable Entity	The request is syntactically valid but cannot be processed due to business rule violations.
500	Internal Server Error	An unexpected error occurred on the server. Contact the Najeeb support team if the issue persists.

Best Practices

Date and Time Format

All date and time values must conform to the ISO 8601 standard. Use the following formats:

• Date and time: YYYY-MM-DDTHH:mm:ss.sssZ (e.g., 2025-01-15T14:30:00.000Z)

Request Timeout

Set your HTTP client timeout to at least 50 seconds. Some operations, particularly prior authorization adjudication, involve AI processing that may take longer than typical API calls.

Idempotency

Use unique identifiers for transactional requests (e.g., transaction_id for prior authorizations) to prevent duplicate processing. Submitting a request with a previously used transaction_id will return an error.

Content Type

All request and response payloads use JSON. Always include the Content-Type: application/json header in your requests.

Rate Limiting

Be mindful of rate limits applied to your API key. Implement exponential backoff and retry logic for transient errors (5xx status codes). Avoid aggressive polling; use webhooks for event-driven updates instead.

Data Validation

Validate your request payloads against the documented schemas before submission. Pay particular attention to:

• Required fields: Missing required fields result in 400 Bad Request errors.
• Enum values: Fields with predefined values (e.g., gender, transaction type) must match the documented options exactly.
• Code formats: Ensure ICD-10 diagnosis codes, NPHIES codes, and CCHI numbers conform to the expected formats.

Error Handling

Implement robust error handling in your integration:

1. Parse the ErrorCode field for programmatic error classification.
2. Log the full error response including the details array for debugging.
3. Display the message field to end users when appropriate.
4. Implement retry logic only for transient errors (5xx). Do not retry client errors (4xx) without correcting the request.