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`.

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/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/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 OTP. Response includes `patient_id` + `gateway_patient` (full saved profile from gateway DB — use to pre-fill HMS patient record).	Bearer
GET	`/api/v3/abha/card`	Download ABHA card PNG (base64) — pass ?token=<x_token>	Bearer
OPD QUEUE
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
CONSENT & FHIR BUNDLE
POST	`/api/v3/consent/request`	Request ABDM data consent from patient	Bearer
POST	`/api/v3/bundle/push`	Push FHIR R4 health document bundle to ABDM	Bearer
UNIFIED BRIDGE (event dispatcher)
POST	`/api/v1/bridge`	Recommended for HMS — single event-based endpoint, routes to correct ABDM service automatically	Bearer
ABDM → BRIDGE CALLBACKS (ABDM calls these; HMS does not need to call them)
POST	`/api/hiecm/user-initiated-linking/v3/patient/care-context/discover`	ABDM asks bridge for patient's available care contexts	ABDM
POST	`/api/hiecm/user-initiated-linking/v3/link/care-context/init`	ABDM initiates care context linking (bridge creates link session)	ABDM
POST	`/api/hiecm/user-initiated-linking/v3/link/care-context/confirm`	ABDM confirms link — bridge marks records as linked, fires HMS webhook	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}

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"
}

Health Records API HMS pushes FHIR bundles → gateway stores → ABDM links on demand

Architecture: HMS builds a FHIR R4 Bundle and pushes it via POST /api/v3/records/push. The gateway validates the bundle, stores it, and returns record_id + queue_id — store both in HMS DB. The gateway serves health data to ABDM directly — it never calls back to HMS (NAT-safe architecture). See FHIR Bundle Guide below for complete bundle examples per HI type.

✓ 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`
`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`
`date_of_birth`	date	optional	`YYYY-MM-DD`
`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 or abha_address is required.

REQUEST

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 */ }
}

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.

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):
{ "resourceType":"DocumentReference", "status":"current",
  "subject":{ "reference":"Patient/pat-1" },
  "content":[{ "attachment":{
    "contentType":"application/pdf",
    "data":"<base64-encoded-pdf>",
    "title":"Old prescription scan"
  }}]
}

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 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 API

Endpoint	Description	Key Fields
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`

// 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" } ] }

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 ABDM calls these — no action required from HMS

For HMS Developers: These endpoints are called by ABDM when patients interact with their PHR / ABHA app. You do not call them from HMS. When ABDM calls link/confirm or consent/notify, the bridge automatically fires an outgoing HMAC webhook to your HMS server — see Bridge → HMS Webhooks below.

User-Initiated Linking — Patient links records via PHR app (3-step flow)

POST /api/hiecm/user-initiated-linking/v3/patient/care-context/discover

ABDM asks: "What records does this patient have at this HIP?" Bridge queries abdm_health_records by ABHA ID and calls ABDM /on-discover with matching care contexts.

POST /api/hiecm/user-initiated-linking/v3/link/care-context/init

ABDM sends selected care contexts. Bridge creates a link session in abdm_link_sessions with a linkRefNumber and calls ABDM /on-init.

POST /api/hiecm/user-initiated-linking/v3/link/care-context/confirm

Patient confirms in PHR app. Bridge marks records as linked, calls ABDM /on-confirm, and fires HMS record_linked_callback webhook for each record.

// 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 records from abdm_health_records, 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

Bridge → HMS Webhooks Bridge calls these on your HMS server

Setup: Configure HMS_WEBHOOK_BASE_URL and HMS_WEBHOOK_SECRET in the gateway .env file. The bridge will POST signed JSON to your HMS server 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

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