Supporting APIs
Details of APIs that provide support for operations within HCX. These APIs are useful in enabling the additional message flows in HCX.
Last updated
Was this helpful?
Details of APIs that provide support for operations within HCX. These APIs are useful in enabling the additional message flows in HCX.
Last updated
Was this helpful?
Communications API will be used for communications between multiple participants in the HCX ecosystem.
/communication/request
/communication/on_request
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 APIs are included in the protocol for claim information fetching using EOB resource:
eob/fetch: Used by third parties (like IIB, sponsor or an ISNP) to request for information about a specific claim (or pre-auth or a pre-determination). The third party shall call the fetch API on the HCX switch and HCX internally routes the fetch request to the relevant participant. The payload for this API should contain the correlation_id of the cycle for which the information is being requested for.
eob/on_fetch: This is the callback API via which the requested information is sent back to the third party via the HCX switch.
Sample Task resource as Fetch API request payload:
Response Payload The payload of response to a fetch request should contain all information related to a claim cycle. As per HL7, the ExplanationOfBenefit (EOB) resource combines key information from a Claim, a ClaimResponse, optional account information and can be used as a resource for data exchange for use cases like reporting. Hence, the ExplanationOfBenefit resource shall be used as the response payload for a claim workflow fetch request.
Request Payload Similar to where a FHIR resource is used as the payload to request for status of a specific API call, the Fetch API shall also use Task resource to request for information about a specific claim workflow. The Task resource shall contain details about the claim workflow for which the information is being requested and optionally the purpose of the fetch request.
Third Party Information Sharing API specifications in OpenAPI 3.0 format are available .
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.
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.
This API is for the authorised participants in the network to request information about a claim workflow. The request body (header attributes and the FHIR document) should be sent in the form of a JWE token (RFC-7516) created as per the steps defined in HCX specs.
The JWE payload (request body) primarily should contain the following:
The domain payload is expressed using Task resource, where
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, the sender of the request (who made the Fetch API call) should expect the response via a call back to On Fetch API asynchronously. The response API payload may either contain the requested claim workflow details or error details in case of any errors during processing.
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 the callback API for payors to send the response for a EOB fetch request from the originator. In case of a successful scenario, this API payload should contain the claim workflow details (represented using ExplanationOfBenefit FHIR resource).
Payors 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 if there are any protocol related errors in processing the corresponding EOB Fetch request (see error handling section in the HCX specifications). The x-hcx-status header value in the ProtocolResponse must be "response.error" while responding with an error.
In case the EOB fetch request could be processed, responder should send a JWEPayload derived from protected ProtocolHeader and ExplanationOfBenefit resources as prescribed for the use case by the domain specifications. ExplanationOfBenefit resource inside the payload would contain details about the claim workflow for which a fetch request is sent.
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.