canonical: https://jentic.com/apis/ndhm.gov.in/ndhm-hip-specifications # 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 spec bundles the 30 endpoints that an entity acting as a Health Information Provider (HIP) must implement to participate in India's NDHM network. It draws operations from the Gateway and Health Repository specs and groups them so HIPs can implement only what is required of them - covering care-context discovery, account linking, consent-grant notifications, health-information data requests, encrypted transfers, and heartbeat monitoring. ## For AI agents Implement the HIP role in the NDHM network - handling care-context discovery, link confirmations, consent notifications, and encrypted health-information transfers. ## Scope Does not run the patient-facing consent UI, issue ABHA Health IDs, or consume records as an HIU - use for the provider-side discovery, linking, consent, and data-transfer role only. ## Capabilities - Receive and respond to care-context discovery requests for a patient by ABHA identifier - Confirm patient-initiated and HIP-initiated care-context linkages with token verification - Process consent notifications and acknowledge consent grants and revocations - Handle health-information data requests by encrypting and transferring the bundle to the HIU - Notify the Gateway of data-flow events including delivery success or failure - Expose JWT verification certificates and a heartbeat endpoint for monitoring ## Use cases ### Hospital HIP Onboarding to NDHM A hospital integrates its EHR system as a Health Information Provider on the NDHM network. The HIP spec defines the 30 endpoints the hospital must expose so the Gateway can discover patient records, request data on behalf of HIUs, and notify the hospital of consent events. Following this contract is the path to NDHM certification. Example prompt: Implement POST /v0.5/care-contexts/discover and reply via POST /v0.5/care-contexts/on-discover with the patient's care contexts ### Consent-Authorised Data Delivery When a patient grants consent and an HIU requests their data, the HIP receives a request, encrypts the bundle with the consent-supplied keys, transfers it to the HIU, and notifies the Gateway. POST /v0.5/health-information/hip/request, /transfer, and /notify together implement the encrypted exchange. Replaces ad-hoc fax or PDF sharing. Example prompt: On receiving POST /v0.5/health-information/hip/request, fetch the records, encrypt them with the keyMaterial, and POST /v0.5/health-information/transfer ### Care-Context Linking Confirmation A patient links their account in the CM to their record at the hospital. The hospital's HIP service confirms the link by validating an OTP or token, then exposes the patient's care contexts to future discovery requests. POST /v0.5/links/link/add-contexts and /on-confirm implement this flow. Example prompt: Receive POST /v0.5/links/link/on-confirm with the link token and persist the linkage in the HIP database ### Agent-Driven HIP Test Harness A QA agent in a hospital integration project simulates Gateway events against the HIP server during certification testing. The agent uses Jentic to look up the right operation, send a sample request, and assert the response. JWT signing keys remain in your Jentic One instance. Example prompt: Search Jentic for 'send NDHM care-context discovery to a HIP', execute POST /v0.5/care-contexts/discover and assert the on-discover callback ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /v0.5/care-contexts/discover | Receive a care-context discovery request | | POST | /v0.5/care-contexts/on-discover | Reply with the patient's care contexts | | POST | /v0.5/links/link/on-confirm | Confirm linkage with token | | POST | /v0.5/health-information/hip/request | Receive a health-information data request | | POST | /v0.5/health-information/transfer | Transfer encrypted health-information bundle | | POST | /v0.5/consents/hip/notify | Receive consent notification | ## Key resources - **Discovery** — Receive and respond to care-context discovery requests - **Link** — Confirm patient and HIP-initiated linkage with OTP or token - **Consent Flow** — Process consent notifications from the Gateway - **Data Flow** — Handle health-information requests, encrypt bundles, and transfer to HIUs - **Data Transfer** — Encrypted bundle delivery and acknowledgement - **Monitoring** — Heartbeat and certificate endpoints ## Why Jentic - **Setup:** Wiring the NDHM HIP provider specification by hand means implementing the signed request/callback exchange, generating and rotating JWT signing keys, and matching each care-context, link, and health-information message to the gateway host yourself. Through Jentic you install once, import the HIP specification from the API Directory, store the signing credentials once, and your agent calls it. - **Permission scoping:** The HIP callbacks carry the care-context, link, 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 care-contexts on-discover or health-information transfer. Because you pick that operation set, the agent cannot invoke a callback you did not include. - **Credential handling:** Your HIP 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 'transfer an NDHM health-information bundle' or 'respond to a care-context discovery', 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** — The Gateway routes discovery, consent, and data requests to the HIP and aggregates responses. - **NDHM HIU Specifications** — Defines the consumer-side counterpart that requests and receives health information from the HIP. - **NDHM Health ID Service** — HIPs identify patients by the ABHA Health ID issued by this service. ## FAQ ### Why is there no official OpenAPI spec for Health Repository Provider Specifications for HIP? NDHM does not publish a maintained OpenAPI specification for the HIP 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 HIP 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 HIP specification require? HIP 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 respond to care-context discovery requests through this spec? Yes. Implement POST /v0.5/care-contexts/discover to receive the request and POST /v0.5/care-contexts/on-discover to reply with matching care contexts. The Gateway broadcasts discovery requests to all registered HIPs and aggregates the responses. ### What are the rate limits for the HIP endpoints? Rate limits are not declared in the OpenAPI spec. The sandbox at dev.ndhm.gov.in applies fair-use throttling for development; production is governed by the HIP's onboarding tier with the National Health Authority and the volume of patients linked to the HIP. ### How do I transfer a health-information bundle through Jentic? Search Jentic for 'transfer NDHM health-information bundle', load the schema for POST /v0.5/health-information/transfer, and execute with the encrypted FHIR bundle and key material from the original request. Notify the Gateway of delivery via POST /v0.5/health-information/notify. ### Can I limit what my agent is allowed to do with the NDHM HIP Specifications API? Yes. Because you run Jentic One yourself, your own rules decide which HIP operations and signing credentials the agent may use, so you can grant it only the callbacks it needs, such as care-contexts on-discover or health-information transfer, and withhold the rest. The HIP messages carry the care-context, link, and transfer targets inside the signed request body rather than the URL, so scoping happens at the operation level you choose. If you do not include a callback in that set, the agent cannot invoke it.