Skip to main content

Python SDK

Official Python SDK for Najeeb Health Suite API.

Installation​

pip install najeeb-health-suite

or

pipenv install najeeb-health-suite

Quick Start​

from najeeb import NajeebClient

client = NajeebClient(
    client_id='YOUR_CLIENT_ID',
    client_secret='YOUR_CLIENT_SECRET'
)

# List patients
patients = client.patients.list()

# Create a patient
patient = client.patients.create({
    'national_id': '1234567890',
    'first_name': 'أحمد',
    'last_name': 'محمد',
    'date_of_birth': '1990-01-15',
    'gender': 'male',
    'insurance_number': 'INS-12345',
    'insurance_company': 'Insurance Co.',
    'policy_start_date': '2024-01-01',
    'address': {
        'street': '123 Main St',
        'city': 'Riyadh',
        'region': 'Riyadh'
    }
})

Configuration​

from najeeb import NajeebClient

client = NajeebClient(
    client_id='YOUR_CLIENT_ID',
    client_secret='YOUR_CLIENT_SECRET',
    base_url='https://api.najeeb.com/v1',  # Optional
    timeout=30  # Optional, request timeout in seconds
)

API Methods​

Patients​

# List patients
patients = client.patients.list(
    page=1,
    per_page=20,
    search='أحمد'
)

# Get patient
patient = client.patients.get('pat_123456')

# Create patient
new_patient = client.patients.create({
    'national_id': '1234567890',
    'first_name': 'أحمد',
    # ... other fields
})

# Update patient
updated = client.patients.update('pat_123456', {
    'phone': '+966501234567'
})

# Delete patient
client.patients.delete('pat_123456')

Claims​

# List claims
claims = client.claims.list(
    status='approved',
    patient_id='pat_123456'
)

# Get claim
claim = client.claims.get('claim_123456')

# Submit claim
new_claim = client.claims.create({
    'patient_id': 'pat_123456',
    'provider_id': 'prov_789012',
    'service_date': '2024-01-15',
    'services': [
        {
            'code': 'CPT-99213',
            'description': 'Office visit',
            'quantity': 1,
            'unit_price': 250.00
        }
    ],
    'diagnosis_codes': ['E11.9']
})

# Update claim status
client.claims.update_status('claim_123456', {
    'status': 'approved',
    'notes': 'Approved after review'
})

Providers​

# List providers
providers = client.providers.list(
    type='hospital',
    city='Riyadh'
)

# Get provider
provider = client.providers.get('prov_123456')

# Check availability
availability = client.providers.get_availability('prov_123456', {
    'date': '2024-01-20'
})

Authorizations​

# List authorizations
authorizations = client.authorizations.list(
    status='pending'
)

# Get authorization
auth = client.authorizations.get('auth_123456')

# Request authorization
new_auth = client.authorizations.create({
    'patient_id': 'pat_123456',
    'provider_id': 'prov_789012',
    'service_date': '2024-01-20',
    'services': [
        {
            'code': 'CPT-27447',
            'description': 'Total knee arthroplasty',
            'quantity': 1,
            'estimated_cost': 50000.00
        }
    ],
    'diagnosis_codes': ['M17.11'],
    'urgency': 'routine'
})

# Approve authorization
client.authorizations.approve('auth_123456', {
    'notes': 'Approved after review'
})

# Reject authorization
client.authorizations.reject('auth_123456', {
    'notes': 'Not medically necessary'
})

Error Handling​

from najeeb.exceptions import NajeebError, NotFoundError, UnauthorizedError

try:
    patient = client.patients.get('pat_123456')
except NotFoundError:
    print('Patient not found')
except UnauthorizedError:
    print('Authentication failed')
except NajeebError as e:
    print(f'Error: {e.message}')

Pagination​

# Get all patients (auto-pagination)
all_patients = client.patients.list_all()

# Manual pagination
page = 1
while True:
    response = client.patients.list(page=page, per_page=100)
    # Process response.data
    if response.meta.page >= response.meta.total_pages:
        break
    page += 1

Webhooks​

from flask import Flask, request
from najeeb.webhooks import verify_webhook_signature
import os

app = Flask(__name__)

@app.route('/webhooks', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Najeeb-Signature')
    secret = os.environ.get('WEBHOOK_SECRET')
    
    if not verify_webhook_signature(request.data, signature, secret):
        return 'Invalid signature', 401
    
    event = request.json
    
    if event['event_type'] == 'claim.status_changed':
        handle_claim_status_changed(event['data']['object'])
    # ... other event types
    
    return 'OK', 200

def handle_claim_status_changed(claim):
    print(f"Claim {claim['id']} status changed to {claim['status']}")

Type Hints​

The SDK includes type hints for better IDE support:

from najeeb import NajeebClient
from najeeb.types import Patient, Claim

client = NajeebClient(
    client_id='YOUR_CLIENT_ID',
    client_secret='YOUR_CLIENT_SECRET'
)

patient: Patient = client.patients.get('pat_123456')

Next Steps​