APIs by Scenario

Use this roadmap when you build each PMJAY screen in the HMIS. Call the API at the point where the user has the required data.

Scenario roadmap

Scenario	API to call	Notes	HMIS screen or point
Get beneficiary policies for the selected payer	/participant/get/policies	Send ABHA or mobile number.	After registration.
Get products, services, rules, and documents for a policy	/v1/insuranceplan/request	Send policy code and HFR ID. Refresh after a policy update.	Insurance detail sync.
Check wallet balance and coverage after registration	/v1/coverageeligibility/check	Use purpose validation.	After registration.
Check covered benefits during preauthorisation	/v1/coverageeligibility/check	Use purpose benefits.	Before preauthorisation or enhancement.
Check package eligibility and required documents	/v1/coverageeligibility/check	Use purpose auth-requirements.	Preauth or enhancement page before submission.
Raise preauthorisation	/v1/preauth/submit	Include HPR ID, claim identifier, billable items, diagnostic reports, and clinical documents.	Preauth page.
Raise enhancement after approval	/v1/preauth/submit	Use Claim.use preauthorization and the correct workflow ID. Use the old reference and a new correlation ID.	Enhancement page.
Respond to a preauth query	/v1/preauth/submit	Read query remarks first. Use the correct query response workflow ID.	Query update page.
Cancel preauthorisation before claim	/v1/task/submit	Use code cancel, input type ClaimNumber, and the claim number value.	Preauth cancel page.
Submit claim after discharge	/v1/claim/submit	Use Claim.use claim. Keep amount less than or equal to the approved amount.	Claim page.
Respond to a claim query	/v1/claim/submit	Use the old reference and a new correlation ID.	Claim query update page.
Reprocess a rejected claim	/v1/task/submit	Use code reprocess, input type ClaimNumber, and reason code claimrejected.	Reprocess request page.
Acknowledge payment notice	/v1/paymentnotice/on_request	The source calls this an acknowledgement point. Confirm the current acknowledgement endpoint.	Payment acknowledgement page.
Raise an erroneous claim after partial payment	/v1/task/submit	Use code reprocess and reason code partialpayment.	Erroneous claim page.

Implementation notes

• Store the correlation ID for every request.
• Use a new correlation ID for each query update.
• Keep the old claim or preauth reference in the payload.
• Validate the amount before preauth and claim submission.
• Read InsurancePlan rules before each package selection.
• Run CoverageEligibility again when a treatment changes.