API Structure

Details of the protocol APIs that facilitate the exchange

API Structure

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 domain data specifications. 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.

CoverageEligibility

• Eligibility check

• /coverageeligibility/check (provider->HCX, HCX->payor)

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:

1. A set of header attributes that provide transport, security, message integrity and summary information about the message being exchanged. This information is used by the HCX gateway for routing the request and auditing purposes.
2. Domain payload containing the CoverageEligibilityRequest domain entity (eObject) as prescribed for the use case by the domain specifications. This needs to be encrypted so that HCX cannot read this and can be decrypted & processed only by the intended recipient.

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:

1. A successful accepted response from the HCX gateway if the strucuture of the request is valid and the validation of open attributes (protocol headers) is successful. Upon successful validation, HCX gateway forwards the same request to the intended recipient asynchronously.
2. An error response if any of the validations fail.

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.

POST/coverageeligibility/check

Authorization

bearer_auth

Body

application/json

payload*object (string)

The paylod should be a JWE token containing the following elements.

1. Protected headers (protected) - A set of attributes that provide transport, security, message integrity and summary information about the message being exchanged.
2. JWE element (encrypted_key) - Content Encryption Key.
3. JWE element (iv) - Initialisation Vector for the algorithm.
4. Encrypted Payload (ciphertext) - Payload containing the relevant domain entity (eObject) as prescribed for the use case by the domain specifications. This needs to be encrypted so that HCX cannot read this.
5. Authentication tag (authentication_tag) - Digital signature on the protected header and the payload of the message to ensure its integrity.

The final payload should be serialzed using JWE compact serialization as defined in the RFC-7516 -

protected || '.' || encrypted_key || '.' || iv || '.' || ciphertext || '.' || authentication_tag

Detailed steps on how to construct the JWE token are provided in this section of the HCX specifications.

Response

202400404500

Accepted

Body

application/json

timestamp*string

Unix timestamp when the response is sent.

api_call_id*string (uuid)

That is present in the transport header of the request.

correlation_id*string (uuid)

That is present in the transport header of the request.

Request

JavaScriptCurl

const response = await fetch('/coverageeligibility/check', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "payload": "eyJlbmMiOiJBMjU2R0NNIiwKImFsZyI6IlJTQS1PQUVQIiwKIngtaGN4LXNlbmRlcl9jb2RlIjoiMS00ZGMzZTA4OC1hMzEzLTQ0YWItYWZhMS0wMjIyOTU5Y2I3NWIiLAoieC1oY3gtcmVjaXBpZW50X2NvZGUiOiIxLTkzZjkwOGJhLWI1NzktNDUzZS04YjJhLTU2MDIyYWZhZDI3NSIsCiJ4LWhjeC1yZXF1ZXN0X2lkIjoiMjZiMTA2MGMtMWU4My00NjAwLTk2MTItZWEzMWUwY2E1MDkxIiwKIngtaGN4LWNvcnJlbGF0aW9uX2lkIjoiNWU5MzRmOTAtMTExZC00ZjBiLWIwMTYtYzIyZDgyMDY3NGUxIiwKIngtaGN4LXRpbWVzdGFtcCI6IjIwMjEtMTAtMjdUMjA6MzU6NTIuNjM2KzA1MzAiLAoieC1oY3gtc3RhdHVzIjoicmVxdWVzdC5pbml0aWF0ZSIsCiJ4LWhjeC13b3JrZmxvd19pZCI6IjVlOTM0ZjkwLTExMWQtNGYwYi1iMDE2LWMyMmQ4MjA2NzRlMiIsCiJ4LWhjeC1kZWJ1Z19mbGFnIjoiSW5mbyIsCiJ4LWhjeC1lcnJvcl9kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCAidHJhY2UiOiAiIn0sCiJ4LWhjeC1kZWJ1Z19kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCJ0cmFjZSI6IiJ9LAoiandzX2hlYWRlciI6eyJ0eXAiOiJKV1QiLCAiYWxnIjoiUlMyNTYifSwKImp3ZV9oZWFkZXIiOnsiYWxnIjoiUlNBLU9BRVAiLCJlbmMiOiJBMjU2R0NNIn0KfQ==.6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.Mz-VPPyU4RlcuYv1IwIvzw"
    }),
});
const data = await response.json();

Response

{
  "timestamp": "1629057611000",
  "api_call_id": "123e4567-e89b-12d3-a456-426614174000",
  "correlation_id": "123e4567-e89b-12d3-a456-426614174000"
}

• /coverageeligibility/on_check (payor->HCX, HCX->provider)

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:

1. The responder shall send a ProtocolResponse object (derived from ProtocolHeader) as the request payload in the following scenarios:

   • if there are any protocol related errors in processing the corresponding Coverage Eligibility 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.
   • if the responder wants to send a redirection instruction to the original sender (see redirection flow in the HCX specifications). The x-hcx-status header value in the ProtocolResponse must be "response.redirect" and the x-hcx-redirect_to header must have a value while sending a redirection instruction.

2. 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.

POST/coverageeligibility/on_check

Authorization

bearer_auth

Body

application/json

one of

JWEPayload (object (byte))ProtocolResponse (object)

Response

202400404500

Accepted

Body

application/json

timestamp*string

Unix timestamp when the response is sent.

api_call_id*string (uuid)

That is present in the transport header of the request.

correlation_id*string (uuid)

That is present in the transport header of the request.

Request

JavaScriptCurl

const response = await fetch('/coverageeligibility/on_check', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "payload": "eyJlbmMiOiJBMjU2R0NNIiwKImFsZyI6IlJTQS1PQUVQIiwKIngtaGN4LXNlbmRlcl9jb2RlIjoiMS00ZGMzZTA4OC1hMzEzLTQ0YWItYWZhMS0wMjIyOTU5Y2I3NWIiLAoieC1oY3gtcmVjaXBpZW50X2NvZGUiOiIxLTkzZjkwOGJhLWI1NzktNDUzZS04YjJhLTU2MDIyYWZhZDI3NSIsCiJ4LWhjeC1yZXF1ZXN0X2lkIjoiMjZiMTA2MGMtMWU4My00NjAwLTk2MTItZWEzMWUwY2E1MDkxIiwKIngtaGN4LWNvcnJlbGF0aW9uX2lkIjoiNWU5MzRmOTAtMTExZC00ZjBiLWIwMTYtYzIyZDgyMDY3NGUxIiwKIngtaGN4LXRpbWVzdGFtcCI6IjIwMjEtMTAtMjdUMjA6MzU6NTIuNjM2KzA1MzAiLAoieC1oY3gtc3RhdHVzIjoicmVxdWVzdC5pbml0aWF0ZSIsCiJ4LWhjeC13b3JrZmxvd19pZCI6IjVlOTM0ZjkwLTExMWQtNGYwYi1iMDE2LWMyMmQ4MjA2NzRlMiIsCiJ4LWhjeC1kZWJ1Z19mbGFnIjoiSW5mbyIsCiJ4LWhjeC1lcnJvcl9kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCAidHJhY2UiOiAiIn0sCiJ4LWhjeC1kZWJ1Z19kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCJ0cmFjZSI6IiJ9LAoiandzX2hlYWRlciI6eyJ0eXAiOiJKV1QiLCAiYWxnIjoiUlMyNTYifSwKImp3ZV9oZWFkZXIiOnsiYWxnIjoiUlNBLU9BRVAiLCJlbmMiOiJBMjU2R0NNIn0KfQ==.6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.Mz-VPPyU4RlcuYv1IwIvzw"
    }),
});
const data = await response.json();

Response

{
  "timestamp": "1629057611000",
  "api_call_id": "123e4567-e89b-12d3-a456-426614174000",
  "correlation_id": "123e4567-e89b-12d3-a456-426614174000"
}

Claims

• PreDetermination submission

• /predetermination/submit (provider->HCX, HCX->payor)

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 Document defined in HCX Specifications and serialized as per the guidelines in HCX Specifications.

POST/predetermination/submit

Authorization

bearer_auth

Body

application/json

payload*object (string)

The paylod should be a JWE token containing the following elements.

1. Protected headers (protected) - A set of attributes that provide transport, security, message integrity and summary information about the message being exchanged.
2. JWE element (encrypted_key) - Content Encryption Key.
3. JWE element (iv) - Initialisation Vector for the algorithm.
4. Encrypted Payload (ciphertext) - Payload containing the relevant domain entity (eObject) as prescribed for the use case by the domain specifications. This needs to be encrypted so that HCX cannot read this.
5. Authentication tag (authentication_tag) - Digital signature on the protected header and the payload of the message to ensure its integrity.

The final payload should be serialzed using JWE compact serialization as defined in the RFC-7516 -

protected || '.' || encrypted_key || '.' || iv || '.' || ciphertext || '.' || authentication_tag

Detailed steps on how to construct the JWE token are provided in this section of the HCX specifications.

Response

202400404500

Accepted

Body

application/json

timestamp*string

Unix timestamp when the response is sent.

api_call_id*string (uuid)

That is present in the transport header of the request.

correlation_id*string (uuid)

That is present in the transport header of the request.

Request

JavaScriptCurl

const response = await fetch('/predetermination/submit', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "payload": "eyJlbmMiOiJBMjU2R0NNIiwKImFsZyI6IlJTQS1PQUVQIiwKIngtaGN4LXNlbmRlcl9jb2RlIjoiMS00ZGMzZTA4OC1hMzEzLTQ0YWItYWZhMS0wMjIyOTU5Y2I3NWIiLAoieC1oY3gtcmVjaXBpZW50X2NvZGUiOiIxLTkzZjkwOGJhLWI1NzktNDUzZS04YjJhLTU2MDIyYWZhZDI3NSIsCiJ4LWhjeC1yZXF1ZXN0X2lkIjoiMjZiMTA2MGMtMWU4My00NjAwLTk2MTItZWEzMWUwY2E1MDkxIiwKIngtaGN4LWNvcnJlbGF0aW9uX2lkIjoiNWU5MzRmOTAtMTExZC00ZjBiLWIwMTYtYzIyZDgyMDY3NGUxIiwKIngtaGN4LXRpbWVzdGFtcCI6IjIwMjEtMTAtMjdUMjA6MzU6NTIuNjM2KzA1MzAiLAoieC1oY3gtc3RhdHVzIjoicmVxdWVzdC5pbml0aWF0ZSIsCiJ4LWhjeC13b3JrZmxvd19pZCI6IjVlOTM0ZjkwLTExMWQtNGYwYi1iMDE2LWMyMmQ4MjA2NzRlMiIsCiJ4LWhjeC1kZWJ1Z19mbGFnIjoiSW5mbyIsCiJ4LWhjeC1lcnJvcl9kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCAidHJhY2UiOiAiIn0sCiJ4LWhjeC1kZWJ1Z19kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCJ0cmFjZSI6IiJ9LAoiandzX2hlYWRlciI6eyJ0eXAiOiJKV1QiLCAiYWxnIjoiUlMyNTYifSwKImp3ZV9oZWFkZXIiOnsiYWxnIjoiUlNBLU9BRVAiLCJlbmMiOiJBMjU2R0NNIn0KfQ==.6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.Mz-VPPyU4RlcuYv1IwIvzw"
    }),
});
const data = await response.json();

Response

{
  "timestamp": "1629057611000",
  "api_call_id": "123e4567-e89b-12d3-a456-426614174000",
  "correlation_id": "123e4567-e89b-12d3-a456-426614174000"
}

• /predetermintation/on_submit (payor->HCX, HCX->provider)

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:

1. The responder shall send a ProtocolResponse object (derived from ProtocolHeader) as the request payload in the following scenarios:

   • if there are any protocol related errors in processing the corresponding Pre-Determination request (see error handling section. The x-hcx-status header value in the ProtocolResponse must be "response.error" while responding with an error.
   • if the responder wants to send a redirection instruction to the original sender (see redirection flow in the HCX specifications). The x-hcx-status header value in the ProtocolResponse must be "response.redirect" and the x-hcx-redirect_to header must have a value while sending a redirection instruction.

2. 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.

POST/predetermination/on_submit

Authorization

bearer_auth

Body

application/json

one of

JWEPayload (object (byte))ProtocolResponse (object)

Response

202400404500

Accepted

Body

application/json

timestamp*string

Unix timestamp when the response is sent.

api_call_id*string (uuid)

That is present in the transport header of the request.

correlation_id*string (uuid)

That is present in the transport header of the request.

Request

JavaScriptCurl

const response = await fetch('/predetermination/on_submit', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "payload": "eyJlbmMiOiJBMjU2R0NNIiwKImFsZyI6IlJTQS1PQUVQIiwKIngtaGN4LXNlbmRlcl9jb2RlIjoiMS00ZGMzZTA4OC1hMzEzLTQ0YWItYWZhMS0wMjIyOTU5Y2I3NWIiLAoieC1oY3gtcmVjaXBpZW50X2NvZGUiOiIxLTkzZjkwOGJhLWI1NzktNDUzZS04YjJhLTU2MDIyYWZhZDI3NSIsCiJ4LWhjeC1yZXF1ZXN0X2lkIjoiMjZiMTA2MGMtMWU4My00NjAwLTk2MTItZWEzMWUwY2E1MDkxIiwKIngtaGN4LWNvcnJlbGF0aW9uX2lkIjoiNWU5MzRmOTAtMTExZC00ZjBiLWIwMTYtYzIyZDgyMDY3NGUxIiwKIngtaGN4LXRpbWVzdGFtcCI6IjIwMjEtMTAtMjdUMjA6MzU6NTIuNjM2KzA1MzAiLAoieC1oY3gtc3RhdHVzIjoicmVxdWVzdC5pbml0aWF0ZSIsCiJ4LWhjeC13b3JrZmxvd19pZCI6IjVlOTM0ZjkwLTExMWQtNGYwYi1iMDE2LWMyMmQ4MjA2NzRlMiIsCiJ4LWhjeC1kZWJ1Z19mbGFnIjoiSW5mbyIsCiJ4LWhjeC1lcnJvcl9kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCAidHJhY2UiOiAiIn0sCiJ4LWhjeC1kZWJ1Z19kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCJ0cmFjZSI6IiJ9LAoiandzX2hlYWRlciI6eyJ0eXAiOiJKV1QiLCAiYWxnIjoiUlMyNTYifSwKImp3ZV9oZWFkZXIiOnsiYWxnIjoiUlNBLU9BRVAiLCJlbmMiOiJBMjU2R0NNIn0KfQ==.6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.Mz-VPPyU4RlcuYv1IwIvzw"
    }),
});
const data = await response.json();

Response

{
  "timestamp": "1629057611000",
  "api_call_id": "123e4567-e89b-12d3-a456-426614174000",
  "correlation_id": "123e4567-e89b-12d3-a456-426614174000"
}

• PreAuth submission

• /preauth/submit (provider->HCX, HCX->payor)

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 Document defined in HCX Specifications and serialized as per the guidelines in HCX Specifications.

POST/preauth/submit

Authorization

bearer_auth

Body

application/json

payload*object (string)

The paylod should be a JWE token containing the following elements.

1. Protected headers (protected) - A set of attributes that provide transport, security, message integrity and summary information about the message being exchanged.
2. JWE element (encrypted_key) - Content Encryption Key.
3. JWE element (iv) - Initialisation Vector for the algorithm.
4. Encrypted Payload (ciphertext) - Payload containing the relevant domain entity (eObject) as prescribed for the use case by the domain specifications. This needs to be encrypted so that HCX cannot read this.
5. Authentication tag (authentication_tag) - Digital signature on the protected header and the payload of the message to ensure its integrity.

The final payload should be serialzed using JWE compact serialization as defined in the RFC-7516 -

protected || '.' || encrypted_key || '.' || iv || '.' || ciphertext || '.' || authentication_tag

Detailed steps on how to construct the JWE token are provided in this section of the HCX specifications.

Response

202400404500

Accepted

Body

application/json

timestamp*string

Unix timestamp when the response is sent.

api_call_id*string (uuid)

That is present in the transport header of the request.

correlation_id*string (uuid)

That is present in the transport header of the request.

Request

JavaScriptCurl

const response = await fetch('/preauth/submit', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "payload": "eyJlbmMiOiJBMjU2R0NNIiwKImFsZyI6IlJTQS1PQUVQIiwKIngtaGN4LXNlbmRlcl9jb2RlIjoiMS00ZGMzZTA4OC1hMzEzLTQ0YWItYWZhMS0wMjIyOTU5Y2I3NWIiLAoieC1oY3gtcmVjaXBpZW50X2NvZGUiOiIxLTkzZjkwOGJhLWI1NzktNDUzZS04YjJhLTU2MDIyYWZhZDI3NSIsCiJ4LWhjeC1yZXF1ZXN0X2lkIjoiMjZiMTA2MGMtMWU4My00NjAwLTk2MTItZWEzMWUwY2E1MDkxIiwKIngtaGN4LWNvcnJlbGF0aW9uX2lkIjoiNWU5MzRmOTAtMTExZC00ZjBiLWIwMTYtYzIyZDgyMDY3NGUxIiwKIngtaGN4LXRpbWVzdGFtcCI6IjIwMjEtMTAtMjdUMjA6MzU6NTIuNjM2KzA1MzAiLAoieC1oY3gtc3RhdHVzIjoicmVxdWVzdC5pbml0aWF0ZSIsCiJ4LWhjeC13b3JrZmxvd19pZCI6IjVlOTM0ZjkwLTExMWQtNGYwYi1iMDE2LWMyMmQ4MjA2NzRlMiIsCiJ4LWhjeC1kZWJ1Z19mbGFnIjoiSW5mbyIsCiJ4LWhjeC1lcnJvcl9kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCAidHJhY2UiOiAiIn0sCiJ4LWhjeC1kZWJ1Z19kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCJ0cmFjZSI6IiJ9LAoiandzX2hlYWRlciI6eyJ0eXAiOiJKV1QiLCAiYWxnIjoiUlMyNTYifSwKImp3ZV9oZWFkZXIiOnsiYWxnIjoiUlNBLU9BRVAiLCJlbmMiOiJBMjU2R0NNIn0KfQ==.6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.Mz-VPPyU4RlcuYv1IwIvzw"
    }),
});
const data = await response.json();

Response

{
  "timestamp": "1629057611000",
  "api_call_id": "123e4567-e89b-12d3-a456-426614174000",
  "correlation_id": "123e4567-e89b-12d3-a456-426614174000"
}

• /preauth/on_submit (payor->HCX, HCX->provider)

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:

1. The responder shall send a ProtocolResponse object (derived from ProtocolHeader) as the request payload in the following scenarios:

   • if there are any protocol related errors in processing the corresponding Pre-Authorization 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.
   • if the responder wants to send a redirection instruction to the original sender (see redirection flow in the HCX specifications). The x-hcx-status header value in the ProtocolResponse must be "response.redirect" and the x-hcx-redirect_to header must have a value while sending a redirection instruction.

2. 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.

POST/preauth/on_submit

Authorization

bearer_auth

Body

application/json

one of

JWEPayload (object (byte))ProtocolResponse (object)

Response

202400404500

Accepted

Body

application/json

timestamp*string

Unix timestamp when the response is sent.

api_call_id*string (uuid)

That is present in the transport header of the request.

correlation_id*string (uuid)

That is present in the transport header of the request.

Request

JavaScriptCurl

const response = await fetch('/preauth/on_submit', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "payload": "eyJlbmMiOiJBMjU2R0NNIiwKImFsZyI6IlJTQS1PQUVQIiwKIngtaGN4LXNlbmRlcl9jb2RlIjoiMS00ZGMzZTA4OC1hMzEzLTQ0YWItYWZhMS0wMjIyOTU5Y2I3NWIiLAoieC1oY3gtcmVjaXBpZW50X2NvZGUiOiIxLTkzZjkwOGJhLWI1NzktNDUzZS04YjJhLTU2MDIyYWZhZDI3NSIsCiJ4LWhjeC1yZXF1ZXN0X2lkIjoiMjZiMTA2MGMtMWU4My00NjAwLTk2MTItZWEzMWUwY2E1MDkxIiwKIngtaGN4LWNvcnJlbGF0aW9uX2lkIjoiNWU5MzRmOTAtMTExZC00ZjBiLWIwMTYtYzIyZDgyMDY3NGUxIiwKIngtaGN4LXRpbWVzdGFtcCI6IjIwMjEtMTAtMjdUMjA6MzU6NTIuNjM2KzA1MzAiLAoieC1oY3gtc3RhdHVzIjoicmVxdWVzdC5pbml0aWF0ZSIsCiJ4LWhjeC13b3JrZmxvd19pZCI6IjVlOTM0ZjkwLTExMWQtNGYwYi1iMDE2LWMyMmQ4MjA2NzRlMiIsCiJ4LWhjeC1kZWJ1Z19mbGFnIjoiSW5mbyIsCiJ4LWhjeC1lcnJvcl9kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCAidHJhY2UiOiAiIn0sCiJ4LWhjeC1kZWJ1Z19kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCJ0cmFjZSI6IiJ9LAoiandzX2hlYWRlciI6eyJ0eXAiOiJKV1QiLCAiYWxnIjoiUlMyNTYifSwKImp3ZV9oZWFkZXIiOnsiYWxnIjoiUlNBLU9BRVAiLCJlbmMiOiJBMjU2R0NNIn0KfQ==.6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.Mz-VPPyU4RlcuYv1IwIvzw"
    }),
});
const data = await response.json();

Response

{
  "timestamp": "1629057611000",
  "api_call_id": "123e4567-e89b-12d3-a456-426614174000",
  "correlation_id": "123e4567-e89b-12d3-a456-426614174000"
}

• Claim submission

• /claim/submit (provider->HCX, HCX->payor)

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 Document defined in HCX Specification and serialized as per the guidelines in HCX Specifications.

POST/claim/submit

Authorization

bearer_auth

Body

application/json

payload*object (string)

The paylod should be a JWE token containing the following elements.

1. Protected headers (protected) - A set of attributes that provide transport, security, message integrity and summary information about the message being exchanged.
2. JWE element (encrypted_key) - Content Encryption Key.
3. JWE element (iv) - Initialisation Vector for the algorithm.
4. Encrypted Payload (ciphertext) - Payload containing the relevant domain entity (eObject) as prescribed for the use case by the domain specifications. This needs to be encrypted so that HCX cannot read this.
5. Authentication tag (authentication_tag) - Digital signature on the protected header and the payload of the message to ensure its integrity.

The final payload should be serialzed using JWE compact serialization as defined in the RFC-7516 -

protected || '.' || encrypted_key || '.' || iv || '.' || ciphertext || '.' || authentication_tag

Detailed steps on how to construct the JWE token are provided in this section of the HCX specifications.

Response

202400404500

Accepted

Body

application/json

timestamp*string

Unix timestamp when the response is sent.

api_call_id*string (uuid)

That is present in the transport header of the request.

correlation_id*string (uuid)

That is present in the transport header of the request.

Request

JavaScriptCurl

const response = await fetch('/claim/submit', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "payload": "eyJlbmMiOiJBMjU2R0NNIiwKImFsZyI6IlJTQS1PQUVQIiwKIngtaGN4LXNlbmRlcl9jb2RlIjoiMS00ZGMzZTA4OC1hMzEzLTQ0YWItYWZhMS0wMjIyOTU5Y2I3NWIiLAoieC1oY3gtcmVjaXBpZW50X2NvZGUiOiIxLTkzZjkwOGJhLWI1NzktNDUzZS04YjJhLTU2MDIyYWZhZDI3NSIsCiJ4LWhjeC1yZXF1ZXN0X2lkIjoiMjZiMTA2MGMtMWU4My00NjAwLTk2MTItZWEzMWUwY2E1MDkxIiwKIngtaGN4LWNvcnJlbGF0aW9uX2lkIjoiNWU5MzRmOTAtMTExZC00ZjBiLWIwMTYtYzIyZDgyMDY3NGUxIiwKIngtaGN4LXRpbWVzdGFtcCI6IjIwMjEtMTAtMjdUMjA6MzU6NTIuNjM2KzA1MzAiLAoieC1oY3gtc3RhdHVzIjoicmVxdWVzdC5pbml0aWF0ZSIsCiJ4LWhjeC13b3JrZmxvd19pZCI6IjVlOTM0ZjkwLTExMWQtNGYwYi1iMDE2LWMyMmQ4MjA2NzRlMiIsCiJ4LWhjeC1kZWJ1Z19mbGFnIjoiSW5mbyIsCiJ4LWhjeC1lcnJvcl9kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCAidHJhY2UiOiAiIn0sCiJ4LWhjeC1kZWJ1Z19kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCJ0cmFjZSI6IiJ9LAoiandzX2hlYWRlciI6eyJ0eXAiOiJKV1QiLCAiYWxnIjoiUlMyNTYifSwKImp3ZV9oZWFkZXIiOnsiYWxnIjoiUlNBLU9BRVAiLCJlbmMiOiJBMjU2R0NNIn0KfQ==.6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.Mz-VPPyU4RlcuYv1IwIvzw"
    }),
});
const data = await response.json();

Response

{
  "timestamp": "1629057611000",
  "api_call_id": "123e4567-e89b-12d3-a456-426614174000",
  "correlation_id": "123e4567-e89b-12d3-a456-426614174000"
}

• /claim/on_submit (payor->HCX, HCX->provider)

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:

1. The responder shall send a ProtocolResponse object (derived from ProtocolHeader) as the request payload in the following scenarios:

   • if there are any protocol related errors in processing the corresponding Claims 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.
   • if the responder wants to send a redirection instruction to the original sender (see redirection flow in the HCX specifications). The x-hcx-status header value in the ProtocolResponse must be "response.redirect" and the x-hcx-redirect_to header must have a value while sending a redirection instruction.

2. 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.

POST/claim/on_submit

Authorization

bearer_auth

Body

application/json

one of

JWEPayload (object (byte))ProtocolResponse (object)

Response

202400404500

Accepted

Body

application/json

timestamp*string

Unix timestamp when the response is sent.

api_call_id*string (uuid)

That is present in the transport header of the request.

correlation_id*string (uuid)

That is present in the transport header of the request.

Request

JavaScriptCurl

const response = await fetch('/claim/on_submit', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "payload": "eyJlbmMiOiJBMjU2R0NNIiwKImFsZyI6IlJTQS1PQUVQIiwKIngtaGN4LXNlbmRlcl9jb2RlIjoiMS00ZGMzZTA4OC1hMzEzLTQ0YWItYWZhMS0wMjIyOTU5Y2I3NWIiLAoieC1oY3gtcmVjaXBpZW50X2NvZGUiOiIxLTkzZjkwOGJhLWI1NzktNDUzZS04YjJhLTU2MDIyYWZhZDI3NSIsCiJ4LWhjeC1yZXF1ZXN0X2lkIjoiMjZiMTA2MGMtMWU4My00NjAwLTk2MTItZWEzMWUwY2E1MDkxIiwKIngtaGN4LWNvcnJlbGF0aW9uX2lkIjoiNWU5MzRmOTAtMTExZC00ZjBiLWIwMTYtYzIyZDgyMDY3NGUxIiwKIngtaGN4LXRpbWVzdGFtcCI6IjIwMjEtMTAtMjdUMjA6MzU6NTIuNjM2KzA1MzAiLAoieC1oY3gtc3RhdHVzIjoicmVxdWVzdC5pbml0aWF0ZSIsCiJ4LWhjeC13b3JrZmxvd19pZCI6IjVlOTM0ZjkwLTExMWQtNGYwYi1iMDE2LWMyMmQ4MjA2NzRlMiIsCiJ4LWhjeC1kZWJ1Z19mbGFnIjoiSW5mbyIsCiJ4LWhjeC1lcnJvcl9kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCAidHJhY2UiOiAiIn0sCiJ4LWhjeC1kZWJ1Z19kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCJ0cmFjZSI6IiJ9LAoiandzX2hlYWRlciI6eyJ0eXAiOiJKV1QiLCAiYWxnIjoiUlMyNTYifSwKImp3ZV9oZWFkZXIiOnsiYWxnIjoiUlNBLU9BRVAiLCJlbmMiOiJBMjU2R0NNIn0KfQ==.6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.Mz-VPPyU4RlcuYv1IwIvzw"
    }),
});
const data = await response.json();

Response

{
  "timestamp": "1629057611000",
  "api_call_id": "123e4567-e89b-12d3-a456-426614174000",
  "correlation_id": "123e4567-e89b-12d3-a456-426614174000"
}

Communications

Communications API will be used for communications between the payors and providers within the claims cycle.

• /communication/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.

POST/communication/request

Authorization

bearer_auth

Body

application/json

payload*object (string)

The paylod should be a JWE token containing the following elements.

1. Protected headers (protected) - A set of attributes that provide transport, security, message integrity and summary information about the message being exchanged.
2. JWE element (encrypted_key) - Content Encryption Key.
3. JWE element (iv) - Initialisation Vector for the algorithm.
4. Encrypted Payload (ciphertext) - Payload containing the relevant domain entity (eObject) as prescribed for the use case by the domain specifications. This needs to be encrypted so that HCX cannot read this.
5. Authentication tag (authentication_tag) - Digital signature on the protected header and the payload of the message to ensure its integrity.

The final payload should be serialzed using JWE compact serialization as defined in the RFC-7516 -

protected || '.' || encrypted_key || '.' || iv || '.' || ciphertext || '.' || authentication_tag

Detailed steps on how to construct the JWE token are provided in this section of the HCX specifications.

Response

202400404500

Accepted

Body

application/json

timestamp*string

Unix timestamp when the response is sent.

api_call_id*string (uuid)

That is present in the transport header of the request.

correlation_id*string (uuid)

That is present in the transport header of the request.

Request

JavaScriptCurl

const response = await fetch('/communication/request', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "payload": "eyJlbmMiOiJBMjU2R0NNIiwKImFsZyI6IlJTQS1PQUVQIiwKIngtaGN4LXNlbmRlcl9jb2RlIjoiMS00ZGMzZTA4OC1hMzEzLTQ0YWItYWZhMS0wMjIyOTU5Y2I3NWIiLAoieC1oY3gtcmVjaXBpZW50X2NvZGUiOiIxLTkzZjkwOGJhLWI1NzktNDUzZS04YjJhLTU2MDIyYWZhZDI3NSIsCiJ4LWhjeC1yZXF1ZXN0X2lkIjoiMjZiMTA2MGMtMWU4My00NjAwLTk2MTItZWEzMWUwY2E1MDkxIiwKIngtaGN4LWNvcnJlbGF0aW9uX2lkIjoiNWU5MzRmOTAtMTExZC00ZjBiLWIwMTYtYzIyZDgyMDY3NGUxIiwKIngtaGN4LXRpbWVzdGFtcCI6IjIwMjEtMTAtMjdUMjA6MzU6NTIuNjM2KzA1MzAiLAoieC1oY3gtc3RhdHVzIjoicmVxdWVzdC5pbml0aWF0ZSIsCiJ4LWhjeC13b3JrZmxvd19pZCI6IjVlOTM0ZjkwLTExMWQtNGYwYi1iMDE2LWMyMmQ4MjA2NzRlMiIsCiJ4LWhjeC1kZWJ1Z19mbGFnIjoiSW5mbyIsCiJ4LWhjeC1lcnJvcl9kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCAidHJhY2UiOiAiIn0sCiJ4LWhjeC1kZWJ1Z19kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCJ0cmFjZSI6IiJ9LAoiandzX2hlYWRlciI6eyJ0eXAiOiJKV1QiLCAiYWxnIjoiUlMyNTYifSwKImp3ZV9oZWFkZXIiOnsiYWxnIjoiUlNBLU9BRVAiLCJlbmMiOiJBMjU2R0NNIn0KfQ==.6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.Mz-VPPyU4RlcuYv1IwIvzw"
    }),
});
const data = await response.json();

Response

{
  "timestamp": "1629057611000",
  "api_call_id": "123e4567-e89b-12d3-a456-426614174000",
  "correlation_id": "123e4567-e89b-12d3-a456-426614174000"
}

• /communication/on_request

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:

1. The responder shall send a ProtocolResponse object (derived from ProtocolHeader) as the request payload in the following scenarios:

   • if there are any protocol related errors in processing the corresponding CommunicationRequest (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.
   • if the responder wants to send a redirection instruction to the original sender (see redirection flow in the HCX specifications). The x-hcx-status header value in the ProtocolResponse must be "response.redirect" and the x-hcx-redirect_to header must have a value while sending a redirection instruction.

2. 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.

POST/communication/on_request

Authorization

bearer_auth

Body

application/json

one of

JWEPayload (object (byte))ProtocolResponse (object)

Response

202400404500

Accepted

Body

application/json

timestamp*string

Unix timestamp when the response is sent.

api_call_id*string (uuid)

That is present in the transport header of the request.

correlation_id*string (uuid)

That is present in the transport header of the request.

Request

JavaScriptCurl

const response = await fetch('/communication/on_request', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "payload": "eyJlbmMiOiJBMjU2R0NNIiwKImFsZyI6IlJTQS1PQUVQIiwKIngtaGN4LXNlbmRlcl9jb2RlIjoiMS00ZGMzZTA4OC1hMzEzLTQ0YWItYWZhMS0wMjIyOTU5Y2I3NWIiLAoieC1oY3gtcmVjaXBpZW50X2NvZGUiOiIxLTkzZjkwOGJhLWI1NzktNDUzZS04YjJhLTU2MDIyYWZhZDI3NSIsCiJ4LWhjeC1yZXF1ZXN0X2lkIjoiMjZiMTA2MGMtMWU4My00NjAwLTk2MTItZWEzMWUwY2E1MDkxIiwKIngtaGN4LWNvcnJlbGF0aW9uX2lkIjoiNWU5MzRmOTAtMTExZC00ZjBiLWIwMTYtYzIyZDgyMDY3NGUxIiwKIngtaGN4LXRpbWVzdGFtcCI6IjIwMjEtMTAtMjdUMjA6MzU6NTIuNjM2KzA1MzAiLAoieC1oY3gtc3RhdHVzIjoicmVxdWVzdC5pbml0aWF0ZSIsCiJ4LWhjeC13b3JrZmxvd19pZCI6IjVlOTM0ZjkwLTExMWQtNGYwYi1iMDE2LWMyMmQ4MjA2NzRlMiIsCiJ4LWhjeC1kZWJ1Z19mbGFnIjoiSW5mbyIsCiJ4LWhjeC1lcnJvcl9kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCAidHJhY2UiOiAiIn0sCiJ4LWhjeC1kZWJ1Z19kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCJ0cmFjZSI6IiJ9LAoiandzX2hlYWRlciI6eyJ0eXAiOiJKV1QiLCAiYWxnIjoiUlMyNTYifSwKImp3ZV9oZWFkZXIiOnsiYWxnIjoiUlNBLU9BRVAiLCJlbmMiOiJBMjU2R0NNIn0KfQ==.6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.Mz-VPPyU4RlcuYv1IwIvzw"
    }),
});
const data = await response.json();

Response

{
  "timestamp": "1629057611000",
  "api_call_id": "123e4567-e89b-12d3-a456-426614174000",
  "correlation_id": "123e4567-e89b-12d3-a456-426614174000"
}

Payments

• Payment notice and acknowledgement

• /paymentnotice/request (payor>HCX, HCX->provider-)

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.

POST/paymentnotice/request

Authorization

bearer_auth

Body

application/json

payload*object (string)

The paylod should be a JWE token containing the following elements.

1. Protected headers (protected) - A set of attributes that provide transport, security, message integrity and summary information about the message being exchanged.
2. JWE element (encrypted_key) - Content Encryption Key.
3. JWE element (iv) - Initialisation Vector for the algorithm.
4. Encrypted Payload (ciphertext) - Payload containing the relevant domain entity (eObject) as prescribed for the use case by the domain specifications. This needs to be encrypted so that HCX cannot read this.
5. Authentication tag (authentication_tag) - Digital signature on the protected header and the payload of the message to ensure its integrity.

The final payload should be serialzed using JWE compact serialization as defined in the RFC-7516 -

protected || '.' || encrypted_key || '.' || iv || '.' || ciphertext || '.' || authentication_tag

Detailed steps on how to construct the JWE token are provided in this section of the HCX specifications.

Response

202400404500

Accepted

Body

application/json

timestamp*string

Unix timestamp when the response is sent.

api_call_id*string (uuid)

That is present in the transport header of the request.

correlation_id*string (uuid)

That is present in the transport header of the request.

Request

JavaScriptCurl

const response = await fetch('/paymentnotice/request', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "payload": "eyJlbmMiOiJBMjU2R0NNIiwKImFsZyI6IlJTQS1PQUVQIiwKIngtaGN4LXNlbmRlcl9jb2RlIjoiMS00ZGMzZTA4OC1hMzEzLTQ0YWItYWZhMS0wMjIyOTU5Y2I3NWIiLAoieC1oY3gtcmVjaXBpZW50X2NvZGUiOiIxLTkzZjkwOGJhLWI1NzktNDUzZS04YjJhLTU2MDIyYWZhZDI3NSIsCiJ4LWhjeC1yZXF1ZXN0X2lkIjoiMjZiMTA2MGMtMWU4My00NjAwLTk2MTItZWEzMWUwY2E1MDkxIiwKIngtaGN4LWNvcnJlbGF0aW9uX2lkIjoiNWU5MzRmOTAtMTExZC00ZjBiLWIwMTYtYzIyZDgyMDY3NGUxIiwKIngtaGN4LXRpbWVzdGFtcCI6IjIwMjEtMTAtMjdUMjA6MzU6NTIuNjM2KzA1MzAiLAoieC1oY3gtc3RhdHVzIjoicmVxdWVzdC5pbml0aWF0ZSIsCiJ4LWhjeC13b3JrZmxvd19pZCI6IjVlOTM0ZjkwLTExMWQtNGYwYi1iMDE2LWMyMmQ4MjA2NzRlMiIsCiJ4LWhjeC1kZWJ1Z19mbGFnIjoiSW5mbyIsCiJ4LWhjeC1lcnJvcl9kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCAidHJhY2UiOiAiIn0sCiJ4LWhjeC1kZWJ1Z19kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCJ0cmFjZSI6IiJ9LAoiandzX2hlYWRlciI6eyJ0eXAiOiJKV1QiLCAiYWxnIjoiUlMyNTYifSwKImp3ZV9oZWFkZXIiOnsiYWxnIjoiUlNBLU9BRVAiLCJlbmMiOiJBMjU2R0NNIn0KfQ==.6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.Mz-VPPyU4RlcuYv1IwIvzw"
    }),
});
const data = await response.json();

Response

{
  "timestamp": "1629057611000",
  "api_call_id": "123e4567-e89b-12d3-a456-426614174000",
  "correlation_id": "123e4567-e89b-12d3-a456-426614174000"
}

• /paymentnotice/on_request (provider->HCX, HCX->payor)

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:

1. The responder shall send a ProtocolResponse object (derived from ProtocolHeader) as the request payload in the following scenarios:

   • if there are any protocol related errors in processing the corresponding Payment Notice 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.
   • if the responder wants to send a redirection instruction to the original sender (see redirection flow in the HCX specifications). The x-hcx-status header value in the ProtocolResponse must be "response.redirect" and the x-hcx-redirect_to header must have a value while sending a redirection instruction.

2. 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.

POST/paymentnotice/on_request

Authorization

bearer_auth

Body

application/json

one of

JWEPayload (object (byte))ProtocolResponse (object)

Response

202400404500

Accepted

Body

application/json

timestamp*string

Unix timestamp when the response is sent.

api_call_id*string (uuid)

That is present in the transport header of the request.

correlation_id*string (uuid)

That is present in the transport header of the request.

Request

JavaScriptCurl

const response = await fetch('/paymentnotice/on_request', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "payload": "eyJlbmMiOiJBMjU2R0NNIiwKImFsZyI6IlJTQS1PQUVQIiwKIngtaGN4LXNlbmRlcl9jb2RlIjoiMS00ZGMzZTA4OC1hMzEzLTQ0YWItYWZhMS0wMjIyOTU5Y2I3NWIiLAoieC1oY3gtcmVjaXBpZW50X2NvZGUiOiIxLTkzZjkwOGJhLWI1NzktNDUzZS04YjJhLTU2MDIyYWZhZDI3NSIsCiJ4LWhjeC1yZXF1ZXN0X2lkIjoiMjZiMTA2MGMtMWU4My00NjAwLTk2MTItZWEzMWUwY2E1MDkxIiwKIngtaGN4LWNvcnJlbGF0aW9uX2lkIjoiNWU5MzRmOTAtMTExZC00ZjBiLWIwMTYtYzIyZDgyMDY3NGUxIiwKIngtaGN4LXRpbWVzdGFtcCI6IjIwMjEtMTAtMjdUMjA6MzU6NTIuNjM2KzA1MzAiLAoieC1oY3gtc3RhdHVzIjoicmVxdWVzdC5pbml0aWF0ZSIsCiJ4LWhjeC13b3JrZmxvd19pZCI6IjVlOTM0ZjkwLTExMWQtNGYwYi1iMDE2LWMyMmQ4MjA2NzRlMiIsCiJ4LWhjeC1kZWJ1Z19mbGFnIjoiSW5mbyIsCiJ4LWhjeC1lcnJvcl9kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCAidHJhY2UiOiAiIn0sCiJ4LWhjeC1kZWJ1Z19kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCJ0cmFjZSI6IiJ9LAoiandzX2hlYWRlciI6eyJ0eXAiOiJKV1QiLCAiYWxnIjoiUlMyNTYifSwKImp3ZV9oZWFkZXIiOnsiYWxnIjoiUlNBLU9BRVAiLCJlbmMiOiJBMjU2R0NNIn0KfQ==.6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.Mz-VPPyU4RlcuYv1IwIvzw"
    }),
});
const data = await response.json();

Response

{
  "timestamp": "1629057611000",
  "api_call_id": "123e4567-e89b-12d3-a456-426614174000",
  "correlation_id": "123e4567-e89b-12d3-a456-426614174000"
}

Operational APIs

• 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

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

• Task.code specifies the nature of the check, and
• Task.focus specifies the context identifiers (e.g case-id for a registered pre-auth, claim id of the provider TMS).
• Task.input carries additional information about the context, e.g: type of entity - preauthorization, claim, etc.

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:

• request.queued - This status means that HCX gateway has not yet forwarded the original request (for which the status is being requeested for) to the intended recipient. The request is still under processing by the HCX gateway. In this scenario, there shall not be a status response via the call back API /hcx/on_status to the caller.
• request.dispatched - This means that HCX gateway has dispatched the original request to the intended recipient and thus, HCX gateway will forward the status request to the same recipient. And the recipient shall respond with status details via the call back API /hcx/on_status to the caller.

POST/hcx/status

Authorization

bearer_auth

Body

application/json

payload*object (string)

The paylod should be a JWE token containing the following elements.

1. Protected headers (protected) - A set of attributes that provide transport, security, message integrity and summary information about the message being exchanged.
2. JWE element (encrypted_key) - Content Encryption Key.
3. JWE element (iv) - Initialisation Vector for the algorithm.
4. Encrypted Payload (ciphertext) - Payload containing the relevant domain entity (eObject) as prescribed for the use case by the domain specifications. This needs to be encrypted so that HCX cannot read this.
5. Authentication tag (authentication_tag) - Digital signature on the protected header and the payload of the message to ensure its integrity.

The final payload should be serialzed using JWE compact serialization as defined in the RFC-7516 -

protected || '.' || encrypted_key || '.' || iv || '.' || ciphertext || '.' || authentication_tag

Detailed steps on how to construct the JWE token are provided in this section of the HCX specifications.

Response

202400404500

Accepted

Body

application/json

timestamp*string

Unix timestamp when the response is sent.

api_call_id*string (uuid)

That is present in the transport header of the request.

correlation_id*string (uuid)

That is present in the transport header of the request.

resultStatusResponseObject (object)

Request

JavaScriptCurl

const response = await fetch('/hcx/status', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "payload": "eyJlbmMiOiJBMjU2R0NNIiwKImFsZyI6IlJTQS1PQUVQIiwKIngtaGN4LXNlbmRlcl9jb2RlIjoiMS00ZGMzZTA4OC1hMzEzLTQ0YWItYWZhMS0wMjIyOTU5Y2I3NWIiLAoieC1oY3gtcmVjaXBpZW50X2NvZGUiOiIxLTkzZjkwOGJhLWI1NzktNDUzZS04YjJhLTU2MDIyYWZhZDI3NSIsCiJ4LWhjeC1yZXF1ZXN0X2lkIjoiMjZiMTA2MGMtMWU4My00NjAwLTk2MTItZWEzMWUwY2E1MDkxIiwKIngtaGN4LWNvcnJlbGF0aW9uX2lkIjoiNWU5MzRmOTAtMTExZC00ZjBiLWIwMTYtYzIyZDgyMDY3NGUxIiwKIngtaGN4LXRpbWVzdGFtcCI6IjIwMjEtMTAtMjdUMjA6MzU6NTIuNjM2KzA1MzAiLAoieC1oY3gtc3RhdHVzIjoicmVxdWVzdC5pbml0aWF0ZSIsCiJ4LWhjeC13b3JrZmxvd19pZCI6IjVlOTM0ZjkwLTExMWQtNGYwYi1iMDE2LWMyMmQ4MjA2NzRlMiIsCiJ4LWhjeC1kZWJ1Z19mbGFnIjoiSW5mbyIsCiJ4LWhjeC1lcnJvcl9kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCAidHJhY2UiOiAiIn0sCiJ4LWhjeC1kZWJ1Z19kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCJ0cmFjZSI6IiJ9LAoiandzX2hlYWRlciI6eyJ0eXAiOiJKV1QiLCAiYWxnIjoiUlMyNTYifSwKImp3ZV9oZWFkZXIiOnsiYWxnIjoiUlNBLU9BRVAiLCJlbmMiOiJBMjU2R0NNIn0KfQ==.6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.Mz-VPPyU4RlcuYv1IwIvzw"
    }),
});
const data = await response.json();

Response

{
  "timestamp": "1629057611000",
  "api_call_id": "123e4567-e89b-12d3-a456-426614174000",
  "correlation_id": "123e4567-e89b-12d3-a456-426614174000",
  "result": {
    "sender_code": "text",
    "recipient_code": "text",
    "entity_type": "coverageeligibility",
    "protocol_status": "request.queued"
  }
}

• /hcx/on_status

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:

1. The responder shall send a ProtocolResponse object (derived from ProtocolHeader) as the request payload in the following scenarios:

   • if there are any protocol related errors in processing the corresponding Status 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.
   • if the responder wants to send a redirection instruction to the original sender (see redirection flow in the HCX specifications). The x-hcx-status header value in the ProtocolResponse must be "response.redirect" and the x-hcx-redirect_to header must have a value while sending a redirection instruction.

2. 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.   

POST/hcx/on_status

Authorization

bearer_auth

Body

application/json

one of

JWEPayload (object (byte))ProtocolResponse (object)

Response

202400404500

Accepted

Body

application/json

timestamp*string

Unix timestamp when the response is sent.

api_call_id*string (uuid)

That is present in the transport header of the request.

correlation_id*string (uuid)

That is present in the transport header of the request.

Request

JavaScriptCurl

const response = await fetch('/hcx/on_status', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "payload": "eyJlbmMiOiJBMjU2R0NNIiwKImFsZyI6IlJTQS1PQUVQIiwKIngtaGN4LXNlbmRlcl9jb2RlIjoiMS00ZGMzZTA4OC1hMzEzLTQ0YWItYWZhMS0wMjIyOTU5Y2I3NWIiLAoieC1oY3gtcmVjaXBpZW50X2NvZGUiOiIxLTkzZjkwOGJhLWI1NzktNDUzZS04YjJhLTU2MDIyYWZhZDI3NSIsCiJ4LWhjeC1yZXF1ZXN0X2lkIjoiMjZiMTA2MGMtMWU4My00NjAwLTk2MTItZWEzMWUwY2E1MDkxIiwKIngtaGN4LWNvcnJlbGF0aW9uX2lkIjoiNWU5MzRmOTAtMTExZC00ZjBiLWIwMTYtYzIyZDgyMDY3NGUxIiwKIngtaGN4LXRpbWVzdGFtcCI6IjIwMjEtMTAtMjdUMjA6MzU6NTIuNjM2KzA1MzAiLAoieC1oY3gtc3RhdHVzIjoicmVxdWVzdC5pbml0aWF0ZSIsCiJ4LWhjeC13b3JrZmxvd19pZCI6IjVlOTM0ZjkwLTExMWQtNGYwYi1iMDE2LWMyMmQ4MjA2NzRlMiIsCiJ4LWhjeC1kZWJ1Z19mbGFnIjoiSW5mbyIsCiJ4LWhjeC1lcnJvcl9kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCAidHJhY2UiOiAiIn0sCiJ4LWhjeC1kZWJ1Z19kZXRhaWxzIjp7ImVycm9yLmNvZGUiOiAiYmFkLmlucHV0IiwgImVycm9yLm1lc3NhZ2UiOiAiUHJvdmlkZXIgY29kZSBub3QgZm91bmQiLCJ0cmFjZSI6IiJ9LAoiandzX2hlYWRlciI6eyJ0eXAiOiJKV1QiLCAiYWxnIjoiUlMyNTYifSwKImp3ZV9oZWFkZXIiOnsiYWxnIjoiUlNBLU9BRVAiLCJlbmMiOiJBMjU2R0NNIn0KfQ==.6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.Mz-VPPyU4RlcuYv1IwIvzw"
    }),
});
const data = await response.json();

Response

{
  "timestamp": "1629057611000",
  "api_call_id": "123e4567-e89b-12d3-a456-426614174000",
  "correlation_id": "123e4567-e89b-12d3-a456-426614174000"
}

Following OpenAPI 3.0 specification details these APIs in detail.: Search API is for regulators/observers to fetch the details of claims for reconciliation and maybe for grievance redressal (in future). For example, NHA can request for all claims processed by all payors in the last one week. The response to the search request will be via the callback API (/hcx/on_search) containing a list of encrypted FHIR objects matching the search criteria.