Requests and Responses

Use this page when you prepare a JWE payload for an NHCX use case. Use Payload Code Snippets to encrypt and decrypt the payload. Use Provider Use Cases and Payer Use Cases for sandbox exit scope.

Common protected headers

Include these mandatory headers in each encrypted request and response. Add the optional headers only when the use case needs them.

Header	Type	Mandatory value or rule
alg	String	RSA-OAEP-256
enc	String	A256GCM
x-hcx-api_call_id	UUID	New API call ID
x-hcx-status	String	Use the status in the use case table.
x-hcx-timestamp	Unix timestamp	Current timestamp, for example 1706308383
x-hcx-sender_code	String	Sender participant code, for example 1000001@sbx
x-hcx-recipient_code	String	Recipient participant code, for example 1000002@sbx
x-hcx-correlation_id	UUID	Request API call ID for a response, or the target request ID for status.
x-hcx-ben-abha-id	String	Beneficiary ABHA ID

Optional header	Type	Use
x-hcx-workflow_id	String	Add the workflow code when available.
x-hcx-use_case	String	Add the use case value when available.
x-hcx-debug_flag	Enum	Add INFO when you need diagnostics.
x-hcx-error_details	ProtocolError	Add code, message, and trace when an error exists.

Protocol error response

Send this response when the receiver cannot decrypt, validate, or process a payload.

Field	Mandatory value or rule
type	ProtocolResponse
alg	RSA-OAEP-256
enc	A256GCM
x-hcx-api_call_id	New API call ID
x-hcx-status	response.error
x-hcx-timestamp	Current timestamp
x-hcx-sender_code	Error sender code
x-hcx-recipient_code	Error receiver code
x-hcx-correlation_id	Original request correlation ID
x-hcx-error_details	code, message, and trace
x-hcx-ben-abha-id	Beneficiary ABHA ID

Use case payload rules

Coverage Eligibility

Flow	Endpoint	Bundle	Status	Mandatory values
Request	/v1/coverageeligibility/check	CoverageEligibilityRequestBundle	request.initiated	CoverageEligibilityRequest.identifier, status=active, priority=normal, purpose=validation, patient, created, enterer, provider, facility
Response	/v1/coverageeligibility/on_check	CoverageEligibilityResponseBundle	response.completed	CoverageEligibilityResponse and required reference resources
Error	/v1/coverageeligibility/on_check	ProtocolResponse	response.error	Common error fields

Preauthorization

Flow	Endpoint	Bundle	Status	Mandatory values
Request	/v1/preauth/submit	ClaimBundle	request.initiated	Claim.identifier, status=active, priority=normal, purpose=validation, use=preauthorization, patient, type, created, enterer, provider, facility
Response	/v1/preauth/on_submit	ClaimResponseBundle	response.complete	ClaimResponse and required reference resources
Error	/v1/preauth/on_submit	ProtocolResponse	response.error	Common error fields

Claim

Flow	Endpoint	Bundle	Status	Mandatory values
Request	/v1/claim/submit	ClaimBundle	request.initiated	Claim.identifier, status=active, priority=normal, purpose=validation, use=claim, patient, type, created, enterer, provider, facility
Response	/v1/claim/on_submit	ClaimResponseBundle	response.partial or response.complete	ClaimResponse and required reference resources
Error	/v1/claim/on_submit	ProtocolResponse	response.error	Common error fields

Payment Notice

Flow	Endpoint	Bundle	Status	Mandatory values
Request	/v1/paymentnotice/request	TaskBundle with PaymentNotice	request.initiated	PaymentNotice.identifier, status=active, request, payment, recipient, amount
Payment reconciliation	Included in request	PaymentReconciliation	active or canceled	paymentDate, paymentAmount, paymentIdentifier
Response	/v1/paymentnotice/on_request	TaskBundle with Task output	response.complete	Task output ACKNOWLEDGED or RECEIVED
Error	/v1/paymentnotice/on_request	ProtocolResponse	response.error	Common error fields

Communication for Additional Documents

Flow	Endpoint	Bundle	Status	Mandatory values
Request	/v1/communication/request	TaskBundle with CommunicationRequest	request.initiated	CommunicationRequest.identifier=ClaimNumber, status=active, priority=routine, reasonReference, basedOn
Response	/v1/communication/on_request	TaskBundle with Communication	response.complete	Communication.identifier=ClaimNumber, status=completed, priority=routine, statusReason, about, payload.contentAttachment, payload.contentCodeableConcept
Response optional values	/v1/communication/on_request	Communication	response.complete	payload.contentReference, recipient, sender, note
Error	/v1/communication/on_request	ProtocolResponse	response.error	Common error fields

Reprocess, Cancel, Release, or Nullify

Flow	Endpoint	Bundle	Status	Mandatory values
Request	/v1/task/submit	TaskBundle	request.initiated	Task.status=requested, Task.code, Task.input.type=ClaimNumber, Task.input.value=Claim Number, Task.basedOn
Task code	/v1/task/submit	Task	request.initiated	Use reprocess, cancel, release, or nullify.
Response	/v1/task/on_submit	TaskBundle	response.complete	Task and ClaimResponse as bundle components
Error	/v1/task/on_submit	ProtocolResponse	response.error	Common error fields

Search

Flow	Endpoint	Bundle	Status	Mandatory values
Request	/v1/search/submit	TaskBundle	request.initiated	Task.status=requested, Task.input.type, Task.input.value, Task.basedOn
Input values	/v1/search/submit	Task	request.initiated	Use 1 or more inputs, such as ClaimNumber, FromDate, ToDate, PolicyNumber, or ProductNumber.
Response	/v1/search/on_submit	TaskBundle	response.partial or response.complete	Task and ClaimResponse as bundle components
Error	/v1/search/on_submit	ProtocolResponse	response.error	Common error fields

Status

Flow	Endpoint	Bundle	Status	Mandatory values
Request	/v1/status	Empty payload	request.initiated	Common mandatory headers and an empty payload string
Response	/v1/on_status	Protocol header only	request.dispatched	Common mandatory response headers

Insurance Plan

Flow	Endpoint	Bundle	Status	Mandatory values
Request	/v1/insuranceplan/request	Task	request.initiated	Task.code=poll, Task.input.type=PolicyNumber, Task.input.value
Request optional inputs	/v1/insuranceplan/request	Task	request.initiated	ProductNumber and ProviderId
Response	/v1/insuranceplan/on_request	TaskBundle	response.complete	InsurancePlan output as InsurancePlanBundle

Value sets

Use these codes when the related field appears in a bundle.

Workflow ID values

Code	Value
10	Patient Registered
11	Patient Admitted
12	Preauth Request Initiated
121	Preauth Query Response Submitted
13	Enhancement Request Initiated
131	Enhancement Query Response Submitted
14	Discharge Submitted
141	Discharge Query Response Submitted
15	Claim Request Initiated
16	Claim Request Resubmitted
151	Claim Query Response Submitted
17	Payment Received
18	Reprocess Request Submitted
20	Preauth Request Received
21	Preauth Request Approved
22	Enhancement Request Approved
241	Enhancement Request Queried
23	Preauth Request Rejected
24	Preauth Request Queried
25	Claim Request Received
26	Claim Request Approved
261	Discharge Request Approved
262	Discharge Request Rejected
263	Discharge Request Queried
27	Claim Request Queried
28	Claim Request in process
29	Claim Forwarded
251	Reprocess Request Received
252	Reprocess Request Approved
253	Reprocess Request Rejected
254	Reprocess Request Queried
30	Payment Initiated
31	Payment Processed
33	Payment Settled

Use case values

Code	Description
Preauthorization New	New preauthorization request
Preauthorization Enhancement	Enhancement request for a preapproved case
Preauthorization Resubmit	Resubmitted preauthorization
Claim New	New claim request
Claim Resubmit	Resubmitted claim request
Claim Reprocess	Claim reprocess request after partial approval or rejection

Task code values

Code	Description
reprocess	Request claim readjudication after partial approval or rejection.
nullify	Close a provider claim.
cancel	Cancel a provider claim.
approve	Approve a task.
search	Search resources such as claim responses.
poll	Retrieve data for a given input.
suspend	Suspend a submitted preauthorization or claim.

Task input values

Code	Description
PayerId	Identifies the payer.
ProviderId	Identifies the provider or hospital.
PolicyNumber	Identifies the member policy.
ProductNumber	Identifies the policy benefit product.
ClaimNumber	Finds claim details in the payer system.
IntimationNumber	Finds preauthorization or claim details in the payer system.
FromDate	Sets the start date for search.
ToDate	Sets the end date for search.
FinanceYear	Sets the policy year or financial year.
ServiceCode	Identifies a benefit service code.

Payment type values

Code	Description
approvedamount	Approved claim amount
tds	TDS deduction amount
servicetax	Service tax amount
advance	Advance amount
recovered	Recovered amount
penalty	Penalty amount
claimedamount	Provider claimed amount

Task output values

Code	Description
paymentack	Payment acknowledged
claimcancelled	Claim cancelled
claimreinitiated	Claim reinitiated
claimsuspended	Claim suspended
taskack	Task acknowledged
taskdelivered	Task delivered

Task reason values

Code	Description
partialpayment	Reprocess due to partial payment by payer
erroneousclaim	Reprocess due to an erroneous provider claim
claimrejected	Reprocess due to claim rejection by payer
referred	Referral to another hospital
erroneousregistration	Incorrect beneficiary registration for a policy
wrongdiagnosis	Additional facts found during treatment
treatmentplanchanged	Treatment plan changed during admission

Adjudication reason values

Code	Description
Non-CoveredService	Service not covered by the policy
ExceededCoverageLimit	Claim amount exceeds the coverage limit
DuplicateClaim	Claim submitted more than once
Coordination-of-Benefits	Claim needs coordination with another policy
IncompleteDocumentation	Required documents are incomplete
PolicyDeductible	Claim amount is subject to policy deductible
Co-Payment	Claimant owes co-payment or coinsurance
ClaimError-1	Claim has a submission error.
FraudulentClaim	Claim appears fraudulent.
MedicalNecessity	Service lacks medical necessity.
BenefitLimitReached	Claimant reached the benefit limit.
MissedFilingDeadline	Claim missed the filing deadline.
PaymentAlreadyMade	Service already has payment.
ClaimError-2 to ClaimError-28	Use the claim error code for the matching scheme reason.
PreauthError-1 to PreauthError-15	Use the preauthorization error code for the matching scheme reason.

Claim response form code values

Code	Description
preauthapproval	Preauthorization approval letter
claimapproval	Claim settlement approval letter
preauthdenial	Preauthorization rejection letter
claimdenial	Claim rejection letter
feedbackletter	Patient feedback form
policydocument	Policy terms document
dischargeapproval	Provisional discharge approval

Procedure category values

Use the HL7 procedure category value set.

Code	Description
Procedure	Procedure service or product
Investigation	Investigation service or product
Implant	Implant service or product
Drug	Drug service or product
Package	Package service or product
Room	Room service or product
Stratification	Stratification service or product
Consultation	Consultation service or product

Benefit category values

Use the ABDM benefit category value set.

Code	Description
BM	Burns Management
ER	Emergency Room Packages
HD	High End Diagnostics
HM	High End Medicine
HP	High End Procedures
ID	Infectious Diseases, General Medicine
IN	Interventional
MC	Cardiology
MG	General Medicine, Pediatric Medical Management
MM	Mental Disorders
MN	Neonatal Care
MO	Medical Oncology
MP	Ophthalmology, Pediatric Medical Management, General Medicine
MR	Radiation Oncology
OT	Organ and Tissue Transplant
SB	Orthopedics
SC	Surgical Oncology
SE	Ophthalmology
SG	General Surgery, Pediatric Surgery
SL	ENT
SM	Oral and Maxillofacial Surgery
SN	Neurosurgery
SO	OBG and Gynecology
SP	Plastic and Reconstructive Surgery
SS	Pediatric Surgery
ST	Polytrauma
SU	Urology
SV	CTVS
US	Unspecified Surgical Package