API Documentation — ABDM Bridge Gateway

Token type	How to send the token	How HFR ID is provided
Hospital-specific token RECOMMENDED	`Authorization: Bearer {hospital-token}`	Send in the request body — add `"hfr_id": "YOUR_HFR_ID"` to every push request. The gateway validates it matches the HFR ID registered to your API key (`403 HFR_ID_MISMATCH` if wrong). Ask your gateway admin for your token (Admin → Hospital Users → Create User).
Gateway master token	`Authorization: Bearer {gateway-token}`	Must be sent in the request body — add `"hfr_id": "YOUR_HFR_ID"` to every push request. Missing = `400 HFR_ID_REQUIRED`. Unregistered = `403 HFR_ID_NOT_REGISTERED`.

Parallel Integration Pathways (Webhooks vs. Polling)

Integration Flexibility: The ABDM Bridge Gateway supports two parallel integration paradigms depending on your HMS hosting architecture. You can choose the one that fits your network structure.

A Webhook-Based (Push Paradigm)

Ideal for: Cloud-hosted HMS installations with a publicly accessible domain/URL (e.g. https://hms.myhospital.com).

In this model, the Gateway functions asynchronously. When an event occurs (e.g., patient links a record or grants a consent), the bridge actively POSTs a signed HMAC payload to your HMS server.

No Polling: No periodic API calls are required, preserving server CPU and network bandwidth.
Real-time: Updates are delivered instantly as soon as ABDM processes them.
Security: The HMS must verify the X-Eka-Signature header using the shared webhook secret before processing.

View Webhook Endpoints →

B Polling-Based (Pull Paradigm)

Ideal for: On-premise HMS installations running inside local intranet networks behind NAT or firewalls.

Since the gateway cannot establish outbound network connections to local IPs behind NAT, the HMS pulls updates by periodically calling the gateway.

Zero Network Config: No public IP, DNS records, or SSL domain setup is required on your local HMS server.
NAT/Firewall Friendly: Fully secure since all connections originate outbound from the HMS.
Endpoints: HMS polls GET /api/v1/hiu/consent/status (for consent state) and GET /api/v1/hiu/data/fetch (for decrypted clinical data).

View Polling Endpoints →

All Endpoints

Method	Endpoint	Description	Auth
SYSTEM
GET	`/api/v3/health?hfr_id=YOUR_HFR_ID`	Gateway health & API key check — validates HFR ID and Bearer token together. Returns `hfr_id_ok` + `api_key_ok`. Use as HMS Test Connection. Both are required.	Bearer
GET	`/api/v3/gateway/status`	Gateway + ABDM upstream connectivity check	Bearer
GET	`/api/v3/abdm/status`	ABDM live status via direct session-token probe (`/api/hiecm/gateway/v3/sessions`) for HMS user alerts	Bearer
HEALTH RECORDS (HMS → Bridge → ABDM)
POST	`/api/v1/patient/sync`	Push or update patient master from HMS (ABHA optional). Upserts gateway patient registry and maps to authenticated hospital.	Bearer
POST	`/api/v1/fhir/sync`	HMS-friendly clinical sync endpoint. Accepts `fhir_resource`, auto-wraps to document bundle when required, then forwards to `/api/v3/records/push`.	Bearer
POST	`/api/v3/records/push`	Push a FHIR R4 health record from HMS. Validates bundle, stores in gateway, returns `record_id` + `queue_id`. Detects duplicates via `care_context_reference`.	Bearer
GET	`/api/v3/records`	List stored records (filterable by abha_id, status, record_type)	Bearer
GET	`/api/v3/records/{id}`	Get a single stored record including full record_data	Bearer
POST	`/api/v3/records/{id}/share`	Trigger ABDM care-context linking for a stored record (HIP-initiated share)	Bearer
POST	`/api/v3/records/{id}/link-and-share`	Single-call orchestrator: auto-submit care-context link (if token available) and share when linked	Bearer
GET	`/api/v3/records/{id}/workflow-status`	Poll record workflow status (record + care-context link state + next action for HMS)	Bearer
HIP-INITIATED LINKING (HMS → Bridge → ABDM)
POST	`/api/v3/hfr/hrp/link`	Optional prereq — register/update facility service link before HIP linking	Bearer
POST	`/api/v3/hip/link-token`	Step 1 — Request a one-time JWT link token for a patient from ABDM (async; token arrives via callback)	Bearer
POST	`/api/v3/hip/link/carecontext`	Step 2 — Link care contexts to patient's ABHA using the link token	Bearer
GET	`/api/v3/hip/link/patient/links`	Fetch all care contexts linked for a patient (`?abha_address=xxx`)	Bearer
POST	`/api/v3/hip/link/notify`	Notify ABDM of a care-context update for a patient	Bearer
POST	`/api/v3/hip/link/sms-notify`	Send ABDM deep-link SMS to patient's mobile	Bearer
ABHA MANAGEMENT
POST	`/api/v3/abha/validate`	Validate ABHA ID or ABHA Address	Bearer
POST	`/api/v3/abha/aadhaar/generate-otp`	Create ABHA — Step 1: Send OTP to Aadhaar-linked mobile	Bearer
POST	`/api/v3/abha/aadhaar/verify-otp`	Create ABHA — Step 2: Verify OTP, create/retrieve ABHA. Response includes `patient_id` + `gateway_patient` (full saved profile from gateway DB).	Bearer
POST	`/api/v3/abha/enrol/mobile/request-otp`	Create ABHA (Child/Alternate No) — Step 2a: Send OTP to parent's alternate mobile (bound to Aadhaar txnId)	Bearer
POST	`/api/v3/abha/enrol/mobile/verify-otp`	Create ABHA (Child/Alternate No) — Step 2b: Verify alternate mobile OTP & finish child's ABHA enrolment	Bearer
POST	`/api/v3/abha/mobile/generate-otp`	Link ABHA — Step 1: Send OTP to registered mobile	Bearer
POST	`/api/v3/abha/mobile/verify-otp`	Link ABHA — Step 2: Verify Mobile OTP. Bridge automatically completes ABDM account selection internally, converts the 300s token into the 1800s Profile X-Token, and delivers `official_card` & `gateway_patient` directly inline.	Bearer
POST	`/api/v3/abha/login/select-account`	Select Account (Mobile Login) — Exchange 300s Mobile OTP token + selected `abha_number` / `abha_address` for 1800s Profile X-Token & official card.	Bearer
GET	`/api/v3/abha/card`	Download Official ABHA Card — Fetches genuine ABDM-issued ABHA Card. Pass patient `token` or `X-Token`. Returns `card_source: "abdm"` when ABDM issues the card, or `card_source: "none"` (with `official_card: null`) if ABDM does not issue a card for the session. Zero locally generated cards.	Bearer
OPD QUEUE & FACILITY
GET	`/api/v3/facility/qr-code`	Fetch facility details and Base64 QR code image	Bearer
GET	`/api/v3/opd/queue`	List OPD tokens for this hospital (date-filtered)	Bearer
POST	`/api/v3/opd/token`	Create a new OPD token (patient check-in)	Bearer
PATCH	`/api/v3/opd/token/{id}`	Update token status (`PENDING` / `CALLED` / `COMPLETED` / `CANCELLED`)	Bearer
GET	`/api/v3/opd/running-token-status`	Get current token being served at this HIP	Bearer
DRUG TERMINOLOGY (CDCI) — HMS SEARCH / AUTOCOMPLETE
GET	`/api/v3/drugs/autocomplete?q=par&type=generic&limit=10`	Fast type-ahead list for drug name inputs. Use from HMS prescription/dispense UI as user types.	Bearer
GET	`/api/v3/drugs/search?q=paracetamol&type=generic&limit=20&offset=0`	Paginated full search in CDCI index. Returns matching entries with type + identifier + metadata.	Bearer
GET	`/api/v3/drugs/detail?type=generic&identifier=419367007&view=hms_fill`	Fetch canonical record, or HMS-friendly projection with `view=hms_fill`.	Bearer
POST	`/api/v3/drugs/detail/bulk`	Batch detail lookup by identifiers (up to 200 per call) with optional `view=hms_fill`.	Bearer
GET	`/api/v3/drugs/by-barcode?barcode=8901234567890`	Barcode helper route (currently returns DATASET_UNAVAILABLE until barcode mapping is integrated).	Bearer
GET	`/api/v3/drugs/version`	Returns latest import run info and table counts. Use in HMS diagnostics/health dashboard.	Bearer
GET	`/api/v3/drugs/masters?master=company&limit=100`	Fetch CDCI-backed HMS master lists (`company`, `formulation`, `short_formulation`, `generic`) for local HMS master sync. Data is served from the gateway CDCI database (not a live ABDM M3 drug-masters proxy). Use `master=company` for Drug Company dropdown.	Bearer
GET	`/api/v3/drugs/formulation-mappings?limit=100`	Fetch effective long-formulation to short-formulation mappings including manual overrides configured in Admin.	Bearer
GET	`/api/v3/pathology/masters?sub_category=PATHOLOGY&limit=200`	Fetch pathology tests from Clinical Test Master for HMS catalog sync (supports search + incremental sync with `updated_since`).	Bearer
GET	`/api/v3/pathology/components?parent_test=Complete Blood Count Panel&limit=200`	Fetch panel-to-component mappings (CBC/LFT/etc.) including LOINC code metadata and sort order.	Bearer
GET	`/api/v3/pathology/panels?panel_type=PANEL&limit=200`	Dedicated pathology panel master endpoint for HMS panel catalog sync (`PANEL`/`META_PANEL`).	Bearer
GET	`/api/v3/pathology/component-masters?sub_category=Hematology&limit=200`	Dedicated pathology component master endpoint for HMS component catalog sync from `abdm_lab_test_master`.	Bearer
GET	`/api/v3/pathology/expand?entity_type=panel&id=1`	Expand panel/meta-panel into atomic tests and return printable template payload (`print_template`) with component tokens.	Bearer
GET	`/api/v3/surgeries/masters?procedure_type=SURGICAL&limit=200`	Fetch procedure master with `procedure_type` (`SURGICAL`/`NON_SURGICAL`), SNOMED CT code, body site and notes for OT/IPD/therapy catalog sync.	Bearer
GET	`/api/v3/radiology/masters?limit=200`	Fetch radiology/imaging master with SNOMED CT code, modality, body site, and ImagingStudy-oriented metadata.	Bearer
GET	`/api/v3/radiology/xray?limit=200`	Dedicated radiology X-Ray endpoint for HMS imaging catalog sync.	Bearer
GET	`/api/v3/radiology/ctscan?limit=200`	Dedicated radiology CT Scan endpoint for HMS imaging catalog sync.	Bearer
GET	`/api/v3/radiology/mri?limit=200`	Dedicated radiology MRI endpoint for HMS imaging catalog sync.	Bearer
GET	`/api/v3/radiology/ultrasound?limit=200`	Dedicated radiology Ultra Sound endpoint for HMS imaging catalog sync.	Bearer
GET	`/api/v3/surgeries/icd10pcs?limit=200`	Fetch surgery-to-ICD-10-PCS crosswalk for billing/package engines mapped with SNOMED CT procedures.	Bearer
GET	`/api/v3/master-data/immunization/uip/version`	Fetch latest active immunization schedule version code, effective date, and payload checksum.	Bearer
GET	`/api/v3/master-data/immunization/uip`	Fetch full baseline national UIP vaccination schedule catalog for HMS sync.	Bearer
GET	`/api/v3/master-data/immunization/uip/changes`	Fetch incremental delta updates since the HMS's current schedule version.	Bearer
SNOMED CT TERMINOLOGY API — HIGH PERFORMANCE SEARCH & LOOKUP
GET	`/api/search/suggest?term=fever&returnlimit=10`	Fast term auto-suggest for HMS clinical UI inputs (returns JSON array of term strings).	Public / Bearer
GET	`/api/search/search?term=fever&returnlimit=10`	Detailed concept search with FSN, concept status, and terminology metadata output.	Public / Bearer
GET	`/api/lookup/concept?id=386661006`	Full concept detail lookup with synonyms, FSN, module ID, and definition status.	Public / Bearer
GET	`/api/explore/parents?id=386661006`	Explore parent concepts in IS-A taxonomy hierarchy.	Public / Bearer
GET	`/api/explore/children?id=386661006`	Explore child concepts in IS-A taxonomy hierarchy.	Public / Bearer
GET	`/api/validate/id?id=386661006`	Validate if SCTID concept ID or description ID exists and is active.	Public / Bearer
GET	`/api/map/icdmap?id=386661006`	Fetch SNOMED CT to ICD-10 crosswalk extended map.	Public / Bearer
M3 HIU OPERATIONS
POST	`/api/v3/hiu/consent/request`	Create ABDM consent request for patient records	Bearer
POST	`/api/v3/hiu/consent/request/status`	Request status update for consent request from ABDM	Bearer
POST	`/api/v3/hiu/consent/request/fetch`	Initiate fetching details of granted consent artifact from ABDM	Bearer
POST	`/api/v1/hiu/data/request`	Initiate clinical data request flow from HIP to Gateway (Recommended)	Bearer
GET	`/api/v1/hiu/consent/status`	Poll/get local consent status & artifact info (for NAT backend)	Bearer
GET	`/api/v1/hiu/data/fetch`	Poll/get decrypted clinical records for a session (for NAT backend)	Bearer
M2 HIP OPERATIONS & FHIR BUNDLE
POST	`/api/v3/bundle/push`	Push FHIR R4 health document bundle to Gateway datastore	Bearer
UNIFIED BRIDGE (event dispatcher)
POST	`/api/v1/bridge`	Recommended for HMS — single event-based endpoint, routes to correct ABDM service automatically	Bearer
M2 USER-INITIATED LINKING (BRIDGE → HMS WEBHOOKS OVER VPN)
POST	`/records/discover` (or /v3/hip/patient/care-context/discover)	Bridge → HMS: Discover walk-in patient by verified mobile, gender, YOB, name; return care contexts	Bearer / HMAC
POST	`/records/link/init` (or /v3/hip/link/patient/care-context/init)	Bridge → HMS: Generate OTP & create link transaction for patient's care contexts	Bearer / HMAC
POST	`/records/link/confirm` (or /v3/hip/link/patient/care-context/confirm)	Bridge → HMS: Verify OTP, link ABHA address to patient, mark health records as linked	Bearer / HMAC
ABDM → BRIDGE CALLBACKS (Gateway calls Bridge; Bridge forwards to HMS)
POST	`/v3/hip/patient/care-context/discover`	ABDM calls bridge → Bridge forwards to HMS `/records/discover` → responds via `/on-discover`	ABDM
POST	`/v3/hip/link/patient/care-context/init`	ABDM calls bridge → Bridge forwards to HMS `/records/link/init` → responds via `/on-init`	ABDM
POST	`/v3/hip/link/patient/care-context/confirm`	ABDM calls bridge → Bridge forwards to HMS `/records/link/confirm` → responds via `/on-confirm`	ABDM
POST	`/v3/hip/patient/status/notify`	ABDM notifies patient link status change	ABDM
POST	`/api/hiecm/hip/v3/link/context/notify`	ABDM notifies HIP-initiated link completion	ABDM
POST	`/api/hiecm/data-flow/v3/health-information/hip/request`	ABDM requests health data — bridge pushes FHIR bundle to patient via dataPushUrl	ABDM
POST	`/api/hiecm/consent/v3/hip/notify`	ABDM notifies consent grant / revocation — bridge fires HMS webhook	ABDM
POST	`/api/v3/hip/token/on-generate-token`	ABDM delivers the generated JWT link token to bridge (HIP-initiated linking step 1 callback)	ABDM
POST	`/api/v3/link/on_carecontext`	ABDM confirms care-context linking result (HIP-initiated linking step 2 callback)	ABDM

Drug Terminology API How HMS should use CDCI APIs

HMS usage pattern: call /api/v3/drugs/autocomplete during typing, then call /api/v3/drugs/detail after user selection to store canonical identifiers in your HMS record. For Drug Company master sync, call /api/v3/drugs/masters?master=company. All endpoints use hospital Bearer token auth.

Data source clarification: in this gateway, drug endpoints (/api/v3/drugs/autocomplete, /api/v3/drugs/detail, /api/v3/drugs/masters) are served from the imported local CDCI dataset in gateway DB. ABDM upstream proxying applies to ABHA/HIECM flows, not to runtime drug master fetch in this integration.

Important for HMS: do not derive company names only from product records. If your HMS shows No company records found. Use Sync From API to seed company masters from drug payloads., run sync from /api/v3/drugs/masters?master=company and map items[].name as company name and items[].identifier as company code.

Response contract updates: autocomplete/search now include score, matched_on, and exact_match. Detail supports view=canonical (default) and view=hms_fill, including short_formulation for HMS UI fill. Standard errors use { ok, error_code, message, details, request_id }.

GET /api/v3/drugs/autocomplete

Use for search box suggestions (minimum 2 chars, limit defaults to 10).

Query Param	Required	Description
`q`	required	Typed search text, e.g. `par`
`type`	optional	`generic`, `brand`, `product`, `substance`
`limit`	optional	Max suggestions (1 to 50)

GET https://abdm-bridge.e-atria.in/api/v3/drugs/autocomplete?q=par&type=generic&limit=10
Authorization: Bearer {hospital-token}

GET /api/v3/drugs/search

Use for full results screen with pagination.

GET https://abdm-bridge.e-atria.in/api/v3/drugs/search?q=paracetamol&type=generic&limit=20&offset=0
Authorization: Bearer {hospital-token}

GET /api/v3/drugs/detail

Use after item selection to fetch structured details and save identifier in HMS. Add view=hms_fill to get HMS-oriented fields directly.

GET https://abdm-bridge.e-atria.in/api/v3/drugs/detail?type=generic&identifier=419367007&view=hms_fill
Authorization: Bearer {hospital-token}

POST /api/v3/drugs/detail/bulk

Resolve multiple identifiers in one call. Supports view=canonical or view=hms_fill.

POST https://abdm-bridge.e-atria.in/api/v3/drugs/detail/bulk
Authorization: Bearer {hospital-token}
Content-Type: application/json

{
  "type": "generic",
  "view": "hms_fill",
  "identifiers": ["419367007", "419477001"]
}

GET /api/v3/drugs/by-barcode

Barcode helper endpoint. Current CDCI import does not include barcode mapping, so this endpoint returns DATASET_UNAVAILABLE until enrichment is added.

GET https://abdm-bridge.e-atria.in/api/v3/drugs/by-barcode?barcode=8901234567890
Authorization: Bearer {hospital-token}

GET /api/v3/drugs/version

Use in admin/HMS diagnostics to verify CDCI data freshness and import counts.

GET https://abdm-bridge.e-atria.in/api/v3/drugs/version
Authorization: Bearer {hospital-token}

GET /api/v3/drugs/masters

Use this to sync normalized master data in HMS dropdowns and validation tables. Supports company, formulation, short_formulation, and generic. Source is local CDCI tables inside gateway DB.

Query Param	Required	Description
`master`	required	`company` \| `formulation` \| `short_formulation` \| `generic`
`q`	optional	Search filter (contains match)
`limit`	optional	Page size (default 100, max 500)
`offset`	optional	Pagination offset (default 0)

GET https://abdm-bridge.e-atria.in/api/v3/drugs/masters?master=company&limit=100
Authorization: Bearer {hospital-token}

{
    "ok": 1,
    "master": "company",
    "count": 2,
    "total": 1248,
    "items": [
        { "identifier": "SUPP-000123", "name": "Sun Pharma", "updated_at": "2026-05-25 09:11:10" },
        { "identifier": "SUPP-000987", "name": "Cipla", "updated_at": "2026-05-25 09:11:10" }
    ],
    "request_id": "REQ-20260525-abc"
}

GET /api/v3/drugs/formulation-mappings

Use this to map long CDCI formulation labels to HMS short labels. Returned effective_short_formulation already applies manual admin override when available.

Query Param	Required	Description
`q`	optional	Search in long/suggested/effective short labels
`overrides_only`	optional	`1`/`true` to fetch only manual overrides
`limit`	optional	Page size (default 100, max 500)
`offset`	optional	Pagination offset (default 0)

GET https://abdm-bridge.e-atria.in/api/v3/drugs/formulation-mappings?overrides_only=1&limit=100
Authorization: Bearer {hospital-token}

{
    "ok": 1,
    "count": 1,
    "total": 1,
    "items": [
        {
            "form_identifier": "371253001",
            "long_formulation": "Buccal spray",
            "suggested_short_formulation": "spray",
            "override_short_formulation": "spray",
            "effective_short_formulation": "spray",
            "has_override": 1,
            "updated_at": "2026-05-25 09:11:10",
            "override_updated_at": "2026-05-25 10:05:22"
        }
    ],
    "request_id": "REQ-20260525-def"
}

Pathology Master Sync API How HMS should sync test masters and panel components

HMS usage pattern: sync /api/v3/pathology/panels for panel catalog, sync /api/v3/pathology/component-masters for atomic pathology components, then use /api/v3/pathology/components for panel-to-component mapping. Use updated_since for incremental sync after initial bootstrap.

Data source: these APIs are served from gateway local tables (abdm_clinical_test_master and abdm_pathology_panel_components) curated from LOINC-oriented datasets and admin mappings. These are not live pull-through endpoints to ABDM.

GET /api/v3/pathology/masters

Use this for pathology test catalog sync in HMS. Returns test-level records from Clinical Test Master where category is Pathology.

Query Param	Required	Description
`q`	optional	Search in `test_name`, `display_name`, code, subcategory
`sub_category`	optional	Exact filter (e.g. `PATHOLOGY`, `Microbiology`)
`updated_since`	optional	Incremental sync filter on `updated_at` (YYYY-MM-DD HH:MM:SS)
`include_inactive`	optional	`1`/`true` to include inactive rows
`limit`	optional	Page size (default 200, max 1000)
`offset`	optional	Pagination offset (default 0)

GET https://abdm-bridge.e-atria.in/api/v3/pathology/masters?sub_category=PATHOLOGY&limit=200&offset=0
Authorization: Bearer {hospital-token}

{
    "ok": 1,
    "count": 2,
    "total": 15536,
    "items": [
        {
            "id": 1201,
            "category": "Pathology",
            "sub_category": "PATHOLOGY",
            "test_name": "Complete Blood Count Panel",
            "code_system": "LOINC",
            "code": "57021-8",
            "display_name": "CBC panel",
            "standard_rate": 450,
            "is_active": true,
            "updated_at": "2026-05-27 13:15:00"
        }
    ],
    "request_id": "REQ-20260527-abc"
}

GET /api/v3/pathology/components

Use this for panel to component sync. Each row represents one component test mapped to a parent panel.

Query Param	Required	Description
`parent_test`	optional	Exact parent panel name (recommended for on-demand component load)
`q`	optional	Search in parent/component/code fields
`updated_since`	optional	Incremental sync filter on `updated_at`
`include_inactive`	optional	`1`/`true` to include inactive rows
`limit`	optional	Page size (default 200, max 1000)
`offset`	optional	Pagination offset (default 0)

GET https://abdm-bridge.e-atria.in/api/v3/pathology/components?parent_test=Complete%20Blood%20Count%20Panel
Authorization: Bearer {hospital-token}

{
    "ok": 1,
    "count": 3,
    "total": 3,
    "items": [
        {
            "id": 10,
            "parent_test": "Complete Blood Count Panel",
            "component_test_name": "Hemoglobin",
            "component_code_system": "LOINC",
            "component_code": "718-7",
            "component_property": "MCnc",
            "component_system": "Bld",
            "component_scale": "Qn",
            "unit": "g/dL",
            "sort_order": 1,
            "is_active": true,
            "updated_at": "2026-05-27 13:15:00"
        }
    ],
    "request_id": "REQ-20260527-def"
}

GET /api/v3/pathology/panels

Dedicated panel catalog endpoint for HMS. Use this for panel and meta-panel masters.

Query Param	Required	Description
`q`	optional	Search in panel name, description, sub category, code
`panel_type`	optional	`PANEL` or `META_PANEL`
`sub_category`	optional	Exact panel sub category filter
`updated_since`	optional	Incremental sync filter on `updated_at`
`include_inactive`	optional	`1`/`true` to include inactive rows
`limit`	optional	Page size (default 200, max 1000)
`offset`	optional	Pagination offset (default 0)

GET https://abdm-bridge.e-atria.in/api/v3/pathology/panels?panel_type=PANEL&limit=200
    Authorization: Bearer {hospital-token}

GET /api/v3/pathology/component-masters

Dedicated pathology component master endpoint (atomic tests) for HMS local component catalog sync.

Query Param	Required	Description
`q`	optional	Search in component name, short name, and code
`sub_category`	optional	Exact pathology sub category filter
`updated_since`	optional	Incremental sync filter on `updated_at`
`include_inactive`	optional	`1`/`true` to include inactive rows
`limit`	optional	Page size (default 200, max 1000)
`offset`	optional	Pagination offset (default 0)

GET https://abdm-bridge.e-atria.in/api/v3/pathology/component-masters?sub_category=Hematology&limit=200
    Authorization: Bearer {hospital-token}

GET /api/v3/pathology/expand

Expands a panel/meta-panel to atomic tests for order/result engines and now also returns a ready print-template structure.

Query Param	Required	Description
`entity_type`	required	`panel`, `meta_panel`, or `test`
`id`	optional	Entity ID selector (recommended)
`name`	optional	Entity name selector (if id not supplied)
`code`	optional	Entity code selector (if id/name not supplied)
`include_inactive`	optional	`1`/`true` to include inactive rows
`max_depth`	optional	Max recursion depth for nested meta-panels (default 8)

GET https://abdm-bridge.e-atria.in/api/v3/pathology/expand?entity_type=panel&id=1
Authorization: Bearer {hospital-token}

{
    "ok": 1,
    "count": 8,
    "atomic_tests": [
        {
            "test_id": 1201,
            "test_name": "Hemoglobin",
            "short_name": "HB",
            "code": "718-7"
        }
    ],
    "print_template": {
        "print_format_html": "...",
        "default_print_format_html": "...",
        "edit_component_rule": [
            {
                "test_id": 1201,
                "test_name": "Hemoglobin",
                "short_name": "HB",
                "code": "718-7",
                "unit": "g/dL",
                "result_value_type": "NUMERIC",
                "is_optional": 0,
                "default_value": null,
                "validation_rule": "numeric|min:0|max:30",
                "normal_min": "12.0",
                "normal_max": "17.5",
                "female_normal_min": "12.0",
                "female_normal_max": "15.5",
                "age_min": "18",
                "age_max": "120",
                "age_unit": "YEAR",
                "notes": "Adult numeric rule"
            }
        ],
        "component_references": [
            { "name": "Hemoglobin", "code": "HB", "token": "{HB}" }
        ]
    },
    "request_id": "REQ-..."
}

GET Edit Component Rule

The expand API now returns an edit_component_rule array inside print_template, matching the admin Edit Component Rule modal fields.

Fields included:
- test_id, test_name, short_name, code, unit
- result_value_type, is_optional, default_value
- validation_rule
- normal_min, normal_max
- female_normal_min, female_normal_max
- age_min, age_max, age_unit
- notes

Recommended HMS Data Structure

Table 1: pathology_test_master
- test_code (unique)
- test_name
- display_name
- sub_category
- code_system
- standard_rate
- is_active
- updated_at

Table 2: pathology_panel_component_map
- parent_test_name
- component_test_name
- component_code
- component_property
- component_system
- component_scale
- unit
- sort_order
- is_active
- updated_at

Sync strategy: run full sync once (page through by limit/offset), then run incremental sync every few minutes using updated_since=last_success_sync_time.

Surgery Master API SNOMED CT mapped procedure catalog for OT + billing setup

Implementation strategy: use SNOMED CT as clinical procedure coding baseline. If your billing engine requires additional code sets (for example ICD-10-PCS), keep them in a local mapping table keyed by SNOMED CT.

FHIR export recommendation: surgeries should map to Procedure resource, imaging to DiagnosticReport (often with ImagingStudy), and lab values to Observation.

GET /api/v3/surgeries/masters

Sync starter/common surgeries and procedures into HMS OT master, package master, and billing mapping tables.

Query Param	Required	Description
`q`	optional	Search in procedure name, SNOMED code, body site, notes
`body_site`	optional	Filter by body site text (for example `Heart`, `Uterus`)
`snomed_code`	optional	Exact SNOMED CT code match
`procedure_type`	optional	Filter by `SURGICAL` or `NON_SURGICAL`
`updated_since`	optional	Incremental sync filter on `updated_at`
`include_inactive`	optional	`1`/`true` to include inactive rows
`limit`	optional	Page size (default 200, max 1000)
`offset`	optional	Pagination offset (default 0)

GET https://abdm-bridge.e-atria.in/api/v3/surgeries/masters?q=append&procedure_type=SURGICAL&limit=50
    Authorization: Bearer {hospital-token}

    {
        "ok": 1,
        "count": 1,
        "total": 20,
        "items": [
        {
            "procedure_name": "Appendectomy",
            "procedure_type": "SURGICAL",
            "snomed_ct_code": "80146002",
            "body_site": "Appendix",
            "notes": "Surgical removal of appendix",
            "billing_code_system": "SNOMED_CT",
            "billing_code": "80146002",
            "is_active": true
        }
        ],
        "request_id": "REQ-20260527-surgery"
    }

GET /api/v3/surgeries/icd10pcs

Related sub-table API for billing crosswalk. Keep SNOMED CT as clinical source and ICD-10-PCS as billing mapping.

Query Param	Required	Description
`q`	optional	Search in procedure name, SNOMED code, ICD-10-PCS code/title
`snomed_code`	optional	Exact SNOMED CT code filter
`icd10pcs_code`	optional	Exact ICD-10-PCS code filter
`updated_since`	optional	Incremental sync filter on `updated_at`
`include_inactive`	optional	`1`/`true` to include inactive rows
`limit`	optional	Page size (default 200, max 1000)
`offset`	optional	Pagination offset (default 0)

GET https://abdm-bridge.e-atria.in/api/v3/surgeries/icd10pcs?snomed_code=80146002&limit=50
Authorization: Bearer {hospital-token}

{
    "ok": 1,
    "count": 1,
    "total": 10,
    "items": [
        {
            "procedure_name": "Appendectomy",
            "snomed_ct_code": "80146002",
            "icd10_pcs_code": "0DTJ0ZZ",
            "icd10_pcs_title": "Resection of Appendix, Open Approach"
        }
    ],
    "request_id": "REQ-20260527-icdmap"
}

Radiology Master API SNOMED CT + ImagingStudy aligned imaging catalog

Implementation strategy: keep radiology modalities (XR, CT, MR, US, MG) as first-class fields in HMS and map clinical meaning with SNOMED CT.

FHIR export recommendation: create ImagingStudy for acquisition metadata and a DiagnosticReport referencing that ImagingStudy for narrative findings and impression.

GET /api/v3/radiology/masters

Sync radiology service master for RIS/PACS orderables, report templates, and billing mappings.

Query Param	Required	Description
`q`	optional	Search in imaging name, SNOMED code, modality, body site, notes
`modality`	optional	Exact modality code (for example `XR`, `CT`, `MR`, `US`, `MG`)
`body_site`	optional	Filter by body site text
`snomed_code`	optional	Exact SNOMED CT code match
`updated_since`	optional	Incremental sync filter on `updated_at`
`include_inactive`	optional	`1`/`true` to include inactive rows
`limit`	optional	Page size (default 200, max 1000)
`offset`	optional	Pagination offset (default 0)

GET https://abdm-bridge.e-atria.in/api/v3/radiology/masters?modality=CT&limit=50
Authorization: Bearer {hospital-token}

{
    "ok": 1,
    "count": 1,
    "total": 10,
    "items": [
        {
            "imaging_name": "CT Head Plain",
            "snomed_ct_code": "77477000",
            "modality": "CT",
            "body_site": "Head",
            "report_loinc_code": "24727-0",
            "fhir_focus_resource": "ImagingStudy",
            "is_active": true
        }
    ],
    "request_id": "REQ-20260527-radiology"
}

GET Dedicated Radiology Modality Endpoints

Use these dedicated endpoints when HMS wants separate modality-wise sync APIs without passing modality as a query parameter.

Endpoint	Description
`/api/v3/radiology/xray`	X-Ray modality focused catalog endpoint.
`/api/v3/radiology/ctscan`	CT Scan modality focused catalog endpoint.
`/api/v3/radiology/mri`	MRI modality focused catalog endpoint.
`/api/v3/radiology/ultrasound`	Ultra Sound modality focused catalog endpoint.

GET https://abdm-bridge.e-atria.in/api/v3/radiology/xray?limit=200
GET https://abdm-bridge.e-atria.in/api/v3/radiology/ctscan?limit=200
GET https://abdm-bridge.e-atria.in/api/v3/radiology/mri?limit=200
GET https://abdm-bridge.e-atria.in/api/v3/radiology/ultrasound?limit=200
Authorization: Bearer {hospital-token}

SNOMED CT Clinical Terminology API Native High-Performance REST Endpoints (Sub-15ms)

Native SNOMED CT Engine: This engine provides instant search, auto-completion, concept detail lookups, hierarchy navigation, and ICD-10 crosswalk mapping. All queries run directly against the indexed local gateway database with sub-15ms execution times.

GET /api/search/suggest

Fast type-ahead search endpoint for HMS clinical text inputs (e.g., OPD diagnosis, Chief Complaints, Procedures). Returns a JSON array of matching terms.

Parameter	Type	Description
`term`	required	Search prefix or phrase (e.g. `fever`, `diabetes`, `appendectomy`).
`returnlimit`	optional	Maximum results to return (default: `10`, max: `500`).
`semantictag`	optional	Filter by SNOMED semantic tag (e.g., `finding`, `disorder`, `procedure`).

GET https://csnotk.e-atria.in/api/search/suggest?term=fever&returnlimit=10

// Sample Response:
[
  "Fever",
  "Feverfew",
  "Feverish cold",
  "Fever seizure",
  "Fever blister",
  "Fever measures",
  "Fever symptoms",
  "Fever treatment",
  "Fever (finding)",
  "Fever of newborn"
]

GET /api/search/search

Detailed concept search endpoint returning full concept metadata (concept ID, term, FSN, definition status, effective time).

GET https://csnotk.e-atria.in/api/search/search?term=fever&returnlimit=2

// Sample Response:
[
  {
    "hierarchy": "finding",
    "isPreferredTerm": "1",
    "conceptState": "1",
    "conceptFsn": "Fever (finding)",
    "definitionStatus": "900000000000074008",
    "conceptId": "386661006",
    "languageCode": "en",
    "typeId": "SYNONYM",
    "term": "Fever",
    "caseSignificanceId": "CASE_INSENSITIVE",
    "id": "1480803010",
    "effectiveTime": "Jul 31, 2017, 12:00:00 AM",
    "activeStatus": 1,
    "moduleId": "900000000000207008"
  }
]

GET /api/lookup/concept

Retrieve complete concept details, including FSN, active status, module ID, definition status, and list of all synonym descriptions.

GET https://csnotk.e-atria.in/api/lookup/concept?id=386661006

// Sample Response:
{
  "descriptions": [
    {
      "hierarchy": "finding",
      "isPreferredTerm": "1",
      "conceptState": "1",
      "conceptFsn": "Fever (finding)",
      "definitionStatus": "900000000000074008",
      "conceptId": "386661006",
      "languageCode": "en",
      "typeId": "SYNONYM",
      "term": "Fever",
      "id": "1480803010",
      "activeStatus": 1
    }
  ],
  "relationships": [],
  "fsn": "Fever (finding)",
  "conceptId": "386661006",
  "definitionStatus": "900000000000074008",
  "active": true,
  "effectiveTime": "Jan 31, 2003, 12:00:00 AM",
  "module": "900000000000207008"
}

GET /api/explore/parents & /api/explore/children

Explore SNOMED CT taxonomy hierarchy up (parents) or down (children) for IS-A relationships.

GET https://csnotk.e-atria.in/api/explore/parents?id=386661006
GET https://csnotk.e-atria.in/api/explore/children?id=386661006

// Sample Response (Parents):
[
  {
    "definitionStatusId": "DEFINED",
    "fullySpecifiedName": "Body temperature above reference range (finding)",
    "preferredName": "Has a temperature",
    "id": "50177009",
    "effectiveTime": "Jul 31, 2018, 12:00:00 AM",
    "activeStatus": 1,
    "moduleId": "900000000000207008"
  }
]

GET /api/validate/id & /api/map/icdmap

Validate SCTID concept/description status, or fetch SNOMED CT to ICD-10 crosswalk mapping for billing engines.

GET https://csnotk.e-atria.in/api/validate/id?id=386661006
// Response: {"name":"result","valueString":"The concept 386661006 is valid","valueBoolean":true}

GET https://csnotk.e-atria.in/api/map/icdmap?id=386661006
// Response:
[
  {
    "referenced_component_id": "386661006",
    "map_target": "R50.9",
    "map_advice": "ALWAYS R50.9"
  }
]

Insurance Master API How HMS should fetch insurer/TPA mappings

POST /api/v3/benefit/search

Use this endpoint to retrieve insurance benefit eligibility/mapping data for patient-side workflows and claims pre-check flows in HMS.

POST https://abdm-bridge.e-atria.in/api/v3/benefit/search
Authorization: Bearer {hospital-token}
Content-Type: application/json

{
    "abhaAddress": "patient@sbx"
}

Immunization Master API How HMS should sync official UIP vaccination schedule catalog

Recommended HMS flow: check the active version using /api/v3/master-data/immunization/uip/version. If the checksum or version code differs from your local database, sync the full schedule using /api/v3/master-data/immunization/uip or fetch delta changes with /api/v3/master-data/immunization/uip/changes?since_version={local-version}.

GET /api/v3/master-data/immunization/uip/version

Retrieve version details, effective date, and SHA-256 data checksum of the active UIP schedule.

GET https://abdm-bridge.e-atria.in/api/v3/master-data/immunization/uip/version?hfr_id={hfr-id}
Authorization: Bearer {hospital-token}

{
    "ok": 1,
    "master_type": "UIP_SCHEDULE",
    "version_code": "GOI-UIP-2026-07",
    "effective_from": "2026-07-01",
    "checksum": "87b55b4c338d01b9dc05ed53020943aabadc6be28867c7e6b483f7168651fd6b"
}

GET /api/v3/master-data/immunization/uip

Fetch the entire baseline national UIP vaccination schedule catalog (all 26 seeded vaccine doses, offset days, route, site, and disease mappings).

GET https://abdm-bridge.e-atria.in/api/v3/master-data/immunization/uip?hfr_id={hfr-id}
Authorization: Bearer {hospital-token}

{
    "ok": 1,
    "version": {
        "version_code": "GOI-UIP-2026-07",
        "source_name": "NHM, Ministry of Health & Family Welfare, Government of India",
        "source_url": "https://nhm.gov.in/index1.php?lang=1&level=2&sublinkid=824&lid=117",
        "source_document_name": "National Immunization Schedule (NIS)",
        "effective_from": "2026-07-01",
        "checksum": "87b55b4c338d01b9dc05ed53020943aabadc6be28867c7e6b483f7168651fd6b"
    },
    "vaccines": [
        {
            "id": 1,
            "version_id": 1,
            "schedule_code": "UIP-BCG-BIRTH",
            "schedule_name": "UIP",
            "beneficiary_category": "child",
            "gender_applicability": "any",
            "age_label": "At Birth",
            "age_value": 0,
            "age_unit": "days",
            "age_offset_days": 0,
            "min_age_days": 0,
            "max_age_days": 365,
            "vaccine_code": "UIP-BCG",
            "dose_number": "1",
            "series_name": "BCG",
            "series_doses": 1,
            "route_name": "Intradermal",
            "site_name": "Left Upper Arm",
            "target_disease_name": "Tuberculosis",
            "is_state_specific": 0,
            "state_code": null,
            "district_code": null,
            "applicability_note": null,
            "notes": "Given at birth or as early as possible till 1 year of age",
            "sort_order": 1,
            "is_active": 1
        }
    ],
    "schedule": [ ... ]
}

GET /api/v3/master-data/immunization/uip/changes

Fetch incremental audit log changes since a specific schedule version.

GET https://abdm-bridge.e-atria.in/api/v3/master-data/immunization/uip/changes?since_version=GOI-UIP-2026-07&hfr_id={hfr-id}
Authorization: Bearer {hospital-token}

{
    "ok": 1,
    "from_version": "GOI-UIP-2026-07",
    "to_version": "GOI-UIP-2026-07",
    "changes": []
}

M2 User-Initiated Linking (Discovery & Linking) — HMS Developer Guide

📋 The Core Compliance Requirement Flagged by ABDM

The Problem: Previously, hospital software assumed that patients visiting the clinic already had an ABHA address linked in the HMS database before discovery (e.g. searching records with WHERE abha_id = 'user@sbx'). Because walk-in patients have no ABHA ID when registered at the hospital reception, this search always returned 0 records found in the PHR app.

The Compliant Flow: 1. Walk-in Registration (No ABHA) → 2. Visit / Prescription Created in HMS → 3. Patient opens PHR App at Home → 4. Demographic Discovery (Mobile + Gender + YOB + Name) → 5. OTP Link Verification → 6. Permanent ABHA Linked

Network Topology: ABDM Gateway ↔ Bridge ↔ Hospital HMS (over VPN)

[PHR App / ABHA App]
       │  (1. Patient searches Hospital by HFR ID: IN0510000871)
       ▼
[ABDM Gateway (dev.abdm.gov.in)]
       │  (2. Sends asynchronous webhooks to Bridge)
       ▼
[ABDM Bridge Gateway (abdm-bridge.e-atria.in)]
       │  (3. Forwards over VPN / HTTPS with Bearer & HMAC headers)
       ▼
[Hospital HMS Instance ({HMS_VPN_DOMAIN} / demo.e-atria.net)]
       │  - POST /records/discover     → Matches walk-in patient by Mobile, Gender, YOB, Name
       │  - POST /records/link/init    → Generates 6-digit OTP, stores link transaction
       │  - POST /records/link/confirm → Verifies OTP, links ABHA address, marks records linked
       ▼
[ABDM Bridge Gateway]
       │  (4. Sends asynchronous on-discover, on-init, on-confirm callbacks to ABDM Gateway)
       ▼
[ABDM Gateway → Patient PHR App: Care contexts successfully linked! ✅]
        

Endpoint 1: Patient Discovery

Route: POST /records/discover
Aliases: /v3/hip/patient/care-context/discover, /api/v1/abdm/gateway/discovery/care-contexts

Extracts verified mobile from patient.verifiedIdentifiers, gender, year-of-birth, and name. Queries patient_master and returns all visit care contexts.

Endpoint 2: Link Initiation (OTP)

Route: POST /records/link/init
Aliases: /v3/hip/link/patient/care-context/init, /api/v1/abdm/gateway/link/init

Receives selected care contexts, generates a 6-digit SMS OTP, creates a pending session in abdm_link_transactions, and returns masked mobile hint (e.g. 92******58).

Endpoint 3: Link Confirmation (Verify)

Route: POST /records/link/confirm
Aliases: /v3/hip/link/patient/care-context/confirm, /api/v1/abdm/gateway/link/confirm

Verifies OTP (test bypass 123456 in sandbox), updates patient_master.abha_address, sets health_records.push_status = 'linked', and completes link.

1 Step 1: Patient Discovery Specification (POST /records/discover)

The Bridge sends the patient's verified demographic identifiers received from the PHR app. Your HMS must match candidates in patient_master and return their care contexts.

INCOMING REQUEST FROM BRIDGE → HMS

POST {HMS_VPN_DOMAIN}/records/discover
Authorization: Bearer {EATRIA_BRIDGE_TOKEN}
X-Signature: sha256={HMAC_SHA256}
X-Eka-Signature: sha256={HMAC_SHA256}
X-Request-Id: {REQUEST_UUID}
Content-Type: application/json

{
  "requestId": "84b1d7d0-fb16-419b-a36c-9c922bc3ef32",
  "transactionId": "84b1d7d0-fb16-419b-a36c-9c922bc3ef32",
  "hipId": "IN0510000871",
  "mobile": "9212609558",
  "abhaAddress": "rahulsingh@sbx",
  "patient": {
    "id": "rahulsingh@sbx",
    "name": "Rahul Singh",
    "gender": "M",
    "yearOfBirth": 1999,
    "verifiedIdentifiers": [
      {
        "type": "MOBILE",
        "value": "+919212609558"
      }
    ],
    "unverifiedIdentifiers": []
  }
}

EXPECTED RESPONSE FROM HMS → BRIDGE (HTTP 200)

{
  "ok": 1,
  "patient": {
    "referenceNumber": "P26071000016",     // HMS Patient ID / UHID / p_code
    "display": "Rahul Singh",               // Patient Name
    "careContexts": [
      {
        "referenceNumber": "OPD-16-S1-20260909",  // Unique Visit / Prescription Ref
        "display": "OPConsultRecord - 09 Sep 2026"
      }
    ],
    "matchedBy": [
      "MOBILE",
      "GENDER",
      "YOB",
      "NAME"
    ]
  },
  "careContexts": [
    {
      "referenceNumber": "OPD-16-S1-20260909",
      "display": "OPConsultRecord - 09 Sep 2026"
    }
  ],
  "count": 1
}

Matching Criteria Algorithm for HMS Developers:

Mobile Matching: Extract 10 digits from verified mobile (e.g. 9212609558). Filter candidate patients in patient_master WHERE mphone1 = '9212609558'.
Gender Matching: Verify candidate gender matches (e.g. M matches 1 or MALE).
Year of Birth (±2 years tolerance): ABDM permits a 2-year tolerance window. If patient.yearOfBirth = 1999, match against YEAR(dob) BETWEEN 1997 AND 2001.
Name Verification: Ensure first name / last name matches with string similarity or substring match.
Care Contexts: Retrieve all clinical episodes (OPD prescriptions, lab tests, discharge summaries) for the matched patient_id.

2 Step 2: Link Initiation Specification (POST /records/link/init)

The PHR user has selected which care contexts to link. The Bridge requests the HMS to generate an OTP session for this patient.

INCOMING REQUEST FROM BRIDGE → HMS

POST {HMS_VPN_DOMAIN}/records/link/init
Authorization: Bearer {EATRIA_BRIDGE_TOKEN}
Content-Type: application/json

{
  "requestId": "f6b21c45-1234-4567-89ab-cdef01234567",
  "transactionId": "tx-e2e-79185ccc",
  "hipId": "IN0510000871",
  "patient": {
    "id": "rahulsingh@sbx",
    "referenceNumber": "P26071000016",
    "careContexts": [
      {
        "referenceNumber": "OPD-16-S1-20260909",
        "display": "OPConsultRecord - 09 Sep 2026"
      }
    ]
  }
}

EXPECTED RESPONSE FROM HMS → BRIDGE (HTTP 200)

{
  "ok": 1,
  "link": {
    "referenceNumber": "LNK-C86A70457F2E7EB4",
    "authenticationType": "DIRECT",
    "meta": {
      "communicationMedium": "MOBILE",
      "communicationHint": "92******58",
      "communicationExpiry": "2026-09-09T18:05:00+05:30"
    }
  },
  "linkRefNumber": "LNK-C86A70457F2E7EB4",
  "communicationHint": "92******58"
}

HMS Actions on Link Init: 1. Verify the patient exists by patient.referenceNumber.
2. Generate a secure 6-digit OTP (e.g. 123456 in sandbox / random OTP in production) and a unique link reference (e.g. LNK-HEX).
3. Store the OTP session in abdm_link_transactions with status = 'PENDING' and 10-minute expiry.
4. Dispatch SMS with OTP to the patient's phone and return the masked mobile hint (e.g. 92******58).

3 Step 3: Link Confirmation Specification (POST /records/link/confirm)

The patient entered the OTP in the PHR app. ABDM passes the OTP token to the Bridge, which forwards it to the HMS to verify and finalize the linking.

INCOMING REQUEST FROM BRIDGE → HMS

POST {HMS_VPN_DOMAIN}/records/link/confirm
Authorization: Bearer {EATRIA_BRIDGE_TOKEN}
Content-Type: application/json

{
  "requestId": "c4a1e902-5678-90ab-cdef-1234567890ab",
  "linkRefNumber": "LNK-C86A70457F2E7EB4",
  "token": "123456",
  "abhaAddress": "rahulsingh@sbx",
  "hipId": "IN0510000871"
}

EXPECTED RESPONSE FROM HMS → BRIDGE (HTTP 200)

{
  "ok": 1,
  "status": "confirmed",
  "patient": {
    "referenceNumber": "P26071000016",
    "display": "Rahul Singh",
    "careContexts": [
      {
        "referenceNumber": "OPD-16-S1-20260909",
        "display": "OPConsultRecord - 09 Sep 2026"
      }
    ]
  }
}

Database Updates required in HMS on Confirmation:

UPDATE patient_master SET abha_address = 'rahulsingh@sbx', abha_verified_status = 'LINKED', abdm_linked_at = NOW() WHERE id = {patient_id};
UPDATE health_records SET abha_id = 'rahulsingh@sbx', push_status = 'linked', linked_at = NOW() WHERE patient_id = {patient_id};
UPDATE abdm_link_transactions SET status = 'COMPLETED', updated_at = NOW() WHERE txn_id = 'LNK-C86A70457F2E7EB4';

HMS Database Migration (`abdm_link_transactions`)

Run this SQL on your HMS database to store pending OTP sessions:

CREATE TABLE IF NOT EXISTS `abdm_link_transactions` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
  `txn_id` varchar(120) NOT NULL,
  `patient_id` bigint unsigned NOT NULL,
  `patient_ref` varchar(80) NOT NULL,
  `abha_address` varchar(120) DEFAULT NULL,
  `otp` varchar(120) NOT NULL,
  `care_contexts` text,
  `status` varchar(30) NOT NULL DEFAULT 'PENDING',
  `expires_at` datetime NOT NULL,
  `created_at` datetime NOT NULL,
  `updated_at` datetime NOT NULL,
  PRIMARY KEY (`id`),
  KEY `idx_txn_id` (`txn_id`),
  KEY `idx_patient_id` (`patient_id`),
  KEY `idx_status` (`status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

Testing Each Step Locally via cURL

Run these cURL commands directly against your HMS server to verify:

# 1. Test Discovery
curl -X POST https://{HMS_DOMAIN}/records/discover \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 792d7fd09d7e37e11b107301959d36c9148a73f33e91e3db0f6d846cdb9617f5" \
  -d '{"hipId":"IN0510000871","patient":{"name":"Rahul Singh","gender":"M","yearOfBirth":1999,"verifiedIdentifiers":[{"type":"MOBILE","value":"+919212609558"}]}}'

# 2. Test Link Init
curl -X POST https://{HMS_DOMAIN}/records/link/init \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 792d7fd09d7e37e11b107301959d36c9148a73f33e91e3db0f6d846cdb9617f5" \
  -d '{"hipId":"IN0510000871","patient":{"referenceNumber":"P26071000016","id":"rahulsingh@sbx","careContexts":[{"referenceNumber":"OPD-16-S1-20260909"}]}}'

# 3. Test Link Confirm
curl -X POST https://{HMS_DOMAIN}/records/link/confirm \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 792d7fd09d7e37e11b107301959d36c9148a73f33e91e3db0f6d846cdb9617f5" \
  -d '{"linkRefNumber":"LNK-12345678","token":"123456","abhaAddress":"rahulsingh@sbx"}'

Ready-to-use PHP Controller Reference: A reference implementation containing the complete matching algorithms, OTP generation, and SQL queries is documented in walkthrough.md.

Health Records API HMS is source-of-truth; gateway orchestrates ABDM callbacks and transfers

Developer Contract: HMS_M2_GATEWAY_TO_HMS_API_CONTRACT.md | HMS_ABDM_PROMPT.md

Architecture (current policy): HMS is the clinical data source for M2. ABDM calls the gateway, and gateway fetches discovery/fetch data from HMS APIs (configured by hospital Domain Name in HMS credential settings). Gateway-local tables are for audit/orchestration metadata, not primary M2 clinical source.

REQUIRED HMS Source APIs for M2

Gateway calls these HMS APIs using https://{hms_domain} for each hospital:

GET /api/v1/abdm/gateway/health
POST /api/v1/abdm/gateway/discovery/care-contexts
POST /api/v1/abdm/gateway/health-information/fetch
POST /api/v1/abdm/gateway/consent/upsert
POST /api/v1/abdm/gateway/link/status

Security headers required on Gateway → HMS calls: Authorization: Bearer ..., X-Eka-Signature, X-Request-Id, X-Timestamp.

✓ HMS Integration Checklist

#	What HMS must do	Detail
★	Get a hospital-specific API token RECOMMENDED	Ask your gateway admin to create a Hospital User for your hospital (Admin → Hospital Users → Create User). Use the issued token as `Authorization: Bearer {token}`. Your hospital is auto-identified — no `hfr_id` field needed. Tokens can be regenerated or revoked per hospital without affecting others.
1	Generate a unique `care_context_reference` per visit	Use a pattern like `OPD-{YYYYMMDD}-{patientId}` or `IPD-{admissionId}`. Never reuse the same reference — a second push with the same value returns 409 DUPLICATE_RECORD with the existing record info.
2	Build a valid FHIR R4 document bundle	Must be `resourceType:"Bundle"`, `type:"document"`. First entry = `Composition`. Must include `Patient` + at least one clinical resource per HI type. See FHIR Bundle Guide for copy-paste examples.
3	Send correct `hi_type`	Must be one of the 8 ABDM values: `OPConsultRecord`, `PrescriptionRecord`, `DiagnosticReportRecord`, `DischargeSummaryRecord`, `ImmunizationRecord`, `WellnessRecord`, `HealthDocumentRecord`, `InvoiceRecord`
4	Store both `record_id` and `queue_id` from the 201 response	`record_id` — used to fetch/share the record later via GET `/records/{id}` or POST `/records/{id}/share`. `queue_id` — used to match the `record_linked_callback` webhook payload back to the HMS visit record.
5	Handle 409 DUPLICATE_RECORD	Do not treat this as an error. The response contains `existing_record_id` and `first_pushed_at`. Use `existing_record_id` for linking — no need to push again.
6	Handle 422 FHIR_VALIDATION_FAILED	Log the `errors[]` array from the response. Each entry has `code`, `field`, `message`. Fix your bundle builder and retry. The `warnings[]` array is non-blocking — ABDM will still accept the record.
7	Implement `record_linked_callback` webhook endpoint	The gateway fires a signed POST to `{HMS_BASE_URL}/AbdmGateway/record_linked_callback` when a patient links the record. Match on `queue_id`. Verify `X-Eka-Signature`. Return HTTP 200. See Webhooks section.

POST /api/v3/records/push Push FHIR health record from HMS to gateway

Field	Type	Required	Description
`hi_type`	string	required	ABDM HI type: `OPConsultRecord` \| `PrescriptionRecord` \| `DiagnosticReportRecord` \| `DischargeSummaryRecord` \| `ImmunizationRecord` \| `WellnessRecord` \| `HealthDocumentRecord` \| `InvoiceRecord`
`fhir_bundle`	object	required	Valid FHIR R4 Bundle (`resourceType:"Bundle"`, `type:"document"`). See FHIR Bundle Guide.
`care_context_reference`	string	required	Unique visit/episode ID per hospital, e.g. `OPD-2026-05-22-001`. Gateway rejects duplicates (409).
`abha_id`	string	one of*	14-digit ABHA number e.g. `91-5101-6530-5101`
`abha_address`	string	one of*	ABHA address e.g. `patient@abdm`
`patient_mobile`	string	one of*	10-digit mobile number e.g. `9720958717` (alias: `mobile`) — required for non-ABHA patients
`care_context_display`	string	optional	Human label shown in PHR app. Auto-generated if omitted: `OPConsultRecord — 2026-05-22 — Dr. Sharma`
`patient_name`	string	optional	Patient full name (stored in shared patient registry)
`local_patient_id`	string	optional	HMS internal patient MRN — stored in hospital sub-table for reference
`visit_date`	date	optional	Date of visit `YYYY-MM-DD`
`doctor_name`	string	optional	Treating doctor name
`department`	string	optional	Department / speciality
`gender`	string	optional	`M` \| `F` \| `O`
`year_of_birth`	number	optional	4-digit birth year e.g. `1979` (alias: `date_of_birth`)
`hfr_id`	string	required	Your hospital’s ABDM Facility Registry ID (e.g. `IN0510000828`). Required for all token types. With a hospital-specific API key the value is validated against the HFR ID registered to that key — a mismatch returns `403 HFR_ID_MISMATCH`. With the gateway master token a missing value returns `400 HFR_ID_REQUIRED` and an unregistered value returns `403 HFR_ID_NOT_REGISTERED`.

* At least one of abha_id, abha_address, or patient_mobile (or mobile) is required. For non-ABHA patients, push with patient_mobile and patient_name — ABDM Discovery will automatically match by Mobile Number when the patient uses the ABHA app later.

REQUEST (WITH ABHA ID)

POST https://abdm-bridge.e-atria.in/api/v3/records/push
Authorization: Bearer {api-key}
Content-Type: application/json

{
  "hi_type":               "OPConsultRecord",
  "care_context_reference": "OPD-2026-05-22-001",
  "care_context_display":   "OPD Visit — Dr. Sharma — 22 May 2026",
  "hfr_id":               "IN0510000828",  // ← Required for ALL token types — must match your registered HFR ID
  "abha_id":               "91-5101-6530-5101",
  "abha_address":          "meera.bisht@abdm",
  "patient_name":          "Meera Bisht",
  "local_patient_id":      "HMS-PAT-001",
  "visit_date":            "2026-05-22",
  "doctor_name":           "Sharma",
  "department":            "General OPD",
  "fhir_bundle":           { /* FHIR R4 Bundle — see guide below */ }
}

REQUEST (NON-ABHA PATIENT — MOBILE MATCHING)

POST https://abdm-bridge.e-atria.in/api/v3/records/push
Authorization: Bearer {api-key}
Content-Type: application/json

{
  "hi_type":               "PrescriptionRecord",
  "care_context_reference": "OPD-2026-07-23-901",
  "care_context_display":   "OPD Consultation — General Medicine",
  "hfr_id":               "IN0810000123",
  "patient_mobile":        "9720958717",       // ← Mobile number for non-ABHA patient
  "patient_name":          "Devender Singh",
  "gender":                "M",
  "year_of_birth":         1979,
  "local_patient_id":      "PAT-2026-09841",
  "visit_date":            "2026-07-23",
  "doctor_name":           "Dr. A. K. Sharma",
  "fhir_bundle":           { /* FHIR R4 Bundle */ }
}

RESPONSE (201) — store record_id & queue_id

{
  "ok": 1,
  "record_id": 42,             // ← store in HMS DB
  "queue_id": "REC-20260522-a1b2c3d4", // ← store in HMS DB
  "patient_id": 15,           // gateway patient id
  "care_context_reference": "OPD-2026-05-22-001",
  "care_context_display": "OPD Visit — Dr. Sharma — 2026-05-22",
  "hi_type": "OPConsultRecord",
  "fhir_validated": true,
  "fhir_warnings": [],       // non-blocking suggestions
  "hospital_id": 4, "hfr_id": "IN0510000828",
  "abdm_status": "pending",
  "pushed_at": "2026-05-22 10:30:00",
  "request_id": "REQ-20260522-xyz"
}

// Duplicate (409): same care_context_reference pushed again
{ "ok":0, "error":"DUPLICATE_RECORD",
  "existing_record_id":42, "first_pushed_at":"2026-05-22 10:30:00" }

// FHIR error (422): bundle has structural issues
{ "ok":0, "error":"FHIR_VALIDATION_FAILED",
  "errors":[{ "code":"INVALID_RECORD", "field":"fhir_bundle.entry",
    "message":"OPConsultRecord requires Condition or MedicationRequest" }] }

GET /api/v3/records

List records for this hospital. record_data and fhir_validation_log are omitted for performance — use GET /records/{id} for the full bundle.

GET /api/v3/records

// Query params (all optional):
// hi_type          exact match on ABDM HI type  (also: record_type)
// abha_id          filter by patient ABHA number
// abha_address     filter by ABHA address
// status           pending | shared | linked | failed | revoked
// queue_id         exact match on queue_id returned at push
// care_context_reference  exact match
// date_from        visit_date >= YYYY-MM-DD
// date_to          visit_date <= YYYY-MM-DD
// page, per_page   (default 1 / 25, max per_page 100)

GET /api/v3/records?abha_id=91-5101-6530-5101&status=pending

// Response
{
  "ok": 1,
  "data": [
    {
      "id": 42, "queue_id": "REC-20260522-a1b2c3d4",
      "abdm_patient_id": 15,
      "patient_name": "Meera Bisht",
      "abha_id": "91-5101-6530-5101",
      "abha_address": "meera.bisht@abdm",
      "record_type": "OPConsultRecord",
      "care_context_reference": "OPD-2026-05-22-001",
      "care_context_display": "OPConsultRecord — 2026-05-22 — Dr. Sharma",
      "visit_date": "2026-05-22",
      "doctor_name": "Sharma",
      "fhir_validated": 1,
      "abdm_status": "pending",
      "created_at": "2026-05-22 10:30:00"
    }
  ],
  "pagination": { "page": 1, "per_page": 25, "total": 1 }
}

GET /api/v3/records/{id} & POST /api/v3/records/{id}/share & POST /api/v3/records/{id}/link-and-share & GET /api/v3/records/{id}/workflow-status

GET returns full record including decoded fhir_bundle. POST /link-and-share is the recommended single HMS action: it submits link if needed and completes share once linked. GET /workflow-status provides pollable progress and next step.

GET /api/v3/records/42
{ "ok": 1, "data": {
    "id": 42, "abdm_status": "linked",
    "abdm_linked_at": "2026-05-22 11:45:00",
    "fhir_validated": 1,
    "fhir_validation_log": { "valid":true, "errors":[], "warnings":[] },
    "record_data": { "resourceType":"Bundle", "type":"document", /* full FHIR bundle */ }
} }

POST /api/v3/records/42/link-and-share
// If care-context not yet linked, endpoint submits link and returns 202.
{ "ok": 1, "care_context_status": "submitted", "message": "Care-context link submitted..." }

GET /api/v3/records/42/workflow-status
{ "ok": 1, "record": { "abdm_status": "pending" }, "care_context": { "status": "submitted" }, "next_action": "Complete HIP linking flow..." }

POST /api/v3/records/42/share
// Still supported as a direct/manual share endpoint.
{ "ok": 1, "message": "Share initiated", "status": "shared" }

// abdm_status lifecycle:
// pending → shared → linked
// pending → failed   (error from ABDM)
// linked  → revoked  (patient revokes consent)

FHIR Bundle Building Guide How to build a valid FHIR R4 document bundle for each HI type

FHIR R4 — Key Rule: Every bundle must be resourceType:"Bundle", type:"document". The first entry must always be a Composition resource with a subject (Patient reference). A Patient resource must also appear in the bundle entries. The gateway validates all of this and returns a detailed errors[] array if anything is wrong.

POST /api/v1/patient/sync Optional pre-sync of patient master from HMS

Use this when you want gateway patient registry to be ready before first clinical record. ABHA fields are optional.

POST https://abdm-bridge.e-atria.in/api/v1/patient/sync
Authorization: Bearer {api-key}
Content-Type: application/json

{
    "local_patient_id": "HMS12345",
    "abha_id": "1234-5678-9012",
    "abha_address": "devender@abdm",
    "name": "Devender Kumar",
    "gender": "male",
    "dob": "1990-05-12",
    "mobile": "9876543210",
    "email": "devender@example.com"
}

// Response
{ "ok": 1, "patient_id": 15, "local_patient_id": "HMS12345", "hospital_id": 4, "hfr_id": "IN0510000828" }
                

POST /api/v1/fhir/sync HMS wrapper that forwards to /api/v3/records/push

Use this when HMS has a single fhir_resource object (Encounter, DiagnosticReport, etc.). Gateway wraps it into a document bundle and pushes through the standard records pipeline.

POST https://abdm-bridge.e-atria.in/api/v1/fhir/sync
Authorization: Bearer {api-key}
Content-Type: application/json

{
    "local_patient_id": "HMS12345",
    "abha_id": "1234-5678-9012",
    "record_type": "OPD",
    "hfr_id": "IN0510000828",
    "fhir_resource": {
        "resourceType": "Encounter",
        "id": "enc123",
        "status": "finished"
    },
    "created_at": "2026-06-27T09:30:00"
}

// Response mirrors /api/v3/records/push (201 / 409 / 422, etc.)
                

8 ABDM HI Types — Required FHIR Resources

ABDM hi_type	Your HMS Record	Required FHIR Resources	Optional / Recommended
`OPConsultRecord`	OPD Consultation	`Composition` + `Patient` + one of: `Condition`, `MedicationRequest`, `Observation`	`Practitioner`, `Organization`, `AllergyIntolerance`, `ServiceRequest`, `Appointment`
`PrescriptionRecord`	OPD Prescription	`Composition` + `Patient` + `MedicationRequest`	`Practitioner`, `Organization`
`DiagnosticReportRecord`	Lab Report / Radiology	`Composition` + `Patient` + `DiagnosticReport`	`Observation` (test results), `ImagingStudy` (radiology), `DocumentReference` (PDF attachment)
`DischargeSummaryRecord`	IPD Discharge	`Composition` + `Patient` + `Encounter` + (`Condition` or `Procedure`)	`Practitioner`, `Organization`, `MedicationRequest`, `CarePlan`
`ImmunizationRecord`	Vaccination record	`Composition` + `Patient` + `Immunization`	`ImmunizationRecommendation`
`WellnessRecord`	Vitals / wellness	`Composition` + `Patient` + `Observation`	Multiple `Observation` entries (BP, SpO2, weight, glucose, etc.)
`HealthDocumentRecord`	Scanned / uploaded doc	`Composition` + `Patient` + `DocumentReference`	Binary attachment embedded in `DocumentReference.content.attachment`
`InvoiceRecord`	Billing / pharmacy invoice	`Composition` + `Patient` + `Invoice`	`Organization` (pharmacy/hospital)

Common Resources — Used in every HI type

Patient (required in all bundles)

{
  "resourceType": "Patient",
  "id": "pat-1",
  "name": [{ "text": "Meera Bisht",
              "family": "Bisht",
              "given": ["Meera"] }],
  "gender": "female",  // male | female | other | unknown
  "birthDate": "1992-07-15",
  "identifier": [{
    "type": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "NI" }] },
    "system": "https://healthid.ndhm.gov.in",
    "value": "91-5101-6530-5101"  // ABHA number
  }]
}

Practitioner (doctor) & Organization (facility)

// Practitioner
{
  "resourceType": "Practitioner",
  "id": "prac-1",
  "name": [{ "prefix": ["Dr."],
              "family": "Sharma",
              "given": ["Ramesh"] }]
}

// Organization (hospital / lab / pharmacy)
{
  "resourceType": "Organization",
  "id": "org-1",
  "name": "City General Hospital",
  "identifier": [{
    "system": "https://facility.ndhm.gov.in",
    "value": "IN0510000828"  // HFR facility ID
  }]
}

OPConsultRecord — Full FHIR Bundle Example

{
  "resourceType": "Bundle",
  "id": "bundle-opd-2026-05-22-001",
  "type": "document",
  "timestamp": "2026-05-22T10:30:00+05:30",
  "identifier": { "system": "https://in0510000828.hfr.abdm.gov.in", "value": "OPD-2026-05-22-001" },
  "entry": [
    { "resource": {
        "resourceType": "Composition", "id": "comp-1",
        "status": "final",
        "type": { "coding": [{ "system": "http://snomed.info/sct", "code": "371530004", "display": "Clinical consultation report" }] },
        "title": "OPD Consultation Note",
        "date": "2026-05-22",
        "subject": { "reference": "Patient/pat-1" },
        "author": [{ "reference": "Practitioner/prac-1" }],
        "section": [
          { "title": "Chief Complaints", "entry": [{ "reference": "Condition/cond-1" }] },
          { "title": "Medications",      "entry": [{ "reference": "MedicationRequest/med-1" }] }
        ]
    }},
    { "resource": { "resourceType": "Patient", "id": "pat-1",
        "name": [{ "text": "Meera Bisht", "family": "Bisht", "given": ["Meera"] }],
        "gender": "female", "birthDate": "1992-07-15",
        "identifier": [{ "system": "https://healthid.ndhm.gov.in", "value": "91-5101-6530-5101" }]
    }},
    { "resource": { "resourceType": "Practitioner", "id": "prac-1",
        "name": [{ "prefix": ["Dr."], "family": "Sharma", "given": ["Ramesh"] }]
    }},
    { "resource": { "resourceType": "Organization", "id": "org-1",
        "name": "City General Hospital",
        "identifier": [{ "system": "https://facility.ndhm.gov.in", "value": "IN0510000828" }]
    }},
    { "resource": { "resourceType": "Condition", "id": "cond-1",
        "subject": { "reference": "Patient/pat-1" },
        "code": { "coding": [{ "system": "http://snomed.info/sct", "code": "38341003", "display": "Hypertension" }] },
        "clinicalStatus": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/condition-clinical", "code": "active" }] }
    }},
    { "resource": { "resourceType": "MedicationRequest", "id": "med-1",
        "status": "active", "intent": "order",
        "subject": { "reference": "Patient/pat-1" },
        "medicationCodeableConcept": { "coding": [{ "system": "http://snomed.info/sct", "code": "372656004", "display": "Amlodipine" }] },
        "dosageInstruction": [{ "text": "5mg once daily after food" }]
    }}
  ]
}

OPConsultRecord - HMS Quick Check (Before Push)

Required for gateway acceptance

Bundle.resourceType must be Bundle
Bundle.type must be document
First entry must be Composition
Bundle must include a Patient entry
For OPConsultRecord, include at least one clinical resource: Condition or MedicationRequest or Observation

Strongly recommended for ABDM quality

Use SNOMED coding for diagnosis (Condition.code.coding)
Use coded medicine concept where possible (MedicationRequest.medicationCodeableConcept.coding)
Include Practitioner and Organization resources
Keep all date-time values in ISO 8601 with timezone

Common HMS mistakes and correct format

// Encounter period start must be ISO date-time:
Wrong: "start": "2026-05-27 05:58:37"
Right: "start": "2026-05-27T05:58:37+05:30"

// Condition should prefer coded SNOMED (not only text):
Better: "code": { "coding": [{ "system": "http://snomed.info/sct", "code": "386661006", "display": "Fever" }], "text": "Fever" }

// Medication should prefer coding + text:
Better: "medicationCodeableConcept": { "coding": [{ "system": "http://snomed.info/sct", "code": "387517004", "display": "Paracetamol" }], "text": "Paracetamol 500 mg tablet" }
                

Note for HMS: For end-to-end automation, use POST /api/v3/records/{id}/link-and-share and poll GET /api/v3/records/{id}/workflow-status. Use /share as manual fallback.

PrescriptionRecord

// Bundle structure same as OPConsultRecord.
// Composition.type.coding:
{ "system":"http://snomed.info/sct", "code":"440545006",
  "display":"Prescription record" }

// Required entry after Composition + Patient:
{ "resourceType": "MedicationRequest",
  "status": "active", "intent": "order",
  "subject": { "reference": "Patient/pat-1" },
  "medicationCodeableConcept": {
    "coding": [{ "system":"http://snomed.info/sct",
      "code": "387207008", "display": "Ibuprofen" }]
  },
  "dosageInstruction": [{ "text": "400mg twice daily after meals" }]
}

DiagnosticReportRecord (Lab / Radiology)

// Composition.type.coding:
{ "system":"http://snomed.info/sct", "code":"721981007",
  "display":"Diagnostic studies report" }

// Required DiagnosticReport entry:
{ "resourceType": "DiagnosticReport",
  "status": "final",
  "code": { "coding": [{ "system":"http://loinc.org",
    "code":"2339-0", "display":"Glucose [Mass/volume] in Blood" }] },
  "subject": { "reference": "Patient/pat-1" },
  "result": [{ "reference": "Observation/obs-1" }],
  "conclusion": "Blood glucose within normal range"
}
// Optional Observation (test result value):
{ "resourceType": "Observation", "id": "obs-1",
  "status": "final",
  "subject": { "reference": "Patient/pat-1" },
  "valueQuantity": { "value": 95, "unit": "mg/dL" }
}

DischargeSummaryRecord

// Composition.type.coding:
{ "system":"http://snomed.info/sct", "code":"373942005",
  "display":"Discharge summary" }

// Required Encounter entry:
{ "resourceType": "Encounter", "status": "finished",
  "class": { "system":"http://terminology.hl7.org/CodeSystem/v3-ActCode",
    "code":"IMP", "display":"inpatient encounter" },
  "subject": { "reference": "Patient/pat-1" },
  "period": { "start":"2026-05-15", "end":"2026-05-22" }
}
// Required Condition (diagnosis) entry:
{ "resourceType": "Condition",
  "subject": { "reference": "Patient/pat-1" },
  "code": { "coding": [{ "system":"http://snomed.info/sct",
    "code":"73211009", "display":"Diabetes mellitus" }] },
  "clinicalStatus": { "coding": [{ "code":"active" }] }
}

WellnessRecord / ImmunizationRecord / HealthDocumentRecord

// WellnessRecord — Observation for each vital:
{ "resourceType":"Observation", "status":"final",
  "subject":{ "reference":"Patient/pat-1" },
  "code":{ "coding":[{ "system":"http://loinc.org",
    "code":"8480-6", "display":"Systolic blood pressure" }] },
  "valueQuantity":{ "value":120, "unit":"mmHg" }
}

// ImmunizationRecord:
{ "resourceType":"Immunization", "status":"completed",
  "patient":{ "reference":"Patient/pat-1" },
  "vaccineCode":{ "coding":[{ "system":"http://snomed.info/sct",
    "code":"1119349007", "display":"COVID-19 mRNA vaccine" }] },
  "occurrenceDateTime":"2026-01-10",
  "lotNumber":"LOT-2026-001"
}

// HealthDocumentRecord (scanned PDF):
// CRITICAL: contentType MUST be "application/pdf", "image/jpeg", or "image/png"
// data MUST contain Base64 encoded file bytes (not raw HTML text).
// Also include Practitioner resource in bundle to avoid Practitioner Name showing NA in ABHA app.
{ "resourceType":"DocumentReference", "status":"current",
  "subject":{ "reference":"Patient/pat-1" },
  "content":[{ "attachment":{
    "contentType":"application/pdf",
    "data":"<base64-encoded-pdf-bytes>",
    "title":"Medical Record PDF"
  }}]
}

Common SNOMED CT Codes for Diagnoses & Medications

Concept	SNOMED Code	Display	Use in
Hypertension	`38341003`	Hypertensive disorder	Condition
Diabetes mellitus	`73211009`	Diabetes mellitus	Condition
Fever	`386661006`	Fever	Condition / Observation
Cough	`49727002`	Cough	Condition
Asthma	`195967001`	Asthma	Condition
Paracetamol / Acetaminophen	`387517004`	Paracetamol	MedicationRequest
Amoxicillin	`372687004`	Amoxicillin	MedicationRequest
Amlodipine	`372656004`	Amlodipine	MedicationRequest
Metformin	`372567009`	Metformin	MedicationRequest
Blood glucose (fasting)	LOINC `1558-6`	Fasting blood glucose	Observation
Systolic BP	LOINC `8480-6`	Systolic blood pressure	Observation
Diastolic BP	LOINC `8462-4`	Diastolic blood pressure	Observation
SpO2	LOINC `59408-5`	Oxygen saturation	Observation
Body weight	LOINC `29463-7`	Body weight	Observation

FHIR Validation Errors — Codes & Fixes

HTTP	error code	message example	Fix
`400`	`INVALID_HI_TYPE`	hi_type must be one of the 8 ABDM HI types	Use exact name: `OPConsultRecord`, `PrescriptionRecord`, etc. (case-sensitive)
`400`	`MISSING_FIELD`	fhir_bundle is required	Send `fhir_bundle` as a nested JSON object, not a string
`422`	`FHIR_VALIDATION_FAILED`	resourceType must be "Bundle"	Wrap your entire FHIR document in a `Bundle` object at the top level
`422`	`FHIR_VALIDATION_FAILED`	Bundle type must be "document"	Set `"type": "document"` on the Bundle (not `transaction` or `collection`)
`422`	`FHIR_VALIDATION_FAILED`	First entry must be Composition	Move the `Composition` resource to `entry[0]`
`422`	`FHIR_VALIDATION_FAILED`	Composition missing subject	Add `"subject": { "reference": "Patient/pat-1" }` to Composition
`422`	`FHIR_VALIDATION_FAILED`	No Patient resource found	Add a `Patient` resource entry to the bundle with `"id": "pat-1"`
`422`	`FHIR_VALIDATION_FAILED`	OPConsultRecord requires Condition or MedicationRequest	Add at least one clinical resource to the bundle
`409`	`DUPLICATE_RECORD`	care_context_reference already pushed	Check `existing_record_id` in response — use that instead of pushing again

HIP-Initiated Linking HMS triggers record linking on patient's ABHA without patient opening PHR app

When to use: After a patient visit, HMS can proactively link prescriptions, lab reports, or discharge summaries to the patient's ABHA directly from the HMS side. No action required from the patient. The flow is: HMS → bridge → ABDM link token → ABDM care-context link → linked ✓.

Implementation sequence: POST /api/v3/hfr/hrp/link (optional setup) → POST /api/v3/hip/link-token → POST /api/v3/hip/link/carecontext → GET /api/v3/hip/link/patient/links → POST /api/v3/hip/link/notify (when metadata changes) → POST /api/v3/hip/link/sms-notify.

ABDM app discovery/link (callback mode): ABDM calls /api/hiecm/user-initiated-linking/v3/patient/care-context/discover, /api/hiecm/user-initiated-linking/v3/link/care-context/init, and /api/hiecm/user-initiated-linking/v3/link/care-context/confirm. HMS should keep ABHA and care-context references accurate in pushed records.

HIP-Initiated Linking — 2-step async flow

POST /api/v3/hip/link-token → async callback /api/v3/hip/token/on-generate-token

HMS sends patient's ABHA details. Bridge calls ABDM /api/hiecm/v3/token/generate-token and returns a request_id immediately. ABDM delivers the JWT link_token asynchronously via the bridge callback (stored in abdm_link_tokens table). Decode the returned link_token_id to use in step 2.

POST /api/v3/hip/link/carecontext → async callback /api/v3/link/on_carecontext

HMS sends care context details with the link_token_id from step 1. Bridge calls ABDM /api/hiecm/hip/v3/link/carecontext with the JWT as X-LINK-TOKEN header. ABDM confirms linking via callback — bridge marks records as linked and fires record_linked_callback webhook to HMS.

Step 1 — Request Link Token

POST https://abdm-bridge.e-atria.in/api/v3/hip/link-token
Authorization: Bearer {api-key}

{
  "abha_address":  "meera.bisht@abdm",
  "abha_number":   "91-5101-6530-5101", // optional
  "name":          "Meera|Bisht",  // First|Last or First|Middle|Last
  "gender":        "F",           // M | F | O
  "year_of_birth": 1990
}

// Response (202) — token arrives asynchronously
{
  "ok": 1,
  "request_id":    "REQ-20260522-abc",
  "link_token_id": 7,   // use in step 2 once delivered
  "message": "Token arrives via on-generate-token callback"
}

Step 2 — Link Care Contexts

POST https://abdm-bridge.e-atria.in/api/v3/hip/link/carecontext
Authorization: Bearer {api-key}

{
  "abha_address":  "meera.bisht@abdm",
  "link_token_id": 7,   // from step 1 response
  "patient_ref":   "HMS-PAT-001",
  "display":       "Meera Bisht",
  "hi_type":       "Prescription",
  "care_contexts": [
    {
      "ref":     "OPD-2026-05-22-001",
      "display": "OPD Visit 22 May 2026"
    }
  ]
}

// Response (202)
{ "ok": 1, "request_id": "REQ-20260522-def",
  "message": "Care-context link request sent to ABDM." }

GET /api/v3/hip/link/patient/links

Fetch all care contexts currently linked in ABDM for a patient. Pass ?abha_address= or ?limit=.

GET /api/v3/hip/link/patient/links?abha_address=meera.bisht@abdm

// Response — ABDM patient links data
{ "ok": 1, "data": { /* ABDM patient links response */ } }

POST /api/v3/hip/link/notify & POST /api/v3/hip/link/sms-notify

notify — Push a care-context update notification to ABDM.
sms-notify — Trigger ABDM to send deep-link SMS to patient's registered mobile.

// notify
POST /api/v3/hip/link/notify
{ "abha_address": "meera.bisht@abdm",
  "care_context_reference": "OPD-2026-05-22-001",
  "hi_type": "Prescription",
  "date_of_record": "2026-05-22" }

// sms-notify
POST /api/v3/hip/link/sms-notify
{ "phone_number": "9876543210",
  "hip_name": "City Hospital" }  // optional

ABHA Integration Flows

✅ Gateway Auto-Saves Patient Profile
On every successful aadhaar/verify-otp or mobile/verify-otp, the gateway automatically saves the Aadhaar-verified patient data into its internal Patient Master (abdm_patients table). The response includes two extra fields so HMS can store and use them:

Response Field	Type	Description & HMS Usage
`patient_id`	integer	Gateway's internal patient ID. Store as `abdm_gateway_patient_id` in HMS patient record. Required when pushing health records.
`gateway_patient.abha_id`	string	14-digit ABHA number (no dashes) — store as `abha_number` in HMS
`gateway_patient.abha_address`	string	ABHA address e.g. `91510165305101@abdm` — required for Push ABDM
`gateway_patient.full_name`	string	Aadhaar-verified full name — auto-fill HMS patient name
`gateway_patient.gender`	`M` / `F` / `O`	Gender — auto-fill HMS gender
`gateway_patient.date_of_birth`	`YYYY-MM-DD`	Date of birth — auto-fill HMS DOB
`gateway_patient.mobile`	string	Registered mobile number
`gateway_patient.email`	string	Email address (if available from ABDM)
`gateway_patient.address_line`	string	Address from Aadhaar
`gateway_patient.district`	string	District name
`gateway_patient.state_name`	string	State name
`gateway_patient.pincode`	string	PIN code

Note: Blank fields from ABDM are never overwritten on repeat calls — existing verified data is always preserved.

🆕 Flow 1 — Create ABHA

Patient does not have ABHA yet. Requires Aadhaar number. 2 steps.
Response includes patient_id + gateway_patient with all Aadhaar-verified demographics.

🔗 Flow 2 — Link Existing ABHA

Patient already has ABHA. Requires registered mobile number. 2 steps.
Response includes patient_id + gateway_patient with verified profile for HMS auto-fill.

🆕 Flow 1: Create ABHA via Aadhaar OTP

1 POST /api/v3/abha/aadhaar/generate-otp

{ "aadhaar": "999941057058" }  // plain 12-digit — gateway encrypts it
// Response: { "ok": 1, "data": { "txnId": "c82482fa-...", "message": "OTP sent to ******8717" } }

2 POST /api/v3/abha/aadhaar/verify-otp

{ "txnId": "c82482fa-...", "otp": "123456", "mobile": "9876543210" }

// Response — ABHA created + full patient profile saved in gateway
{
  "ok": 1,
  "request_id": "REQ-20260601-abc",
  "patient_id": 1,           // gateway abdm_patients.id — store this in HMS
  "gateway_patient": {          // full Aadhaar-verified patient record — use to pre-fill HMS
    "id": 1,
    "abha_id": "91510165305101",
    "abha_address": "91510165305101@abdm",
    "full_name": "MEERA BISHT",
    "gender": "F",
    "date_of_birth": "1990-05-14",
    "mobile": "9876543210",
    "email": "meera@example.com",
    "address_line": "12 Main Street",
    "district": "Udham Singh Nagar",
    "state_name": "Uttarakhand",
    "state_code": "UK",
    "pincode": "263153",
    "last_verified_at": "2026-06-01 10:00:00"
  },
  "data": {                       // raw ABDM response — for reference / advanced use
    "ABHAProfile": { "ABHANumber": "91-5101-6530-5101", "name": "MEERA BISHT", "gender": "F", "...": "..." },
    "tokens": { "token": "eyJ...", "expiresIn": 1800 }
  }
}

ℹ️ HMS Action: Save patient_id in your HMS patient record as abdm_gateway_patient_id. Use gateway_patient fields to auto-fill Name, DOB, Gender, Mobile, Address. On repeat OTP flows for the same patient, only non-blank fields update — existing verified data is preserved.

👶 Flow 1.1: Create ABHA for Child / Dependent (with Parent's Alternate Mobile)

⚠️ CRITICAL HMS INTEGRATION NOTE: When creating an ABHA for a child or dependent who does not have their own phone number, use the parent's phone number as an Alternate Mobile Number.
Do NOT call POST /api/v3/abha/mobile/generate-otp without txnId for alternate mobile verification. Doing so triggers a Profile Login for the parent's mobile number, returning the parent's existing ABHA card instead of creating the child's ABHA card.

1 POST /api/v3/abha/aadhaar/generate-otp

{ "aadhaar": "999941057058" }  // child's plain 12-digit Aadhaar
// Response: { "ok": 1, "data": { "txnId": "c82482fa-...", "message": "OTP sent to Aadhaar-linked mobile" } }

2 POST /api/v3/abha/enrol/mobile/request-otp

{ "txnId": "c82482fa-...", "mobile": "9720958717" }  // parent's alternate mobile number

// Response
{ "ok": 1, "data": { "txnId": "c82482fa-...", "message": "OTP sent to alternate mobile ending with ******8717" } }

3 POST /api/v3/abha/enrol/mobile/verify-otp

{ "txnId": "c82482fa-...", "otp": "123456" }

// Response — Child's new ABHA created
{
  "ok": 1,
  "patient_id": 2,
  "gateway_patient": {
    "abha_id": "91510165305102",
    "full_name": "SON NAME",
    "mobile": "9720958717"
  },
  "data": {
    "ABHAProfile": { "ABHANumber": "91-5101-6530-5102", "name": "SON NAME" }
  }
}

🔗 Flow 2: Link Existing ABHA via Mobile OTP

1 POST /api/v3/abha/mobile/generate-otp

{ "mobile": "9999999999" }
// Response: { "ok": 1, "data": { "txnId": "1f491656-..." } }

2 POST /api/v3/abha/mobile/verify-otp

{ "txnId": "1f491656-...", "otp": "654321" }

// Response — profile verified + saved in gateway
{
  "ok": 1,
  "request_id": "REQ-20260601-xyz",
  "patient_id": 1,           // gateway abdm_patients.id — store this in HMS
  "gateway_patient": {          // full verified patient record
    "id": 1,
    "abha_id": "91510165305101",
    "abha_address": "91510165305101@abdm",
    "full_name": "MEERA BISHT",
    "gender": "F",
    "date_of_birth": "1990-05-14",
    "mobile": "9999999999",
    "district": "Udham Singh Nagar",
    "state_name": "Uttarakhand",
    "pincode": "263153",
    "last_verified_at": "2026-06-01 10:00:00"
  },
  "data": {                       // raw ABDM response
    "authResult": "success",
    "profile": { "ABHANumber": "91-5101-6530-5101", "name": "MEERA BISHT", "mobile": "9999999999", "...": "..." },
    "token": "eyJ..."
  }
}

ℹ️ HMS Action: Save patient_id in HMS as abdm_gateway_patient_id. Auto-fill patient demographics from gateway_patient. Also includes token in data for ABHA card download via GET /api/v3/abha/card?token=....

OPD Queue & Facility API

Endpoint	Description	Key Fields
GET `/api/v3/facility/qr-code`	Get facility details and official QR code Base64 string	Returns `hospital_id`, `hospital_name`, `hfr_id`, `qr_data`
POST `/api/v3/opd/token`	Create manual token for walk-in patient	`patient_name`, `phone`, `abha_number`, `gender`, `department`, `department_code`, `date`
GET `/api/v3/opd/queue`	List queue with pagination — optional `?date=YYYY-MM-DD&status=PENDING`	Returns `summary`, `pagination`, and `tokens[]` with `token_number`, `status`, `abha_number`, `source`
PATCH `/api/v3/opd/token/{id}`	Update token status	`status`: `PENDING` \| `CALLED` \| `COMPLETED` \| `CANCELLED`
GET `/api/v3/opd/running-token-status`	Get current token being served (for display boards)	Returns `token_number`, `department`

// Fetch facility details & official ABDM QR Code GET /api/v3/facility/qr-code // Response: { "ok": 1, "hospital_id": 8, "hospital_name": "E-Atria Hospital", "hfr_id": "IN0510000871", "qr_data": "data:image/png;base64,iVBORw0KG..." } // Create manual OPD token (walk-in) POST /api/v3/opd/token { "patient_name": "Ramesh Kumar", "phone": "9876543210", "abha_number": "91-5101-6530-5101", "gender": "M", "department": "General OPD", "department_code": "773568002" } // Response: { "ok": 1, "token_id": 15, "token_number": 15, "status": "PENDING" } // List OPD queue (status filter uses uppercase values) GET /api/v3/opd/queue?date=2026-05-24&status=PENDING&page=1&limit=50 // Response includes summary + pagination { "ok": 1, "summary": { "pending": 2, "called": 1, "completed": 5, "cancelled": 0 }, "tokens": [ { "id": 15, "token_number": 15, "status": "PENDING", "source": "scan_share" } ] } // Update status PATCH /api/v3/opd/token/15 { "status": "CALLED" } // Response: { "ok": 1, "token_id": 15, "token_number": 15, "patient_name": "Ramesh Kumar", "status": "CALLED" }

Unified Bridge API (Recommended for HMS integration)

POST /api/v1/bridge — event dispatcher

Send a single event_type with a payload. The bridge routes it to the correct ABDM service automatically.

POST https://abdm-bridge.e-atria.in/api/v1/bridge
Authorization: Bearer {api-key}
{ "event_type": "abdm.abha.validate", "payload": { "abha_id": "14-1234-5678-9012" } }

// Response
{ "ok": 1, "event_type": "abdm.abha.validate", "request_id": "REQ-20260518-abc",
  "dispatch": { "ok": 1, "http_code": 200, "response": { /* ABDM response */ } } }

Supported Event Types

event_type	Description	Required payload fields
`abdm.abha.validate`	Validate ABHA ID	`abha_id` or `abha_address`
`abdm.consent.requested`	Request patient consent	`abha_id`, `purpose_code`, `hi_types[]`
`abdm.fhir.share.requested`	Push any FHIR document	`consent_handle`, `hi_type`, `bundle{}`
`abdm.opd.prescription.share.requested`	Share OPD prescription	`consent_handle`, `bundle{}`
`abdm.ipd.admission.share.requested`	Share IPD admission summary	`consent_handle`, `bundle{}`
`abdm.ipd.discharge.share.requested`	Share IPD discharge summary	`consent_handle`, `bundle{}`
`abdm.diagnosis.report.share.requested`	Share diagnostic report	`consent_handle`, `bundle{}`
`abdm.scan_share.lookup`	SNOMED CT term lookup	`term`, `return_limit` (optional)

ABDM → Bridge Callbacks & HMS VPN Forwarding Gateway callbacks forwarded to HMS in real-time

How Bridge Forwarding Works: ABDM calls these endpoints on the Bridge Gateway when patients interact with their PHR / ABHA app. The Bridge immediately forwards the payload over VPN / HTTPS to your Hospital HMS (/records/discover, /records/link/init, /records/link/confirm), waits for your HMS JSON response, and dispatches the corresponding asynchronous on-discover, on-init, and on-confirm callbacks back to ABDM Gateway. See the dedicated M2 User-Initiated Linking Guide above for implementation details.

User-Initiated Linking — Real-Time Gateway → Bridge → HMS Forwarding Flow

POST /v3/hip/patient/care-context/discover → HMS /records/discover

ABDM asks: “What records does this patient have at this HIP?” Bridge calls HMS POST {HMS_VPN_DOMAIN}/records/discover with verified mobile, gender, YOB, and name. HMS returns matching care contexts, and Bridge responds to ABDM via /on-discover.

POST /v3/hip/link/patient/care-context/init → HMS /records/link/init

ABDM sends selected care contexts to link. Bridge calls HMS POST {HMS_VPN_DOMAIN}/records/link/init. HMS generates OTP & masked hint, Bridge creates a link session in abdm_link_sessions, and responds to ABDM via /on-init.

POST /v3/hip/link/patient/care-context/confirm → HMS /records/link/confirm

Patient enters OTP in PHR app. Bridge calls HMS POST {HMS_VPN_DOMAIN}/records/link/confirm to verify OTP and link ABHA in HMS. Bridge marks local records as linked, calls ABDM /on-confirm, and completes the link transaction.

// Example: ABDM sends discover to bridge
POST /api/hiecm/user-initiated-linking/v3/patient/care-context/discover
Authorization: Bearer {abdm-gateway-token}

{
  "requestId": "ABDM-REQ-UUID", "transactionId": "TX-UUID",
  "hip": { "id": "HIP-ID" },
  "patient": { "id": "91-5101-6530-5101" }
}
// Bridge: 202 Accepted, then calls ABDM /on-discover with care contexts

POST /api/hiecm/hip/v3/link/context/notify

ABDM notifies bridge when a HIP-initiated link (via /records/{id}/share) is confirmed. Bridge marks record as linked and fires record_linked_callback to HMS.

{ "notification": {
    "careContext": {
      "patientReference":    "91-5101-...",
      "careContextReference": "OPD-2026-05-18-001"
    }
} }
// Bridge: 202, marks record linked, fires HMS webhook

POST /api/hiecm/data-flow/v3/health-information/hip/request

ABDM requests health data after consent is granted. Bridge acknowledges, fetches consent-scoped FHIR data from HMS API /api/v1/abdm/gateway/health-information/fetch, pushes to dataPushUrl, and notifies ABDM of completion.

{ "requestId": "REQ-UUID", "transactionId": "TX-UUID",
  "hiRequest": {
    "consent": { "id": "CONS-UUID" },
    "dateRange": { "from": "2026-01-01T00:00:00Z", "to": "2026-05-18T23:59:59Z" },
    "dataPushUrl": "https://abdm.gov.in/health-info/transfer/..."
  }
}
// Bridge: acknowledges → fetches records → pushes FHIR bundle → notifies ABDM

POST /api/hiecm/consent/v3/hip/notify — Consent notification

ABDM notifies bridge when a patient grants or revokes consent for this HIP.

On GRANTED:

{ "notification": {
    "consentId": "CONS-UUID",
    "status": "GRANTED",
    "patient": { "id": "91-5101-..." }
} }
// Bridge stores consentId on records,
// calls ABDM /hip/on-notify to ack

On REVOKED:

{ "notification": {
    "consentId": "CONS-UUID",
    "status": "REVOKED",
    "revokedAt": "2026-05-18T12:00:00Z"
} }
// Bridge marks records revoked,
// fires HMS consent_revoked_callback

HIU Consent Flow: To query patient records from other hospitals, the HMS must:

Initiate consent by calling POST /api/v3/hiu/consent/request.
Poll for status changes using GET /api/v1/hiu/consent/status.
Once status is GRANTED, fetch the consent artifact using POST /api/v3/hiu/consent/request/fetch.
Request data flow using POST /api/v1/hiu/data/request.

POST /api/v3/hiu/consent/request

Creates a consent request to ask the patient for permission to view their health records.

POST https://abdm-bridge.e-atria.in/api/v3/hiu/consent/request
Authorization: Bearer {hospital-token}
Content-Type: application/json

{
  "hfr_id": "IN0510000871",
  "requestId": "b2d08c9f-2a4e-4555-aebd-6b7f88bf4a16",
  "timestamp": "2026-07-01T10:30:00.000Z",
  "consent": {
    "purpose": {
      "code": "CAREMGT",
      "text": "Care Management",
      "refUri": "https://abdm.gov.in"
    },
    "patient": {
      "id": "someone@sbx"
    },
    "hiu": {
      "id": "IN0510000871"
    },
    "requester": {
      "name": "E-Atria Hospital"
    },
    "hiTypes": ["OPConsultation", "DiagnosticReport"],
    "permission": {
      "accessMode": "VIEW",
      "dateRange": {
        "from": "2026-06-01T00:00:00.000Z",
        "to": "2026-07-01T00:00:00.000Z"
      },
      "dataEraseAt": "2027-07-01T00:00:00.000Z",
      "frequency": {
        "unit": "HOUR",
        "value": 1,
        "repeats": 0
      }
    }
  }
}

// Response
{
  "ok": 1,
  "request_id": "REQ-...",
  "http_code": 202,
  "data": {
    "consentRequestId": "c7c8fed7-1180-468f-bce8-ff192eb1bbaf"
  }
}

POST /api/v3/hiu/consent/request/status

Requests the current status of a consent request from ABDM.

POST https://abdm-bridge.e-atria.in/api/v3/hiu/consent/request/status
Authorization: Bearer {hospital-token}
Content-Type: application/json

{
  "hfr_id": "IN0510000871",
  "requestId": "cb95ee8f-2ae4-4d50-840f-538f6097786c",
  "timestamp": "2026-07-01T10:35:00.000Z",
  "consentRequestId": "c7c8fed7-1180-468f-bce8-ff192eb1bbaf"
}

// Response
{
  "ok": 1,
  "request_id": "REQ-...",
  "http_code": 202
}

POST /api/v3/hiu/consent/request/fetch

Initiates a request to fetch the granted consent artifact details from ABDM after status changes to GRANTED.

POST https://abdm-bridge.e-atria.in/api/v3/hiu/consent/request/fetch
Authorization: Bearer {hospital-token}
Content-Type: application/json

{
  "hfr_id": "IN0510000871",
  "requestId": "f7d78373-0906-4180-a2e2-a95a0246db88",
  "timestamp": "2026-07-01T10:36:00.000Z",
  "consentId": "699f4dc3-d033-41b9-ae63-b5cc24af2e20"
}

// Response
{
  "ok": 1,
  "request_id": "REQ-...",
  "http_code": 202
}

HMS → Gateway Polling & Reconciliation For HMS instances running behind NAT

Architecture Note: Since HMS instances run locally behind a NAT layer, the Gateway cannot connect to them directly. Instead of relying on outbound webhooks, HMS should poll the Gateway using these secure endpoints to fetch consent updates and decrypted clinical records.

GET /api/v1/hiu/consent/status

Reconcile or check status of a consent request. Supply either the original HMS request_id, the ABDM consent_request_id, or the granted consent_id (artifact ID).

Param	Required	Description
`request_id`	optional	Original HMS request_id (e.g. `REQ-CONSENT-...`)
`consent_request_id`	optional	ABDM-generated consent request ID
`consent_id`	optional	ABDM-granted consent artifact ID

GET https://abdm-bridge.e-atria.in/api/v1/hiu/consent/status?request_id=REQ-HIU-12345
Authorization: Bearer {hospital-token}

// Response when PENDING (Waiting for patient approval)
{
  "ok": 1,
  "consent": {
    "consent_request_id": "72fedbb4-87dc-4667-8565-82597aea3a75",
    "status": "REQUESTED"
  },
  "request_id": "REQ-..."
}

// Response when GRANTED (Patient approved)
{
  "ok": 1,
  "consent": {
    "consent_id": "9ad70f81-cfde-444f-a377-77a23853a002",
    "consent_request_id": "72fedbb4-87dc-4667-8565-82597aea3a75",
    "status": "GRANTED",
    "abha_address": "patient@sbx",
    "purpose": "Care Management",
    "hi_types": ["OPConsultRecord"],
    "date_range": {
      "from": "2026-06-03T19:57:16Z",
      "to": "2026-07-03T19:57:16Z"
    },
    "expiry": "2027-07-03T19:57:16Z",
    "granted_at": "2026-07-04T01:27:48Z"
  },
  "request_id": "REQ-..."
}

GET /api/v1/hiu/data/fetch

Poll for decrypted clinical FHIR records. You can supply a transaction_id, a consent_id (artifact ID), or the original consent_request_id in the consent_id parameter to retrieve all merged hospital records at once.

Param	Required	Description
`transaction_id`	optional	The transaction ID generated for the data flow request
`consent_id`	optional	The granted consent artifact ID (UUID) OR the original `consent_request_id`

GET https://abdm-bridge.e-atria.in/api/v1/hiu/data/fetch?consent_id=REQ-CONSENT-12345
Authorization: Bearer {hospital-token}

// Response containing decrypted FHIR records from all sessions
{
  "ok": 1,
  "count": 1,
  "sessions": [
    {
      "transaction_id": "TXN-12345",
      "consent_id": "9ad70f81-cfde-444f-a377-77a23853a002:REQ-...",
      "status": "received",
      "decrypted_data": [
        {
          "careContextReference": "OPD-2026-05-18-001",
          "media": "application/fhir+json",
          "decrypted_data": "{\"resourceType\":\"Bundle\",...}"
        }
      ],
      "created_at": "2026-07-04 01:27:22"
    }
  ],
  "request_id": "REQ-..."
}

POST /api/v1/hiu/data/request (Auto-Managed by Gateway)

Note: Under the NAT/VPN model, the gateway automatically handles fetching consent details and triggering the data requests once a consent is GRANTED. You do not need to call this endpoint manually unless you wish to explicitly re-trigger a request.

CRITICAL FOR STABILITY (ABDM-1063): The date range in dateRange must fall strictly inside or equal to the granted consent date range. You MUST NOT strip or modify the millisecond/timezone format (e.g. preserve .379Z or +05:30 exactly as returned by the Consent Status endpoint). Stripping fractional seconds will lead to immediate ABDM-1063: Date Range given is invalid errors.

POST https://abdm-bridge.e-atria.in/api/v1/hiu/data/request
Authorization: Bearer {hospital-token}
Content-Type: application/json

{
  "hiRequest": {
    "consent": {
      "id": "0a3dd462-8923-4e98-b8c1-66ab542610f2"
    },
    "dateRange": {
      "from": "2026-06-01T00:00:00.000Z",
      "to": "2026-07-04T00:00:00.000Z"
    },
    "dataPushUrl": "https://abdm-bridge.e-atria.in/api/v3/hiu/data/push",
    "transactionId": "TXN-12345"
  }
}

// Response
{
  "ok": 1,
  "request_id": "REQ-...",
  "http_code": 202,
  "data": {
    "status": "ACKNOWLEDGED",
    "transactionId": "TXN-12345"
  }
}

Bridge → HMS Webhooks Bridge calls these on your HMS server

Setup: Configure hospital Domain Name in Admin → HMS Credential and set HMS_WEBHOOK_SECRET. The bridge resolves https://{hms_domain} and POSTs signed JSON when ABDM events occur. Always verify X-Eka-Signature before processing.

Verify Incoming Webhooks (HMAC-SHA256)

// Every webhook includes this header:
X-Eka-Signature: sha256=<hmac_hex>

// PHP verification
$expected = 'sha256=' . hash_hmac('sha256', file_get_contents('php://input'), getenv('HMS_WEBHOOK_SECRET'));
if (!hash_equals($expected, $_SERVER['HTTP_X_EKA_SIGNATURE'] ?? '')) { http_response_code(401); exit; }

// Python verification
import hmac, hashlib
expected = 'sha256=' + hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
assert hmac.compare_digest(expected, request.headers['X-Eka-Signature'])

POST {HMS_BASE_URL}/AbdmGateway/record_linked_callback

Fired when a care context record is successfully linked to a patient's ABHA in ABDM (user-initiated or HIP-initiated).

// Payload
{
  "queue_id":               "REC-20260518-a1b2c3d4",
  "care_context_reference": "OPD-2026-05-18-001",
  "abha_id":               "91-5101-6530-5101",
  "abha_address":          "meera.bisht@abdm",
  "record_type":           "OPConsultRecord",  // ABDM hi_type value
  "linked_at":             "2026-05-18 11:45:00",
  "source": "user_initiated"  // or "hip_initiated"
}
// Expected response from HMS: HTTP 200

POST {HMS_BASE_URL}/AbdmGateway/consent_revoked_callback

Fired when a patient revokes consent. Bridge also marks all linked records for this ABHA as revoked automatically.

// Payload
{
  "consent_handle": "CONS-UUID",
  "abha_id":        "91-5101-6530-5101",
  "revoked_at":     "2026-05-18T12:00:00Z"
}
// Expected response from HMS: HTTP 200

POST {HMS_BASE_URL}/api/v1/abdm/gateway/consent/upsert

Fired when ABDM notifies the gateway about GRANTED, REVOKED, or EXPIRED consent status changes. Your HMS must capture the consent_id and store it to initiate data flows.

// Payload
{
  "request_id":      "REQ-20260704012748-abcd",
  "hospital_hfr_id": "IN0510000870",
  "consent_id":      "9ad70f81-cfde-444f-a377-77a23853a002",
  "status":          "GRANTED",  // "GRANTED", "REVOKED", or "EXPIRED"
  "abha_id":         "patient@sbx",
  "abha_address":    "patient@sbx",
  "date_range": {
    "from": "2026-06-03T19:57:16Z",  // optional (supplied during fetch)
    "to":   "2026-07-03T19:57:16Z"
  },
  "hi_types": ["OPConsultRecord", "DiagnosticReportRecord"], // optional
  "raw_notification": {}
}
// Expected response from HMS: HTTP 200

Error Reference

HTTP	error code	Meaning	Recommended Action
`200`	ok: 1	Success	Process `data` or `dispatch` object
`201`	ok: 1	Resource created (health record push)	Store returned `record_id` + `queue_id` in HMS DB
`202`	`status: accepted`	Async accepted (ABDM callbacks, share triggers)	No further action; callback webhook fires on completion
`400`	`MISSING_FIELD`	Required field missing or empty (`hi_type`, `fhir_bundle`, `care_context_reference`, or ABHA identifier)	Check request body — add the missing field listed in `message`
`400`	`INVALID_HI_TYPE`	`hi_type` is not one of the 8 ABDM values	Response includes `valid_types[]` — use one of those exact strings
`401 / 403`	`UNAUTHORIZED`	Invalid or missing API key	Verify `Authorization: Bearer <key>` header is correct
`404`	`NOT_FOUND`	Record ID not found	Confirm the ID exists and belongs to your hospital
`409`	`DUPLICATE_RECORD`	Same `care_context_reference` already pushed for this hospital	Not a failure — response includes `existing_record_id` + `first_pushed_at`. Use the existing record for linking.
`422`	`FHIR_VALIDATION_FAILED`	FHIR bundle has structural errors (wrong bundle type, missing Composition, missing required clinical resource)	Read `errors[]` array — each entry has `code`, `field`, `message`. The `warnings[]` are non-blocking. Fix bundle and retry.
`500`	`SERVER_ERROR`	Gateway internal error	Log the `request_id` and retry once. If persists, contact admin.

E-Atria — ABDM Bridge Gateway

📋 The Core Compliance Requirement Flagged by ABDM