canonical: https://jentic.com/apis/ndhm.gov.in/ndhm-health-id-service

# Ndhm Health ID Service

Jentic publishes the only available OpenAPI specification for Health ID Service, keeping it validated and agent-ready. The NDHM Health ID Service issues and manages the ABHA Health ID - a unique identifier used across India's National Digital Health Mission to issue, access, and share health records with patient consent. The 73-endpoint surface covers Aadhaar and mobile-OTP based registration, KYC, profile management, password and credential recovery, health-facility linkage, integrated programs, search, and Health ID card generation in PDF, PNG, and SVG formats.

## For AI agents

Issue and manage ABHA Health IDs with Aadhaar or mobile-based registration, KYC, profile updates, password recovery, and Health ID card generation.

## Scope

Does not orchestrate consent flows, store HIP records, or run provider-side clinical workflows - use for ABHA Health ID issuance, profile, KYC, and card generation only.

## Capabilities

- Register a new ABHA Health ID using Aadhaar OTP or mobile OTP verification
- Generate and verify Aadhaar OTPs for KYC and re-KYC of an existing Health ID
- Reset a Health ID password using Aadhaar, mobile, or existing-password flows
- Generate the Health ID card as PDF, PNG, or SVG for download
- Manage profile data including name, gender, year of birth, and contact details
- Search Health IDs and link them to a Health Facility ID for provider-side workflows

## Use cases

### ABHA Health ID Registration in a Provider App

Hospitals and telemedicine apps register patients into the NDHM ecosystem by issuing them an ABHA Health ID. The Aadhaar registration flow (POST `/v1/account/aadhaar/generateOTP` and /verifyOTP) completes KYC in the same call, while the mobile flow caters to patients without an Aadhaar link. Issuance now takes seconds rather than the minutes-long flow on the NDHM portal.

Example prompt: Call POST `/v1/account/aadhaar/generateOTP` with the Aadhaar number, then POST `/v1/account/aadhaar/verifyOTP` to complete registration

### Patient Self-Service Password Reset

Patients who have forgotten their Health ID password reset it via Aadhaar OTP, mobile OTP, or existing-password flows. The `/v1/account/change/passwd` endpoints orchestrate OTP generation and verification while preserving the audit trail required by NDHM. Replaces a manual support-ticket process.

Example prompt: Call GET `/v1/account/change/passwd/generateMobileOTP` with the registered mobile, then POST `/v1/account/change/passwd/byMobile` with the OTP and new password

### Health ID Card Issuance

Issue a printable or digital Health ID card to the patient after onboarding. GET `/v1/account/getCard` returns a PDF, /getPngCard returns a PNG suitable for in-app display, and /getSvgCard returns a vector format used by some hospital print services. Cards include the ABHA number and QR code for offline lookup.

Example prompt: Call GET `/v1/account/getCard` with a valid Health ID token and stream the resulting PDF to the patient's email

### Agent-Driven ABHA Onboarding

An AI agent inside a hospital reception app onboards a new patient end-to-end - capturing their Aadhaar, generating the OTP, verifying it, and downloading the Health ID card - all through Jentic. The Aadhaar OTP and reset-password tokens stay in the encrypted vault rather than the agent's context.

Example prompt: Search Jentic for 'register ABHA Health ID via Aadhaar', execute the OTP and verifyOTP endpoints, then GET `/v1/account/getCard`

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/account/aadhaar/generateOTP` | Generate Aadhaar OTP for registration or KYC |
| POST | `/v1/account/aadhaar/verifyOTP` | Verify Aadhaar OTP |
| POST | `/v1/account/change/passwd/byMobile` | Change password via mobile OTP |
| GET | `/v1/account/getCard` | Generate Health ID card as PDF |
| GET | `/v1/account/getPngCard` | Generate Health ID card as PNG |
| DELETE | `/v1/account/profile` | Delete a Health ID account |

## Key resources

- **Authentication** — Login and session-issuance flows for the Health ID
- **Registration with Aadhaar** — Aadhaar-OTP based registration and KYC
- **Registration with mobile number** — Mobile-OTP based registration and KYC
- **Profile** — Manage Health ID profile data and card downloads
- **Health Facility** — Link Health IDs to provider Health Facility records
- **Search** — Look up Health IDs by mobile, Aadhaar, or other identifiers
- **Forgot health id/number** — Recover a forgotten Health ID or password

## Why Jentic

- **Setup:** Wiring the NDHM Health ID Service by hand means managing Health ID bearer tokens and Aadhaar OTP transaction ids on the healthidsbx.ndhm.gov.in host and sequencing the OTP steps yourself. Through Jentic you install once, import the Health ID Service from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** The Health ID Service carries the Aadhaar number, OTP, and transaction id in the request body rather than in the URL path, so scope the agent to the operations it needs, such as generating and verifying an Aadhaar OTP. You choose the operations it may call, so profile deletion or password changes are not included unless you add them.
- **Credential handling:** Your Health ID bearer tokens, Aadhaar OTP transaction ids, and client credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. This identity material never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'register an ABHA Health ID via Aadhaar', and Jentic returns the matching operation with its input schema so the agent walks through generateOTP and verifyOTP without browsing the reference docs.

## Related APIs

- **NDHM Gateway** — The Gateway uses ABHA Health IDs issued by this service to identify patients across HIPs and HIUs.
- **NDHM Health Data Consent Manager** — The CM stores consent records keyed on the patient's ABHA Health ID.
- **NDHM HIP Specifications** — HIPs link patient records to the Health ID issued by this service via `/links/link/add-contexts.`

## FAQ

### Why is there no official OpenAPI spec for Health ID Service?

NDHM does not publish a maintained OpenAPI specification for the Health ID Service - only HTML reference docs and a deprecated apis.guru import. Jentic generates and maintains this spec so that AI agents and developers can call Health ID Service via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Health ID Service use?

Most endpoints require a bearer JWT issued through the NDHM Health ID auth flow (POST `/v1/account/aadhaar/verifyOTP` returns a token). The OpenAPI spec leaves `securitySchemes` empty because the auth pattern is documented at the operation level rather than as a global scheme. Through Jentic, tokens are stored encrypted and supplied per request.

### Can I register a new ABHA Health ID through this API?

Yes. The Aadhaar flow (POST `/v1/account/aadhaar/generateOTP` then /verifyOTP) registers and KYCs the patient in one sequence. The mobile flow uses /generateMobileOTP and /verifyMobileOTP for patients who cannot link an Aadhaar.

### What are the rate limits for the Health ID Service?

Rate limits are not declared in the OpenAPI spec. The sandbox at healthidsbx.ndhm.gov.in applies per-IP throttling for development. Aadhaar OTP endpoints are additionally throttled by UIDAI and may return rate-limit errors during peak load.

### How do I download a Health ID card through Jentic?

Search Jentic for 'download ABHA Health ID card', load the schema for GET `/v1/account/getCard` (PDF), /getPngCard (PNG), or /getSvgCard (SVG), and execute with a valid Health ID bearer token. The response is a binary stream that Jentic returns to the agent for forwarding.

### Is the NDHM Health ID Service free?

Yes. The Health ID Service is operated by India's National Health Authority and is free for accredited integrators. Production access requires onboarding through the NHA developer portal.

### Can I limit what my agent is allowed to do with the NDHM Health ID Service API?

Yes. Because you run Jentic One yourself, your own rules decide which Health ID Service operations and credentials the agent can use. You can allow only the operations it needs, such as generating and verifying an Aadhaar OTP for registration and KYC, while excluding sensitive ones like profile deletion (DELETE `/v1/account/profile`) or password changes unless you explicitly add them. The Aadhaar number, OTP, and transaction id travel in the request body rather than the URL, so scoping stays at the operation level and the agent never touches endpoints you have not authorized.