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

# 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 specification covers the endpoints a Health Information User must implement and call to participate in India's NDHM network - typically an insurer, doctor, telehealth platform, or research entity that needs consented access to patient records. The 32 endpoints cover identification, consent flow callbacks, health information requests and on-request callbacks, encrypted record receipt via `/v0.5/health-information/transfer`, and Gateway-facing helpers such as certs and OpenID configuration.

## For AI agents

Implement and call the Health Information User side of NDHM - raise consent requests, receive consent state callbacks, request and receive encrypted health records.

## Scope

Does not issue consent artefacts, store records, or manage ABHA identifiers - use for the NDHM HIU record-requesting role only.

## Capabilities

- Raise consent requests for patient records via `/v0.5/consent-requests/init`
- Handle consent state callbacks at `/v0.5/consents/hiu/on-notify`
- Fetch granted consent artefacts using `/v0.5/consents/fetch` and on-fetch
- Request health information from a HIP through `/v0.5/health-information/cm/request`
- Receive encrypted health record transfers at `/v0.5/health-information/transfer`
- Notify the Gateway of data-flow events through `/v0.5/health-information/notify`

## Use cases

### Insurer Claims HIU Workflow

An insurer acting as an HIU raises a scoped consent request for the encounters covered by a claim, fetches the artefact when granted, and requests the encrypted FHIR bundle from the relevant HIP. The HIU receives the records via `/v0.5/health-information/transfer`, decrypts them locally, and reconciles them against the claim. The flow is async and bounded by the consent's validity window.

Example prompt: POST `/v0.5/consent-requests/init` with the encounter scope, then on grant call `/v0.5/consents/fetch` and `/v0.5/health-information/cm/request` to retrieve the encrypted bundle.

### Telemedicine Pre-Consultation Record Pull

A telemedicine platform acting as an HIU pulls the patient's recent labs and prescriptions before a consultation. The HIU raises a short-validity consent request, the patient approves it on their CM, and the telemedicine app receives the encrypted FHIR bundle on `/v0.5/health-information/transfer` in time for the doctor to review. Integration follows the NDHM 0.5 callback choreography.

Example prompt: POST `/v0.5/consent-requests/init` with a 1-hour validity window covering the requested HI types, then receive the encrypted bundle on `/v0.5/health-information/transfer.`

### Research Cohort Data Access

A research entity registered as an HIU raises consent requests against a cohort of opted-in citizens, fetches the granted artefacts, and pulls de-identified records from each citizen's HIP. The HIU enforces the artefact's purpose and validity locally, since NDHM does not police these constraints downstream. This pattern is common for public-health and clinical-trial use cases.

Example prompt: Iterate over a cohort of ABHA ids and POST `/v0.5/consent-requests/init` for each, scoped to the research purpose and the agreed HI types.

### Agent-Driven HIU Operations

An AI agent embedded in an HIU back-office uses Jentic to orchestrate the consent-and-fetch loop without rebuilding signing, async callback, and decryption scaffolding for every project. The agent searches for the right operation, loads the schema, and submits the consent request and health information request while Jentic manages the participant credentials.

Example prompt: Search Jentic for 'request health information as HIU', load the schema for `/v0.5/health-information/cm/request`, and execute it with the consent id and HIP id.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v0.5/consent-requests/init` | Raise a consent request |
| POST | `/v0.5/consent-requests/status` | Check consent request status |
| POST | `/v0.5/consents/fetch` | Fetch a granted consent artefact |
| POST | `/v0.5/consents/hiu/on-notify` | Receive consent notification on HIU side |
| POST | `/v0.5/health-information/cm/request` | Request health information from CM |
| POST | `/v0.5/health-information/hiu/on-request` | HIU on-request callback for data flow |
| POST | `/v0.5/health-information/transfer` | Receive encrypted health information transfer |

## Key resources

- **Consent Requests** — Raise and check status of HIU consent requests
- **Consents** — Fetch granted artefacts and receive notifications
- **Health Information** — Request records and receive encrypted transfers
- **Subscriptions** — Subscribe to notifications and acknowledge events
- **Gateway Helpers** — Certs and OpenID configuration retrieval
- **Heartbeat** — Liveness reporting for HIU services

## Why Jentic

- **Setup:** Wiring the NDHM HIU record-requesting role by hand means signing consent and health-information messages with your HIU keys, setting the X-HIU-ID header, and tracking the asynchronous request and on-request callbacks against the gateway host yourself. Through Jentic you install once, import the HIU role from the API Directory, store the signing credentials once, and your agent calls it.
- **Permission scoping:** The HIU operations pass the consent request and health-information targets 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 health-information transfer. Because you choose that set, callbacks you omit remain unavailable.
- **Credential handling:** Your HIU signing keys, id header, and gateway client secret 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 'request health information as an HIU' or 'check consent request status', 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** — Routes the consent and data requests an HIU initiates
- **NDHM HIP Specifications** — Record-holding counterpart that fulfils HIU data requests
- **Health Data Consent Manager** — Issues the consent artefacts the HIU presents to HIPs

## FAQ

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

The National Health Authority publishes HIU responsibilities as written specifications and reference Postman collections rather than an OpenAPI document. 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 NDHM 0.5 specification and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the NDHM HIU API use?

The OpenAPI spec does not declare a top-level security scheme because HIU endpoints validate Gateway-issued JWTs against the certificates published at `/v0.5/certs` and require the X-HIU-ID header. Through Jentic the HIU signing keys and id are stored encrypted in the vault and applied at execution time, so the agent context never sees the long-lived secret.

### Can I receive encrypted health records with the HIU API?

Yes. After raising a consent request and receiving the granted artefact, POST `/v0.5/health-information/cm/request` to ask for the records. The HIP transfers the encrypted FHIR bundle to your `/v0.5/health-information/transfer` endpoint, where the HIU decrypts and processes it.

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

The NDHM 0.5 specification does not publish per-endpoint rate limits in the OpenAPI document; throughput is governed by the participant onboarding agreement with the National Health Authority. Treat the dev.ndhm.gov.in/gateway sandbox as low-throughput and back off on 429 or 503 responses.

### How do I raise a consent request through Jentic?

Run pip install jentic, then search for 'raise patient consent request', load the schema for POST `/v0.5/consent-requests/init`, and execute it with the requesting HIU id, patient ABHA id, requested HI types, and validity window. Jentic returns the acknowledgement and the on-init callback payload.

### Does the HIU API store the records it receives?

No. The HIU API only handles the consent and transfer choreography. Storage, decryption, and downstream processing of the FHIR bundle happen inside the HIU's own systems.

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

Yes. Because you run Jentic One yourself, your own rules decide which HIU operations the agent may call and which signing credentials it may use. You can allow just the endpoints a task needs, such as POST `/v0.5/consent-requests/init` and POST `/v0.5/health-information/transfer`, and leave every other callback out of the agent's reach. Any operation you do not grant stays unavailable to the agent, and your HIU keys and X-HIU-ID stay outside its context.