API Structure
Details of the protocol APIs that facilitate the exchange
Last updated
Was this helpful?
Details of the protocol APIs that facilitate the exchange
Last updated
Was this helpful?
Based on the above protocol definition and the message structure, each use case API in the HCP ecosystem is expected to follow the following pattern for the onward and return journey of the use case message:
<transport_protocol>://<server_address>/<protocol_version/><resource_name>/<action|on_action>, where
transport_protocol - for HCX V1 purpose it will always be https
server_address is the address of the server on which the API is called (an HCX for payor/provider or a payor/provider/HCX for an HCX)
protocol_version - API version for the current protocol to help support protocol transitions
resource_name is the name of the domain resource that the API is serving. E.g. for cashless claims, it may be “claims”, “coverage eligibility”, etc. based on the use case.
action is the action sought within the context of that resource
on_action represents the callback from the receiving system for responding to the original message
Keeping this pattern in mind, in the current cashless use case following APIs are expected to be supported.
Please note that search APIs are expected to support search parameters as detailed in the . For FHIR based entities this is expected to be clearly published in the corresponding implementation guides. Visibility and availability of the attributes in the search result payloads are also expected to be defined in domain data specifications.
Eligibility check
/coverageeligibility/check (provider->HCX, HCX->payor)
/coverageeligibility/on_check (payor->HCX, HCX->provider)
PreDetermination submission
/predetermination/submit (provider->HCX, HCX->payor)
/predetermintation/on_submit (payor->HCX, HCX->provider)
PreAuth submission
/preauth/submit (provider->HCX, HCX->payor)
/preauth/on_submit (payor->HCX, HCX->provider)
Claim submission
/claim/submit (provider->HCX, HCX->payor)
/claim/on_submit (payor->HCX, HCX->provider)
Communications API will be used for communications between the payors and providers within the claims cycle.
/communication/request
/communication/on_request
Payment notice and acknowledgement
/paymentnotice/request (payor>HCX, HCX->provider-)
/paymentnotice/on_request (provider->HCX, HCX->payor)
Entity Status API: Status API can be used by providers to know the status of a request made by them. For example, a provider can query the status of a pre-auth request using the status API. HCX gateway shall return the protocol status synchronously and the recipient returns the status in the on_status callback API asynchronously.
/hcx/status
/hcx/on_status
Following details these APIs in detail. These API specs can be opened in swagger editor via this .
This API is for providers to check the eligibility of a beneficiary with the payors via HCX. This API should be used to request whether the patient's coverage is in force, whether it is valid at this or specified date, and/or for requesting the benefits & plan details associated with the coverage.
Providers should send the following details in the request body while making a call for coverage eligibility check:
Overall, the request body (header attributes and the FHIR document) should be sent in the form of a JWE token (RFC-7516) using the steps defined in HCX specs.
The response to this API could be one of the following:
If the request is successfully accepted by the HCX gateway and forwarded to the recipient (i.e. the payor), the provider (who made the Coverage Eligibility Request API call) should expect the response via a call back to Coverage Eligibility Response API asynchronously. The response API payload may either contain the requested coverage details or error details in case of any errors during processing.
An alternate scenario is when the Payor might respond with a redirect instruction asking the Provider to submit the same request to another Payor.
This object is used as payload in the HCX protocol APIs that require the request body to sent in JWE format (as defined in RFC-7516).
This is a callback API is for payors/proessors to send the response for a coverage eligibility request from the providers/originator. In case of a successful scenario, this API payload should contain the eligibilitydetails (in the CoverageEligibilityResponse bundle) and plan url (in the domain header) of the beneficiary for whom the details are requested for.
Payors/Processors should send the following details as the request payload in this callback API:
The responder shall send a ProtocolResponse object (derived from ProtocolHeader) as the request payload in the following scenarios:
In case coverage eligibility request could be processed, responder should send a JWEPayload derived from protected ProtocolHeader and CoverageEligibilityResponse bundle as prescribed for the use case by the domain specifications. CoverageEligibilityResponse resource inside the bundle would contain details about the domain/business processing outcome as follows as per FHIR specifications for the resource.
Object to be returned as payload of the callback API (on_* APIs) in case there are any protocol related errors while processing the request or send a redirection instruction to the original sender of the request.
This API is for providers to submit pre-determination requests (and resubmit updated request) to HCX gateway and for HCX gateway to route the same request to payors.
Payload for this API has to be created as per the Claim Request Bundle defined in HCX Specifications and serialized as per the guidelines in HCX Specifications.
This object is used as payload in the HCX protocol APIs that require the request body to sent in JWE format (as defined in RFC-7516).
This is a callback API is for payors/proessors to send the response for a Pre-Determination request from the providers/originator.
Payors/Processors should send the following details as the request payload in this callback API:
The responder shall send a ProtocolResponse object (derived from ProtocolHeader) as the request payload in the following scenarios:
In case Pre-Determinationrequest could be processed, responder should send a JWEPayload derived from protected ProtocolHeader and ClaimResponse bundle as prescribed for the use case by the domain specifications. ClaimResponse resource inside the bundle would contain details about the domain/business processing outcome as follows as per FHIR specifications for the resource.
Object to be returned as payload of the callback API (on_* APIs) in case there are any protocol related errors while processing the request or send a redirection instruction to the original sender of the request.
This API is for providers to submit pre-authorization requests (and resubmit updated request) to HCX gateway and for HCX gateway to route the same request to payors.
Payload for this API has to be created as per the Claim Request Bundle defined in HCX Specifications and serialized as per the guidelines in HCX Specifications.
This object is used as payload in the HCX protocol APIs that require the request body to sent in JWE format (as defined in RFC-7516).
This is a callback API is for payors/proessors to send the response for a Pre-Authorization request from the providers/originator.
Payors/Processors should send the following details as the request payload in this callback API:
The responder shall send a ProtocolResponse object (derived from ProtocolHeader) as the request payload in the following scenarios:
In case Pre-Authorization request could be processed, responder should send a JWEPayload derived from protected ProtocolHeader and ClaimResponse bundle as prescribed for the use case by the domain specifications. ClaimResponse resource inside the bundle would contain details about the domain/business processing outcome as follows as per FHIR specifications for the resource.
Object to be returned as payload of the callback API (on_* APIs) in case there are any protocol related errors while processing the request or send a redirection instruction to the original sender of the request.
This API is for providers to submit claim requests (and resubmit updated request) to HCX gateway and for HCX gateway to route the same request to payors.
Payload for this API has to be created as per the Claim Request Bundle defined in HCX Specification and serialized as per the guidelines in HCX Specifications.
This object is used as payload in the HCX protocol APIs that require the request body to sent in JWE format (as defined in RFC-7516).
This is a callback API is for payors/proessors to send the response for a Claims request from the providers/originator.
Payors/Processors should send the following details as the request payload in this callback API:
The responder shall send a ProtocolResponse object (derived from ProtocolHeader) as the request payload in the following scenarios:
In case Claims request could be processed, responder should send a JWEPayload derived from protected ProtocolHeader and ClaimResponse bundle as prescribed for the use case by the domain specifications. ClaimResponse resource inside the bundle would contain details about the domain/business processing outcome as follows as per FHIR specifications for the resource.
Object to be returned as payload of the callback API (on_* APIs) in case there are any protocol related errors while processing the request or send a redirection instruction to the original sender of the request.
This API is for payors to raise a communication requests to HCX gateway and for HCX gateway to route the same request to providers during the claims cycle.
A communication request can happen only within the context of a existing claim cycle (predetermination, preauth or the actual claim). The protocol header x-hcx-correlation_id should carry the correlation id of the original claim request for which the communication request is being raised. HCX gateway should validate that the correlation id is a valid identifier and the original claim request is still open.
Payload for this API has to be created as per the Communication Request defined in HCX Specifications and serialized as per the guidelines in HCX Specifications.
This object is used as payload in the HCX protocol APIs that require the request body to sent in JWE format (as defined in RFC-7516).
This is a callback API is for recievers of Communication request to send the Communication response.
Responder should send the following details as the request payload in this callback API:
The responder shall send a ProtocolResponse object (derived from ProtocolHeader) as the request payload in the following scenarios:
In case CommunicationRequest could be processed, responder should send a JWEPayload derived from protected ProtocolHeader and Communication bundle as prescribed for the use case by the domain specifications. Communication resource inside the bundle would contain details about the domain/business processing outcome as follows as per FHIR specifications for the resource.
Object to be returned as payload of the callback API (on_* APIs) in case there are any protocol related errors while processing the request or send a redirection instruction to the original sender of the request.
This API is for Payors to send Payment notification/reconciliation objects to Providers via the HCX gateway. This API is available on HCX gateways and Provider systems.
Payload for this API has to be created as per the Payment Notice defined in HCX Specifications and serialized as JWE json as per the guidelines in HCX Specifications.
This object is used as payload in the HCX protocol APIs that require the request body to sent in JWE format (as defined in RFC-7516).
This is a callback API is for service providers to send the response for a Payment notice request from the payor/processors.
Service providers should send the following details as the request payload in this callback API:
The responder shall send a ProtocolResponse object (derived from ProtocolHeader) as the request payload in the following scenarios:
In case Payment Notice request could be processed, responder should send a JWEPayload derived from protected ProtocolHeader and ClaimResponse bundle as prescribed for the use case by the domain specifications. PaymentNotice resource inside the bundle would contain details about the domain/business processing outcome as follows as per FHIR specifications for the resource.
Object to be returned as payload of the callback API (on_* APIs) in case there are any protocol related errors while processing the request or send a redirection instruction to the original sender of the request.
Participants (Provider/Payors) in the network can check the business status of particular processes initiated, for example, status of pre-auth request, claim, status of information requested. The request payload is expressed using FHIR Task, where
The protocol header x-hcx-correlation_id should carry the correlation id of the process (request) for which the status is being requested for. HCX gateway should validate that the correlation id is a valid identifier and the request is still open.
The request body for this API should be sent in the form of a JWE token (RFC-7516) using the steps defined in HCX specs. HCX gateway shall validate the incoming request and send the protocol status in the http response. The protocol status value could be one of the following:
This object is used as payload in the HCX protocol APIs that require the request body to sent in JWE format (as defined in RFC-7516).
This is a callback API is for recievers of status request to send the processing status of requested resource.
Responder should send the following details as the request payload in this callback API:
The responder shall send a ProtocolResponse object (derived from ProtocolHeader) as the request payload in the following scenarios:
In case Status request could be processed, responder should send a JWEPayload derived from protected ProtocolHeader and Response bundle corresponding to the resource (e.g. a CoverageEligibilityResponse or a ClaimResponse etc.) indicated in the status request. It could be any of the Response resources as prescribed for the use case by the domain specifications. Response resource inside the bundle would contain details about the domain/business processing outcome as follows as per FHIR specifications for the resource.
In a way this callback behaves similar to corresponding cycle's on_* callback, however, while those callbacks would usually carry the FHIR resource with "complete" or "error" outcome, this callback may also indicate a partially processed resource.
Object to be returned as payload of the callback API (on_* APIs) in case there are any protocol related errors while processing the request or send a redirection instruction to the original sender of the request.