canonical: https://jentic.com/apis/ndhm.gov.in/ndhm-hiu-specifications

# Ndhm Health Repository Provider Specifications for HIU

Jentic publishes the only available OpenAPI specification for Health Repository Provider Specifications for HIU, keeping it validated and agent-ready. This spec bundles the 32 endpoints that an entity acting as a Health Information User (HIU) must implement and consume to participate in India's NDHM network. It draws operations from the Gateway and Bridge specs and groups them under identification, consent flow, data flow, subscriptions, and monitoring - making it clear which calls an HIU originates against the Gateway and which callbacks the Gateway invokes against the HIU.

## For AI agents

Implement the HIU role in the NDHM network - initiating consent requests, receiving encrypted health-information bundles, and responding to Gateway callbacks.

## Scope

Does not host patient records, run the patient-facing consent UI, or issue ABHA Health IDs - use for the consumer-side consent, identification, and data-flow role only.

## Capabilities

- Initiate consent requests for patient health information by ABHA identifier
- Receive consent grant, denial, expiry, and revocation notifications from the Gateway
- Request encrypted health-information bundles from the Consent Manager and HIPs
- Acknowledge data-transfer events and report delivery success or failure
- Subscribe to ongoing health-information feeds for longitudinal use cases
- Expose JWT verification certificates and a heartbeat endpoint for monitoring

## Use cases

### Insurance Claim Document Pulls

An insurance HIU integrates with NDHM to pull discharge summaries and lab reports from hospitals when a claim is filed. The HIU initiates a consent request via /v0.5/consent-requests/init on the Gateway, the patient grants approval through their CM, and the HIU then requests the data bundle. Replaces fax and email document collection with a signed consent flow.

Example prompt: Call POST /v0.5/consent-requests/init via the Gateway; on /consents/hiu/notify, call POST /v0.5/health-information/cm/request

### Telemedicine HIU for Cross-Hospital History

A telemedicine app needs longitudinal patient history before a consultation. As an HIU, it initiates a consent request scoped to the past two years, receives consent artefacts, and pulls bundles from each HIP that holds matching records. The HIU spec defines the callbacks the Gateway invokes during this flow.

Example prompt: Initiate a consent request with HI types DiagnosticReport and DischargeSummary; on data-flow notify, decrypt and store the bundle

### Research-Use HIU for De-Identified Data

A clinical research platform acts as an HIU to gather de-identified patient histories for cohort studies. The platform asks patients to consent to research-purpose access, then pulls bundles strictly within the consented scope and time window. Audit notifications back to the Gateway create the trail required for ethics review.

Example prompt: Issue a consent request with purpose=PUBHLTH for the cohort and listen for /consents/hiu/on-notify to enumerate granted artefacts

### Agent-Driven HIU Operations

An AI agent inside an HIU app handles the consent-request lifecycle on behalf of an end user - issuing the request, polling status, and receiving bundles. Jentic resolves the natural-language request to the right /consent-requests, /consents, and /health-information endpoints and signs payloads from the encrypted vault.

Example prompt: Search Jentic for 'NDHM HIU initiate consent request', execute POST /v0.5/consent-requests/init with HIU id and purpose

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v0.5/consent-requests/init | Initiate a consent request as an HIU |
| POST | /v0.5/consent-requests/on-init | Receive consent-request acknowledgement |
| POST | /v0.5/consents/fetch | Fetch a consent artefact |
| POST | /v0.5/consents/hiu/notify | Receive consent decision notification |
| POST | /v0.5/health-information/cm/request | Request a health-information bundle |
| POST | /v0.5/health-information/hiu/on-request | Receive data-request acknowledgement |

## Key resources

- **Identification** — Resolve patient identifiers via the Gateway
- **Consent Flow** — Initiate consent requests and receive grant or denial notifications
- **Data Flow** — Request and receive encrypted health-information bundles
- **Subscriptions** — Subscribe to ongoing health-information feeds
- **Monitoring** — Heartbeat and certificate endpoints
- **Gateway** — Callbacks invoked by the Gateway against the HIU

## Why Jentic

- **Setup:** Wiring the NDHM HIU consumer specification by hand means building the consent-request and health-information callback flow, signing every message with your participant keys, and routing initiator and callback calls to the correct gateway host yourself. Through Jentic you install once, import the HIU specification from the API Directory, store the signing credentials once, and your agent calls it.
- **Permission scoping:** The HIU operations pass the consent request, HIU id, and purpose inside the signed request body rather than in the URL path, so you limit the agent to the operations it needs, such as consent-requests init or consents fetch. The agent can only run the operations you selected, so callbacks you leave out stay unavailable.
- **Credential handling:** Your HIU signing keys and client credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'initiate an NDHM consent request' or 'request health information as an HIU', and Jentic returns the matching HIU operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **NDHM Gateway** — The Gateway routes the HIU's consent and data requests to the CM and HIPs.
- **NDHM HIP Specifications** — Defines the provider-side counterpart that supplies records to the HIU.
- **NDHM Health Data Consent Manager** — The CM mediates consent grants and forwards data requests on behalf of the HIU.

## FAQ

### Why is there no official OpenAPI spec for Health Repository Provider Specifications for HIU?

NDHM does not publish a maintained OpenAPI specification for the HIU role - only Markdown reference docs and a deprecated apis.guru import. Jentic generates and maintains this spec so that AI agents and developers can call Health Repository Provider Specifications for HIU 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 HIU specification require?

HIU endpoints are secured with signed JWTs issued through the NDHM Gateway and validated against certificates fetched from /v0.5/certs. The OpenAPI spec leaves `securitySchemes` empty because authorisation is enforced at the JWT layer rather than via a standard HTTP scheme.

### Can I initiate a consent request as an HIU through this spec?

Yes. POST /v0.5/consent-requests/init starts the flow on the Gateway with the HIU id, purpose, HIP scope, and time range. The CM then prompts the patient and your /v0.5/consents/hiu/notify endpoint receives the consent artefact reference.

### What are the rate limits for the HIU endpoints?

Rate limits are not declared in the OpenAPI spec. The sandbox at dev.ndhm.gov.in applies fair-use throttling for development; production rate limits depend on the HIU's onboarding tier with the National Health Authority and the volume of consents in flight.

### How do I request a health-information bundle through Jentic?

Search Jentic for 'request NDHM health-information bundle as HIU', load the schema for POST /v0.5/health-information/cm/request, and execute with the granted consent artefact reference. The CM forwards the request to the HIP, which transfers the encrypted bundle to your /on-request endpoint.

### Can I limit what my agent is allowed to do with the NDHM HIU Specifications API?

Yes. Because Jentic One is self-hosted, you decide which HIU operations the agent may call, so you can allow it to run consent-requests init or consents fetch while withholding everything else. The agent can only execute the operations you selected, which means callbacks and endpoints you leave out stay unavailable to it. The consent request, HIU id, and purpose travel inside the signed request body rather than the URL path, so your scoping rules govern exactly which calls the agent makes with your signing credentials.