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

# Ndhm Health Data Consent Manager

Jentic publishes the only available OpenAPI specification for Health Data Consent Manager, keeping it validated and agent-ready. The Health Data Consent Manager API implements India's National Digital Health Mission (NDHM) Consent Manager role, allowing patients to authorise the aggregation and sharing of medical records across hospitals, diagnostic labs, insurers, and researchers. It exposes endpoints for raising consent requests, fetching signed consent artefacts, notifying Health Information Providers and Users about consent state changes, and orchestrating the resulting data flow. The 22 endpoints cover discovery, linking, consent lifecycle, and health information transfer flows defined in the NDHM 0.5 specification.

## For AI agents

Raise patient consent requests, fetch signed consent artefacts, and coordinate health record exchange between Indian Health Information Providers and Users under NDHM rules.

## Scope

Does not store clinical records, issue ABHA identifiers, or process payments - use for orchestrating NDHM patient consent only.

## Capabilities

- Initiate patient consent requests for sharing medical records between Health Information Providers and Users
- Fetch signed consent artefacts via `/v0.5/consents/fetch` for downstream verification
- Notify HIPs and HIUs of consent grant, revoke, or expiry events through the on-notify callbacks
- Discover patient care contexts across hospitals using `/v0.5/care-contexts/on-discover`
- Link patient care contexts across providers via `/v0.5/links/link/add-contexts`
- Coordinate health information requests and acknowledgements between HIU and HIP roles

## Use cases

### Patient-Initiated Health Record Sharing

Allow a patient to authorise an insurer or doctor to access their lab reports and discharge summaries held at multiple hospitals. The Consent Manager raises the consent request, collects the patient approval, and issues a signed consent artefact that the Health Information User presents to providers when fetching records. Integration follows the NDHM 0.5 flow with discovery, link, consent, and data transfer phases.

Example prompt: POST `/v0.5/consent-requests/init` with the HIU id, patient ABHA id, requested HI types, and validity window, then poll `/v0.5/consent-requests/status` until the artefact is granted.

### Insurer Claims Verification

Health insurers verify treatment claims by requesting consented access to specific encounters at hospitals. The Consent Manager scopes the consent to the relevant care contexts and date range, and notifies the HIP via `/v0.5/consents/hip/on-notify` when access is granted. The insurer's HIU then issues `/v0.5/health-information/request` to retrieve the encrypted records covered by the artefact.

Example prompt: Create a consent request scoped to encounters between two dates for a given hospital, fetch the artefact, then call `/v0.5/health-information/request` with the consent id.

### Care Context Linking After Hospital Admission

After a patient is admitted, the hospital can initiate care-context linking so that the encounter becomes discoverable under the patient's ABHA id. The Consent Manager processes `/v0.5/links/link/add-contexts`, validates the patient identifier, and confirms linkage via `/v0.5/links/link/on-confirm.` Once linked, the encounter is available for future consent-based retrieval.

Example prompt: POST `/v0.5/links/link/add-contexts` with the patient ABHA id and the new care-context references for an admission encounter.

### Agent-Driven Health Record Aggregation

An AI agent acting on behalf of a patient can use Jentic to discover NDHM consent operations, raise consent for specified Health Information types, and orchestrate the artefact fetch and downstream data request without hard-coding NDHM endpoint paths. The agent retrieves operation schemas at runtime, so it can adapt as the NDHM spec evolves.

Example prompt: Search Jentic for 'raise patient consent request', load the schema for `/v0.5/consent-requests/init`, and execute the call with patient and HIU parameters.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v0.5/consent-requests/init` | Create a consent request |
| POST | `/v0.5/consent-requests/status` | Get consent request status |
| POST | `/v0.5/consents/fetch` | Get a signed consent artefact |
| POST | `/v0.5/consents/hip/on-notify` | Notify HIP of consent state change |
| POST | `/v0.5/consents/hiu/on-notify` | Notify HIU of consent state change |
| POST | `/v0.5/care-contexts/on-discover` | Respond to patient care-context discovery |
| POST | `/v0.5/links/link/add-contexts` | Link new care contexts for a patient |
| POST | `/v0.5/health-information/request` | HIU request for health information |

## Key resources

- **Consent Requests** — Initiate, query, and act on consent request lifecycle
- **Consent Artefacts** — Fetch and notify on signed consent artefacts
- **Care Contexts** — Discover and link patient encounters across providers
- **Health Information** — Request and acknowledge encrypted health record transfer
- **Patients** — Identify patients by consent-manager user id and share profiles

## Why Jentic

- **Setup:** Wiring the NDHM Consent Manager by hand means signing each participant message with your JWT keys, setting the X-HIU-ID and X-HIP-ID headers correctly, and tracking the asynchronous init, status, and notify callbacks yourself. Through Jentic you install once, import the Consent Manager from the API Directory, store the signing credentials once, and your agent calls it.
- **Permission scoping:** The Consent Manager carries the consent request, patient, and care-context 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 consents fetch. You choose that operation set, so notify or health-information callbacks are excluded unless you add them.
- **Credential handling:** Your NDHM participant signing keys and id headers 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 'raise a patient consent request' or 'check consent status', and Jentic returns the matching Consent Manager operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **NDHM Gateway** — Routes calls between the Consent Manager, HIPs, and HIUs in the NDHM network
- **NDHM HIU Specifications** — HIU-side callbacks that consume consent artefacts produced by the Consent Manager
- **NDHM HIP Specifications** — HIP-side endpoints that serve health records once consent is granted

## FAQ

### Why is there no official OpenAPI spec for Health Data Consent Manager?

The National Health Authority publishes the NDHM specifications as documentation rather than a machine-readable OpenAPI file. Jentic generates and maintains this spec so that AI agents and developers can call Health Data Consent Manager via structured tooling. It is validated against the published NDHM 0.5 specification and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Health Data Consent Manager use?

The OpenAPI spec does not declare a security scheme because NDHM authentication is handled out-of-band via the Gateway-issued JWT and X-HIU-ID/X-HIP-ID headers configured per participant. Through Jentic the participant credentials are stored encrypted in your Jentic One instance and injected at execution time, so the agent context never sees the raw JWT signing keys.

### Can I raise a patient consent request with the Health Data Consent Manager API?

Yes. POST to `/v0.5/consent-requests/init` with the requesting HIU id, the patient's consent-manager user id, the requested Health Information types and date range. The request is acknowledged synchronously and the resulting artefact is delivered asynchronously via `/v0.5/consent-requests/on-init.`

### What are the rate limits for the Health Data Consent Manager?

The NDHM 0.5 specification does not publish per-endpoint rate limits in the spec; limits are negotiated per participant agreement with the National Health Authority. Treat the sandbox at dev.ndhm.gov.in/cm as low-throughput and back off on 429 or 503 responses.

### How do I fetch a consent artefact through Jentic?

Run pip install jentic, then search for 'fetch consent artefact', load the schema for POST `/v0.5/consents/fetch`, and execute with the consent id from the on-init callback. Jentic returns the signed artefact JSON ready to be presented to a HIP.

### Does the Health Data Consent Manager handle clinical record storage?

No. The Consent Manager only orchestrates consent and routing. The actual encrypted health records are exchanged via the HIP `/v0.5/health-information/request` and `/v0.5/health-information/transfer` endpoints between the HIP and HIU.

### Can I limit what my agent is allowed to do with the Health Data Consent Manager API?

Yes. Because you run Jentic One yourself, you choose exactly which Consent Manager operations your agent may call, so you can allow only the ones it needs, such as POST `/v0.5/consent-requests/init` to raise a consent request or POST `/v0.5/consents/fetch` to retrieve a signed artefact. The consent request, patient, and care-context targets travel inside the signed request body rather than the URL, so scoping happens at the operation level you control. Callbacks like `/v0.5/consents/hip/on-notify` or `/v0.5/health-information/request` stay excluded unless you deliberately add them to the agent's allowed set.