Developer Portal

Developer Documentation

Integrate the Nexa Health Tech NHCX Bidirectional Adapter with your existing stack — FHIR R4, standard headers, and predictable responses for claims workflows.

Quick Start

Getting started with the NHCX bidirectional adapter

The adapter sits between your core claims or policy systems and the NHCX network. You send FHIR R4 Bundles over HTTPS; the gateway validates profiles, applies routing rules from YAML configuration, and returns operation outcomes your services can handle without schema rewrites.

All traffic requires TLS 1.2+. Request and response bodies are JSON (application/fhir+json) unless custom binary wire encodings are enabled for your tenant.

Step 01

1. Prerequisites

HTTPS with TLS 1.2+, valid X-API-Key header, and access to an active sandbox or production environment.

Step 02

2. Configure Environment

Set ADAPTER_BASE_URL and ADAPTER_API_KEY in your microservice environment configuration. Store secret keys securely.

Step 03

3. Ingest First FHIR Bundle

POST a valid FHIR R4 Bundle to /fhir/R4/Bundle with Content-Type: application/fhir+json and X-API-Key. See Code Examples for cURL, TypeScript, Python, and Java.

Environment Variables (.env)

UTF-8 / Key-Value

ADAPTER_BASE_URL=https://api.adapter.nexahealthtech.com
ADAPTER_API_KEY=sk_live_nexa_7f9a2b8e4d1c3a6e5f

Authentication & Security

Tenant API keys, mTLS, and zero-trust policies

Production tenants authenticate via an API key passed in the request header. Enterprise deployments can additionally enforce mTLS x509 client certificates and Keycloak IAM zero-trust token verification.

Required Request Header

X-API-Key: sk_live_nexa_7f9a2b8e4d1c3a6e5f

API Endpoints Reference

Core REST endpoints for claims, eligibility & metadata

Base URL is provisioned per tenant environment. Replace {baseUrl} with your assigned host (e.g. api.adapter.nexahealthtech.com).

Method	Path	Description	Auth
POST	/fhir/R4/Bundle	Ingest a FHIR R4 Bundle (Claim, CoverageEligibilityRequest, PaymentNotice) for NHCX routing.	X-API-Key
GET	/fhir/R4/Bundle/{id}	Poll execution status, receipt acknowledgement, or adjudication response by Bundle ID.	X-API-Key
POST	/nhcx/v1/coverageeligibility/check	Direct real-time coverage eligibility check against insurer NHCX endpoint.	X-API-Key
POST	/nhcx/v1/preauth/submit	Submit pre-authorization request Bundle with sub-15 minute SLA target.	X-API-Key
GET	/fhir/R4/metadata	CapabilityStatement for discovery, supported resources, and validator profile alignment.	Public
GET	/health	Liveness and readiness probe for load balancers and Kubernetes health checks.	Public

Code Examples

Executable snippets for cURL, TypeScript, Python, and Java

Sample payload and request snippets across cURL, TypeScript, Python, and Java. Replace {baseUrl} with your environment endpoint.

curl -sS -X POST "https://api.adapter.nexahealthtech.com/fhir/R4/Bundle" \
  -H "Content-Type: application/fhir+json" \
  -H "Accept: application/fhir+json" \
  -H "X-API-Key: sk_live_nexa_7f9a2b8e4d1c3a6e5f" \
  -d @- << 'EOF'
{
  "resourceType": "Bundle",
  "id": "nhcx-claim-bundle-1029",
  "type": "collection",
  "entry": [
    {
      "fullUrl": "urn:uuid:claim-001",
      "resource": {
        "resourceType": "Claim",
        "id": "claim-001",
        "status": "active",
        "type": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/claim-type",
              "code": "institutional"
            }
          ]
        },
        "use": "claim",
        "patient": { "reference": "Patient/pat-9921" },
        "created": "2026-04-12T10:30:00Z",
        "provider": { "reference": "Organization/hosp-ghaziabad-01" },
        "priority": { "coding": [{ "code": "stat" }] }
      }
    }
  ]
}
EOF

FHIR Profiles & Resource Mappings

Strict NHCX resource validator alignments

The Nexa adapter natively parses and validates official NHCX FHIR R4 profiles:

Claim

Standard pre-auth and claim submission payload with items, diagnosis, and billing info.

CoverageEligibilityRequest

Real-time insurance eligibility & policy coverage check.

ClaimResponse

Adjudication decision payload containing approved amount and items breakdown.

PaymentNotice

Disbursement and payment settlement confirmation payload.

OperationOutcome

Standardized error and diagnostic payload returned on validation faults.

Errors & Rate Limits

HTTP status responses, rate limiting, and OperationOutcome schema

Validation or routing errors return standard HTTP 4xx/5xx status codes accompanied by a FHIR OperationOutcome payload detailing diagnostics.

Professional tiers support up to 500 requests/sec. Enterprise tiers support custom volumetric burst capacity and dedicated load balancers.

Status Code	Description
200 OK	Request processed and routed successfully.
400 Bad Request	FHIR profile or JSON syntax validation failed (returns OperationOutcome).
401 Unauthorized	Missing or invalid X-API-Key header or expired token.
422 Unprocessable	NHCX business logic or rule validation failed.
502 Bad Gateway	Upstream NHCX network or target insurer gateway timeout.

Sample OperationOutcome Error Payload

application/fhir+json

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "Profile validation failed: Claim.patient reference format is invalid"
    }
  ]
}

YAML Configuration Guide

Insurer routing rules, timeouts, and sandbox settings

Engineers can customize insurer routing rules, retry policies, and sandbox modes using adapter-config.yaml:

# adapter-config.yaml
version: "1.0"
environment: "production"
nhcx:
  gateway_url: "https://nhcx.nha.gov.in/api/v1"
  participant_code: "NEXA-HOSP-GZB-01"
  sandbox_mode: false
routing:
  max_retries: 3
  timeout_ms: 15000
  supported_insurers:
    - code: "INS_STAR_HEALTH"
      endpoint: "https://nhcx.starhealth.in/fhir"
    - code: "INS_HDFC_ERGO"
      endpoint: "https://nhcx.hdfcergo.com/fhir"
security:
  mtls_enabled: true
  cert_path: "/etc/ssl/nexa/client.crt"
  key_path: "/etc/ssl/nexa/client.key"

Repo & Architecture Layout

Directory conventions and architectural structure

Overview of key project directories if you are extending the Nexa Portal or integrating our SDK components.

src/app/

App Router page routes, metadata & server actions

src/constants/

Single source of truth marketing content & copy

src/features/

Decoupled feature components, views & widgets

src/lib/

API clients, FHIR helpers, SEO metadata & utilities