abdm-overview

name	abdm-overview
description	Understand ABDM (Ayushman Bharat Digital Mission), its registries (ABHA, HPR, HFR), roles (HIP/HIU/PHR), the four certification milestones M1-M4, and how Eka's ABDM Connect APIs map to them. Use when the user asks "what is ABDM", "what is ABHA/HPR/HFR", "which milestone do I need", "HIP vs HIU", "how does ABDM certification work", or at the start of any ABDM integration to decide scope.

ABDM Overview

What ABDM is

Ayushman Bharat Digital Mission is India's national digital health infrastructure (run by the National Health Authority, NHA). Patients, hospitals, labs, insurers, and health apps exchange health records through a central gateway, with patient consent driving every transaction. Eka's ABDM Connect is an API/SDK layer that absorbs the ABDM gateway complexity (callbacks, encryption, retries, certification requirements) behind simple REST APIs.

The four registries

• ABHA — the patient identity. Either a 14-digit ABHA Number (Aadhaar-KYC-verified) or an ABHA Address like nisha@abdm. All transactions anchor to this.
• HPR — Healthcare Professionals Registry. Every doctor/nurse gets an HPR ID.
• HFR — Health Facility Registry. Every facility gets an HFR ID.
• Consent Manager — mediates consent between HIPs and HIUs (the ABDM Gateway itself).

The two roles (a product can be both)

• HIP (Health Information Provider): holds records — hospital HMS, lab LIMS, pharmacy. Links records to a patient's ABHA after each visit/test and serves them when requested.
• HIU (Health Information User): requests records with consent — insurers, referral systems, analytics platforms.
• PHR app: a separate patient-facing track. Typically both HIP (self-uploaded records) and HIU (fetches from providers). Adds Scan & Share, health locker, subscription notifications.

Milestones — who needs what

Milestone	Required by	Covers
M1 — ABHA identity	Everyone	Create/login ABHA (Aadhaar OTP, mobile OTP, face auth), profile, KYC, ABHA card/QR, verify at check-in
M2 — Care context linking & data sharing	HIPs	Link visit/test records to ABHA, discovery, serve FHIR data to HIUs (or let Eka store & serve)
M3 — Consent management & data fetching	HIUs (+ PHR)	Create consent requests, approve/deny/revoke, auto-approval, receive encrypted FHIR
M4 — HPR & HFR registration	All HMIS/LMIS	Create HPR IDs, register/link facilities, software linkage to Eka Bridge

Scoping heuristic: HMS/LIMS → M1+M2+M4 (HIP). Insurer/analytics → M1+M3 (HIU). Patient app → M1+M3+PHR extras. Full platform → all four.

Key architectural facts (Eka-specific)

• Three integration methods exist per facility: Web SDK (embedded, themed), hosted web/widget (redirect/QR to eka.care-hosted flows, zero code), raw API. The Eka console stores one integration_method value per facility, not per milestone — a client can genuinely be on SDK for M1 and raw API for M2, but the console won't remember that distinction for you. Re-ask the integration-method question at the start of every milestone; never assume continuity from a previous milestone.
• A single client account (workspace_id) can have more than one facility/HIP registered (each with its own hip_id, credential, integration method, and branding config), and each HIP can have multiple linked NDHM clinics under it. Don't assume one facility — ask which hip_id (and clinic, if applicable) an integration run applies to whenever the client's account could plausibly have more than one.
• Branding/theme for SDK integrations (M1 today; check per-milestone whether other SDKs expose the same) is carried in a client config the client uploads or pastes at integration time — see abdm-auth skill's references/client-config.md. This mirrors the console's per-facility theme_config, so treat it as per-facility too, not reusable verbatim across multiple HIPs on the same account.
• Eka-managed clients transact on the Eka Bridge (OHPL_001); console-issued credentials look like EC_... / eka_....
• Base URLs: prod https://api.eka.care, sandbox https://api.dev.eka.care.
• Auth: client_id + client_secret → /connect-auth/v1/account/login → access token (use in auth/Authorization header) + refresh token. 401 → refresh. Long-lived tokens available for server-to-server.
• Many flows are asynchronous via webhooks (linking status, data fetch requests, consent updates, data push). The integrator must expose a webhook endpoint. There is no self-service API to register ABDM webhooks (Eka's public webhook-registration API is scoped to appointment/prescription/receipt events only) — collect the client's webhook URL proactively and relay it to Eka console/support yourself; don't leave it as a vague "register it later."
• Data custody choice (biggest design decision for HIPs and HIUs): letting Eka store/serve data on your behalf is not a routinely available option today for most accounts — plan integrations around the client keeping/managing their own data (webhook + build-on-demand + encryption) by default, and only offer the Eka-managed path if the client already knows it's enabled on their account.
• Compliance: never store raw Aadhaar, full patient mobile, OTPs, or plaintext secrets. ABHA numbers/addresses, HPR/HFR IDs, and transaction IDs are safe to store.

Known limitations — don't imply the integration can do more than it can

• Facility/HFR approval is asynchronous and human-reviewed by NHA — no API shortcut exists; set this expectation explicitly with the user (see abdm-m4-nhpr).
• integration_method and branding/theme config are per-facility, not per-org or per-milestone — a client with multiple facilities needs separate setup for each, and switching method mid-integration is real and expected, not an edge case.
• No self-service API exists for ABDM webhook registration (console/support only, see above).
• SDKs don't always return everything you need: e.g. the NHPR Web SDK's unmount callback doesn't return the created clinic id — it must be looked up server-side by hip_id (see abdm-m4-nhpr). Tell users about SDK gaps like this directly instead of quietly working around them.
• The console can be ahead of the public docs site. developer.eka.care is the primary source for live schemas, but per-milestone module pages in console.eka.care sometimes expose SDKs or config the public docs haven't caught up on yet (e.g. a per-language backend SDK snippet for a milestone with no matching public doc page). If a live-fetch of the public docs comes up empty for something the user says exists, don't conclude it doesn't exist — ask them to check their console module page or paste its snippet before ruling it out.

Deep dives

• Full live docs map (fetch pages as .md): references/docs-map.md
• Per-milestone skills: abdm-m1-abha, abdm-m2-care-context, abdm-m3-consent, abdm-m4-nhpr
• Cross-cutting: abdm-auth, abdm-fhir, abdm-testing, abdm-debugging