API Specification — eKlotho Nexus Platform

Authentication

All API requests must be authenticated using OAuth 2.0 Bearer tokens. The eKlotho Nexus API supports two grant types depending on the use case.

🔐 Client Credentials (M2M)

For server-to-server integrations where no user context is required. Suitable for ETL pipelines, automated reporting, and system integrations.

// Step 1: Request access token
POST https://auth.eklotho.io/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={your_client_id}
&client_secret={your_client_secret}
&scope=nexus:read nexus:write nexus:claims

// Response
{
  "access_token": "eyJhbGciOiJSUzI1...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "nexus:read nexus:write nexus:claims"
}

👤 Authorization Code (User Context)

For applications that act on behalf of a logged-in eKlotho Nexus user. Provides user-scoped permissions and audit trail. Supports PKCE for public clients.

// Step 1: Redirect user to authorization
GET https://auth.eklotho.io/oauth2/authorize
  ?response_type=code
  &client_id={client_id}
  &redirect_uri={your_callback}
  &scope=openid nexus:read
  &state={random_state}
  &code_challenge={S256_challenge}   // PKCE

// Step 2: Exchange code for token
POST https://auth.eklotho.io/oauth2/token
grant_type=authorization_code
&code={auth_code}
&redirect_uri={callback}
&code_verifier={pkce_verifier}

🔑 Using the Token

// Include Bearer token in all API requests
GET https://api.eklotho.io/v2/patients
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI...
X-Organization-ID: org_8kqm2xb7          // Required
X-API-Version: 2.1                       // Optional, defaults to latest
Content-Type: application/json
Accept: application/json

Available OAuth Scopes

Scope	Access Level
nexus:read	Read all resources
nexus:write	Create and update resources
nexus:claims	Submit and manage claims
nexus:auth	Authorizations and referrals
nexus:enrollment	Member enrollment operations
nexus:analytics	Reports and analytics data
nexus:admin	Admin operations (restricted)
nexus:phi	Access to PHI fields (requires BAA)

🔒

HIPAA Notice: Access to Protected Health Information (PHI) via the API requires a signed Business Associate Agreement (BAA) with eKlotho Inc, the nexus:phi scope, and IP allowlisting. Contact api-access@eklotho.com to request a BAA and production credentials.

Rate Limits & Quotas

Rate limits are enforced per API key, per organization, and per endpoint category.

Request Limits by Tier

Tier	Requests/min	Requests/day	Burst
Developer	60	10,000	100
Standard	300	100,000	500
Enterprise	1,200	1,000,000	2,000
Clearinghouse	5,000	Unlimited	10,000

Endpoint-Specific Limits (Standard Tier)

Patient Search

30 / min

Claim Submission

120 / min

Eligibility Check

150 / min

Auth Submission

60 / min

Analytics Query

20 / min

Bulk Export

5 / hour

Rate Limit Response Headers

X-RateLimit-Limit: 300                    // Max requests per window
X-RateLimit-Remaining: 247                // Requests remaining this window
X-RateLimit-Reset: 1717516800             // Unix timestamp when window resets
X-RateLimit-Window: 60                    // Window size in seconds
Retry-After: 12                           // Present on 429 responses only

Patients API

Search, retrieve, create, and update patient demographics and enrollment records.

Patient Resources

GET /patients Search patients by name, MBI, MRN, or demographics

Query Parameters

Parameter	Type	Required	Description
mbi	string	optional	Medicare Beneficiary Identifier (11-char)
mrn	string	optional	Medical Record Number (internal)
last_name	string	optional	Patient last name (partial match supported)
first_name	string	optional	Patient first name
dob	string	optional	Date of birth (YYYY-MM-DD)
ssn_last4	string	optional	Last 4 digits of SSN (requires nexus:phi scope)
page	integer	optional	Page number (default: 1)
per_page	integer	optional	Results per page (max: 100, default: 25)

Response 200

{
  "data": [{
    "id": "pat_4k8mxb72",
    "mrn": "MRN-2024-08847",
    "mbi": "1EG4-TE5-MK72",
    "first_name": "Maria",
    "last_name": "Gonzalez",
    "dob": "1954-07-18",
    "gender": "F",
    "address": { "line1": "123 Main St", "city": "Los Angeles", "state": "CA", "zip": "90001" },
    "phone": "310-555-0142",
    "language": "es",
    "pcp_npi": "1234567890",
    "risk_score": 2.14,
    "enrollment_status": "active",
    "created_at": "2024-01-15T08:00:00Z"
  }],
  "pagination": { "page": 1, "per_page": 25, "total": 1847, "pages": 74 }
}

GET /patients/{id} Get full patient record including conditions and coverage

Path Parameters

Parameter	Type	Description
id	string	Patient ID (pat_xxxxx) or MRN prefixed with mrn: (e.g., `mrn:MRN-2024-08847`)

Query Parameters — Field Expansion

Parameter	Values	Description
include	`conditions,medications,coverage,claims,care_plans,vitals`	Comma-separated list of related resources to embed in response

POST /patients Register a new patient

Request Body (application/json)

Field	Type	Required	Description
first_name	string	required	Legal first name
last_name	string	required	Legal last name
dob	string	required	Date of birth (YYYY-MM-DD)
gender	string	required	M / F / U / X (unknown / non-binary)
address	object	required	line1, city, state, zip, country (default: US)
phone	string	optional	Primary phone (E.164 format preferred)
email	string	optional	Contact email
mbi	string	optional	Medicare Beneficiary Identifier
pcp_npi	string	optional	Primary Care Provider NPI
language	string	optional	ISO 639-1 language code (en, es, zh, etc.)
external_id	string	optional	Your system's patient ID for cross-referencing

PATCH /patients/{id} Update patient demographics (partial update)

Notes

Accepts the same fields as POST /patients. Only fields provided will be updated. All changes are logged in the HIPAA audit trail with requesting system identity.

Eligibility API

Real-time and batch insurance eligibility verification.

Eligibility Endpoints

POST /eligibility/check Real-time eligibility verification (triggers EDI 270)

Request Body

{
  "patient_id": "pat_4k8mxb72",          // OR provide mbi + dob + name
  "payer_id": "00431",               // Payer EDI ID (e.g., Aetna)
  "service_type_code": "30",        // 30=Health Benefit Plan Coverage
  "service_date": "2026-04-15",    // Date of service to check
  "npi": "1234567890"                // Rendering provider NPI
}

Response 200 — Eligibility Result

{
  "inquiry_id": "elig_7xkm92b",
  "status": "active",                 // active | inactive | unknown
  "payer": { "id": "00431", "name": "Aetna Medicare Advantage" },
  "coverage": {
    "plan_name": "Aetna Medicare Choice PPO",
    "plan_id": "H1234-001",
    "group_number": "GRP-889001",
    "member_id": "W1234567",
    "effective_date": "2026-01-01",
    "termination_date": null
  },
  "benefits": {
    "deductible": { "individual": 0, "met": 0, "remaining": 0 },
    "out_of_pocket_max": { "individual": 7550, "met": 120, "remaining": 7430 },
    "copay": { "primary_care": 10, "specialist": 35, "er": 90 },
    "coinsurance": 0
  },
  "msp": { "is_secondary": false },
  "checked_at": "2026-04-04T14:32:00Z",
  "source": "realtime_271"
}

POST /eligibility/batch Batch eligibility verification for multiple members

Request Body

{
  "requests": [
    { "patient_id": "pat_4k8mxb72", "payer_id": "00431", "service_date": "2026-04-15" },
    { "patient_id": "pat_9x2kqm41", "payer_id": "SB580", "service_date": "2026-04-15" }
  ],
  "callback_url": "https://your-system.com/webhooks/eligibility",
  "notify_on_completion": true
}

Returns a batch_id immediately. Results delivered via webhook or polled via GET /eligibility/batch/{batch_id}. Max 1,000 members per batch.

Claims API

Submit, track, adjudicate, and retrieve claims. Supports professional (837P), institutional (837I), and dental (837D) claim types.

Claims Endpoints

POST /claims Submit a new claim (REST JSON — auto-converts to 837)

Request Body

{
  "type": "professional",          // professional | institutional | dental
  "patient_id": "pat_4k8mxb72",
  "billing_provider": {
    "npi": "1234567890",
    "tax_id": "12-3456789",
    "name": "Westside Medical Group"
  },
  "rendering_provider_npi": "9876543210",
  "payer_id": "00431",
  "service_date_from": "2026-03-20",
  "service_date_to": "2026-03-20",
  "place_of_service": "11",          // 11=Office, 21=Inpatient, 23=ER
  "service_lines": [{
    "cpt_code": "99214",
    "icd10_codes": ["E11.9", "I10"],
    "units": 1,
    "charge_amount": 250.00,
    "modifiers": []
  }],
  "total_charge": 250.00,
  "authorization_number": "AUTH-2026-0044812"  // If prior auth required
}

Response 201 — Claim Accepted

{
  "claim_id": "clm_8xkm72b",
  "status": "submitted",
  "edi_control_number": "20260404001",
  "clearinghouse_id": "CH-8847291",
  "submitted_at": "2026-04-04T14:45:00Z",
  "expected_adjudication": "2026-04-18"
}

GET /claims/{id}/status Get current claim status and adjudication details

Response 200

{
  "claim_id": "clm_8xkm72b",
  "status": "adjudicated",  // submitted|validated|adjudicated|paid|denied|appealed
  "adjudication": {
    "paid_amount": 188.00,
    "allowed_amount": 200.00,
    "patient_responsibility": 10.00,
    "adjustment_codes": [
      { "group": "CO", "reason": "45", "amount": 50.00, "desc": "Charge exceeds fee schedule" }
    ],
    "check_number": "EFT-2026-04192",
    "payment_date": "2026-04-19"
  }
}

GET /claims List claims with filters (date range, status, patient, provider)

Key Query Parameters

Parameter	Type	Example
status	string	`adjudicated,paid` (comma-separated)
patient_id	string	`pat_4k8mxb72`
provider_npi	string	`1234567890`
date_from	string	`2026-01-01`
date_to	string	`2026-03-31`
type	string	`professional`

Authorizations API

Submit and manage prior authorization requests, referrals, and authorization status inquiries (EDI 278 compatible).

Authorization Endpoints

POST /authorizations Submit prior authorization request (maps to EDI 278)

Request Body

{
  "type": "prior_auth",             // prior_auth | referral | expedited
  "patient_id": "pat_4k8mxb72",
  "requesting_provider_npi": "1234567890",
  "servicing_provider_npi": "9876543210",
  "payer_id": "00431",
  "service_type": "inpatient_admission",
  "cpt_codes": ["27447"],
  "icd10_codes": ["M17.11"],
  "units_requested": 1,
  "service_date_from": "2026-05-10",
  "clinical_notes": "Severe right knee OA, failed conservative management x18mo",
  "urgency": "routine"                // routine | urgent | emergent
}

Response 201

{
  "auth_id": "auth_9km2xb7",
  "auth_number": "AUTH-2026-0044812",
  "status": "pending_review",       // approved|denied|pend|cancelled
  "sla_due": "2026-04-07T17:00:00Z", // 72-hour SLA for routine
  "submitted_at": "2026-04-04T15:00:00Z"
}

GET /authorizations/{id} Get authorization status and decision details

ℹ️

If status is denied, the response includes denial_reason_code, denial_rationale, and appeal_deadline fields. Use POST /authorizations/{id}/appeal to file an appeal.

Providers API

Provider directory, credentialing status, network participation, and contract management.

Provider Endpoints

GET /providers Search provider directory by NPI, specialty, location, or network status

Key Query Parameters

Parameter	Description	Example
npi	National Provider Identifier	`1234567890`
taxonomy	NUCC taxonomy code or description	`207R00000X`
network_status	Filter by network participation	`in_network`
accepting_patients	Filter to providers accepting new patients	`true`
zip	ZIP code for proximity search	`90001`
radius_miles	Search radius from zip (default 25)	`10`
credentialing_status	Filter by credentialing state	`active`

GET /providers/{npi}/credentialing Get credentialing status, license verifications, and expiration dates

Response 200

{
  "npi": "1234567890",
  "credentialing_status": "active",
  "last_credentialed": "2025-03-01",
  "next_review": "2027-03-01",
  "licenses": [{
    "state": "CA", "number": "A12345",
    "type": "Medical", "expiry": "2027-06-30", "status": "active"
  }],
  "exclusions": { "oig_leie": false, "sam_gov": false, "last_checked": "2026-04-01" },
  "malpractice": { "covered": true, "expiry": "2027-01-15" }
}

Enrollment API

Member enrollment, plan changes, disenrollment, and benefit verification.

Enrollment Endpoints

POST /enrollment/members Enroll a new member in a health plan (triggers EDI 834)

Request Body (key fields)

Field	Type	Description
patient_id	required	Existing patient record ID
plan_id	required	Health plan product ID
effective_date	required	Coverage start date (YYYY-MM-DD)
enrollment_type	required	new \| change \| termination \| reinstatement
eligibility_segment	optional	medicare \| medicaid \| commercial \| dual
premium_amount	optional	Monthly premium (cents, integer)
subsidy_eligible	boolean	Low-income subsidy (LIS) eligible
pcp_npi	optional	Designated PCP at enrollment

GET /enrollment/members/{id}/history Get full enrollment history including plan changes and retroactive adjustments

Returns chronological list of all enrollment transactions, plan changes, disenrollments, and retroactive adjustments with effective dates and processing status.

Analytics API

Population-level metrics, HEDIS measure performance, financial reports, and custom queries.

Analytics Endpoints

GET /analytics/metrics Retrieve aggregated population health and financial metrics

Query Parameters

Parameter	Description
metric	Metric name (e.g., `mlr`, `hedis_bcs`, `readmission_30d`, `ed_utilization`)
period	Reporting period: `current_month`, `ytd`, `last_12m`, or `custom`
date_from / date_to	Custom date range (required if period=custom)
group_by	Segment results: `plan`, `provider`, `diagnosis`, `age_group`
format	Response format: `json` (default), `csv`

POST /analytics/export Request async bulk data export (NDJSON or CSV)

Supports FHIR Bulk Data export format (NDJSON) as well as CSV. Exports are processed asynchronously. Returns a job_id to poll for completion. Files are available for download via signed URL for 24 hours.

Webhooks & Events

Subscribe to real-time event notifications when data changes in eKlotho Nexus. All webhook payloads are signed with HMAC-SHA256.

📡 Available Event Types

Event	Trigger	Payload Resource
`claim.submitted`	Claim accepted by clearinghouse	Claim object (no PHI in header)
`claim.adjudicated`	Claim paid or denied by payer	Claim with adjudication details
`claim.denied`	Claim denied with reason codes	Claim with denial codes + appeal deadline
`auth.approved`	Prior auth approved	Authorization with approval number
`auth.denied`	Prior auth denied	Authorization with denial rationale
`auth.expiring`	Auth expires within 7 days	Authorization expiry summary
`eligibility.changed`	Member coverage changed or terminated	Eligibility coverage object
`enrollment.effective`	Enrollment becomes effective	Member enrollment object
`patient.risk_score_updated`	HCC risk score recalculated	Patient ID + new/previous score
`alert.critical`	Critical clinical alert fired	Alert details (de-identified)

🔒 Webhook Security

// Verify webhook signature in your handler
// eKlotho signs payload with HMAC-SHA256 using your webhook secret

// Headers sent with each webhook
X-Eklotho-Signature: sha256=base64_hmac_signature
X-Eklotho-Timestamp: 1717516800
X-Eklotho-Event: claim.adjudicated
X-Eklotho-Delivery-ID: wh_8km2xb7q

// Verification (Node.js example)
const sig = crypto
  .createHmac('sha256', webhookSecret)
  .update(rawBody + '.' + timestamp)
  .digest('base64');
if (sig !== receivedSig) throw new Error('Invalid signature');

⚠️

Always verify the timestamp is within 5 minutes of current time to prevent replay attacks. Reject webhook deliveries with stale timestamps.

FHIR R4 Compatibility

eKlotho Nexus exposes a FHIR R4 compliant endpoint for EHR integration, SMART on FHIR apps, and regulatory data exchange (CMS Interoperability Rule compliance).

🏥 FHIR Base URL

// FHIR R4 base endpoint
https://api.eklotho.io/fhir/r4

// Capability statement (metadata)
GET https://api.eklotho.io/fhir/r4/metadata

// SMART on FHIR discovery document
GET https://api.eklotho.io/fhir/r4/.well-known/smart-configuration

Supported FHIR Resources

Patient Coverage Condition Claim ClaimResponse ServiceRequest CoverageEligibilityRequest CoverageEligibilityResponse MedicationRequest Observation Encounter CarePlan Practitioner Organization Location ExplanationOfBenefit

CMS Interoperability Rule Compliance

Requirement	Endpoint	Status
Patient Access API	`GET /fhir/r4/ExplanationOfBenefit?patient={id}`	✓ Compliant
Provider Directory API	`GET /fhir/r4/Practitioner`, `/Organization`, `/Location`	✓ Compliant
Drug Formulary API	`GET /fhir/r4/MedicationKnowledge`	✓ Compliant
Payer-to-Payer Data Exchange	`POST /fhir/r4/$member-match`	✓ Compliant
SMART on FHIR Backend Services	client_credentials flow	✓ Compliant

Sandbox & Testing

Sandbox Environment

Base URL	`https://api-sandbox.eklotho.io/v2`
Auth	`https://auth-sandbox.eklotho.io`
FHIR	`https://api-sandbox.eklotho.io/fhir/r4`
Rate Limits	60 req/min (sandbox throttled)
PHI	Synthetic data only — no real PHI

Test Credentials

# Sandbox OAuth credentials
client_id=sandbox_client_demo_001
client_secret=sk_sandbox_demo_xkm9b7q2
org_id=org_sandbox_demo

# Test patient MBI (always returns active)
mbi=1EG4-TE5-MK72

# Test payer ID (simulates Aetna)
payer_id=SANDBOX_AETNA

🧪

Register for sandbox access at developer.eklotho.io. Sandbox includes pre-populated synthetic member panels of 500+ patients across multiple conditions, 90 days of claim history, and simulated real-time eligibility responses. EDI transactions are intercepted and not forwarded to real clearinghouses.

eKlotho Nexus Platform API

API Reference Sections

Foundation

Core APIs

Extended