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

# Ndhm Health Repository Provider Specifications for HIP

Jentic publishes the only available OpenAPI specification for Health Repository Provider Specifications for HIP, keeping it validated and agent-ready. This specification covers the endpoints a Health Information Provider must implement and call to participate in India's NDHM network as a record-holding party - typically a hospital, lab, or clinic. The 30 endpoints cover discovery callbacks, care-context linking, consent notification, encrypted health information transfer, and Gateway-facing helpers such as the certs and OpenID configuration. It is the producer side of the NDHM data flow.

## For AI agents

Implement and call the Health Information Provider side of NDHM - discover patients, link care contexts, receive consent notifications, and transfer encrypted health records.

## Scope

Does not issue consent artefacts, ABHA identifiers, or payments - use for the NDHM HIP record-serving role only.

## Capabilities

- Respond to patient discovery via `/v0.5/care-contexts/on-discover` with matching encounters
- Link patient care contexts using `/v0.5/links/link/init` and `/v0.5/links/link/confirm`
- Receive consent grant and revoke notifications at `/v0.5/consents/hip/on-notify`
- Acknowledge HIU health information requests via `/v0.5/health-information/hip/on-request`
- Transfer encrypted health records to the HIU through `/v0.5/health-information/transfer`
- Notify the Gateway of data-flow events through `/v0.5/health-information/notify`

## Use cases

### Hospital HIP Onboarding

A hospital implementing HIP responsibilities under NDHM exposes the discovery, link, consent, and data-transfer callbacks defined in this specification. When the Gateway broadcasts a discovery for a patient, the hospital responds with matching encounters, then handles the consent notification and serves the encrypted FHIR bundle on transfer. End-to-end onboarding takes 4-8 weeks of integration plus NHA certification.

Example prompt: POST `/v0.5/care-contexts/on-discover` with matching encounters for the patient identifiers received in the discovery callback.

### Care Context Linking After Discharge

After a patient is discharged, the hospital initiates HIP-side care-context linking so future consent flows can target the encounter. The HIP calls `/v0.5/links/link/add-contexts` on the Consent Manager and handles the on-confirm callback locally. Once linked, the encounter becomes discoverable and shareable under the patient's ABHA id.

Example prompt: POST `/v0.5/links/link/add-contexts` with the patient ABHA id, the new encounter references, and the HIP's identifier.

### Consent-Bound Record Transfer

When an HIU presents a granted consent artefact, the Gateway forwards a `/v0.5/health-information/hip/request` to the HIP. The HIP validates the consent artefact, packages the requested records as an encrypted FHIR bundle, acknowledges via `/v0.5/health-information/hip/on-request`, and transfers the bundle to the HIU via `/v0.5/health-information/transfer.` The whole flow is async and bound to the consent's validity window.

Example prompt: Validate the incoming consent artefact, then POST `/v0.5/health-information/transfer` with the encrypted FHIR bundle, key material reference, and the transaction id.

### Agent-Driven HIP Operations

An AI agent embedded in a hospital information system uses Jentic to handle NDHM HIP callbacks without rebuilding the request signing and routing scaffolding. The agent searches for the right operation, loads the schema, and submits responses to discovery, link, and transfer events while Jentic manages the participant credentials.

Example prompt: Search Jentic for 'transfer encrypted health information from HIP', load the schema for `/v0.5/health-information/transfer`, and execute it with the encrypted bundle.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v0.5/care-contexts/on-discover` | Respond to patient care-context discovery |
| POST | `/v0.5/links/link/init` | Initiate care-context linking |
| POST | `/v0.5/links/link/confirm` | Confirm care-context linking |
| POST | `/v0.5/links/link/add-contexts` | Add new care contexts for a patient |
| POST | `/v0.5/consents/hip/on-notify` | Receive consent notification on HIP side |
| POST | `/v0.5/health-information/hip/on-request` | Acknowledge HIU health information request |
| POST | `/v0.5/health-information/transfer` | Transfer encrypted health records |

## Key resources

- **Care Contexts** — HIP discovery and linking of patient encounters
- **Consents** — Receive consent grant, revoke, and expiry notifications
- **Health Information** — Acknowledge HIU requests and transfer encrypted records
- **Links** — Initiate, confirm, and add care contexts
- **Gateway Helpers** — Certs and OpenID configuration retrieval
- **Heartbeat** — Liveness reporting for HIP services

## Why Jentic

- **Setup:** Wiring the NDHM HIP record-serving role by hand means signing link and transfer messages with your HIP keys, setting the X-HIP-ID header, and matching each on-request and on-notify callback to the gateway host yourself. Through Jentic you install once, import the HIP role from the API Directory, store the signing credentials once, and your agent calls it.
- **Permission scoping:** The HIP operations carry the link, care-context, and transfer targets inside the signed request body rather than in the URL path, so you limit the agent to the operations it needs, such as links confirm or health-information transfer. The agent can call only the operations you selected, so on-notify handling stays out unless you add it.
- **Credential handling:** Your HIP 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 'transfer encrypted health information from an HIP' or 'confirm a care-context link', and Jentic returns the matching HIP operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **NDHM Gateway** — Routes discovery, consent, and data calls to and from the HIP
- **NDHM HIU Specifications** — Counterpart that consumes the records the HIP transfers
- **Health Data Consent Manager** — Issues the consent artefacts the HIP must validate before transferring records

## FAQ

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

The National Health Authority publishes HIP 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 HIP 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 HIP API use?

The OpenAPI spec does not declare a top-level security scheme because HIP endpoints validate Gateway-issued JWTs against the certificates published at `/v0.5/certs` and require the X-HIP-ID header. Through Jentic the HIP 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 transfer encrypted health records with the HIP API?

Yes. After validating an inbound consent artefact, POST `/v0.5/health-information/transfer` with the encrypted FHIR bundle, the key material reference, and the transaction id matching the HIU's original `/v0.5/health-information/hip/request.`

### What are the rate limits for the HIP 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 link a care context through Jentic?

Run pip install jentic, then search for 'link a care context for a patient', load the schema for POST `/v0.5/links/link/add-contexts`, and execute it with the patient ABHA id and the new encounter references. Jentic returns the on-confirm acknowledgement payload.

### Does the HIP API issue consent artefacts?

No. The HIP only consumes consent artefacts and serves records under their scope. Issuing artefacts is the responsibility of the Consent Manager, called via `/v0.5/consent-requests/init` on the Gateway.

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

Yes. Because you run Jentic One yourself, your own rules decide which of the HIP operations and which signing credentials the agent can use, and it can call only the ones you select. For example, you can allow the agent to confirm a care-context link through `/v0.5/links/link/confirm` and transfer an encrypted FHIR bundle through `/v0.5/health-information/transfer` while keeping consent-notification handling at `/v0.5/consents/hip/on-notify` out of scope until you add it. The link, care-context, and transfer targets travel inside the signed request body rather than the URL path, so scoping is enforced at the operation level rather than by parsing paths.