Eligibility Checks

Introduction

Claims Eligibility Check is a REST based API exposed by Claims to check the eligibility of a member within the context of the requesting provider. The service supports three operations, which together form the eligibility check conversation an external client can enter in with Claims.

These operations are:

  1. POST operation to initiate an eligibility check.
    Once the request has been received, the eligibility check resource is created and a HTTP 201 (Created), along with a Location header is sent back. The location header points to a status resource. Once the eligibility check resource has been created successfully, internally the execution of a process is started to have the eligibility check run through a series of configured steps.

  2. GET operation on the aforementioned status resource allowing a client to check - in a polling fashion - about the status of the process that has been started for the eligibility check. The information provided in the status resource allows the client to 'know' when it can call upon the last step of the conversation, which is mentioned in #3 below.

  3. GET operation on the eligibility check resource, which can/is to be called once the information in the status resource indicates that the process of performing the eligibility check has been completed successfully. The representation of this particularly resource is largely driven by a piece of dynamic logic, that typically leverages the outcome of the eligibility check process.

  4. It is also possible to update cancellationDate field along with the dynamic fields or records with a PUT operation and a HTTP 200 (Updated), is sent back.

Claims Eligibility Check

The path where this service is available will be:

http://[hostName]:[portNumber]/[api-context-root]/eligibilitychecks

The service will expose a POST method. An optional responseDefinitionCode can be passed as a request parameter to specify which process steps are to be executed to perform the eligibility check. In case no request parameter is given, the system will use the default response definition that has been configured. In case the response definition given does not exist in the system or no default is defined when it is left out - a HTTP 400 (Bad Request) will follow.

The contract for the service is as follows:

Table 1. Request Structure: EligibilityCheck
Id Attributes Type Required

1

person attributes that identifies the person

Person

Yes

2

provider attributes that identifies the provider

Provider

No

3

requestDate ;

Date

Yes

4

Dynamic field and/or dynamic record attributes

Depends on dynamic field/record definition

No

3

cancellationDate ;

Date

No

Sample Structure:

  { "person" : {
       "SSN" : "8236-73538-11"
    },
    "provider" : {
       "flexCodeDefinitionCode" : "OHI",
       "code" : "PROV723630"
    },
    "requestDate" : "2017-01-01",
    "product" : "DENTAL",
    "countryOfBirth": "India"
  }

In the example above:

  1. The person is identified by it’s SSN (Social Security Number). A dynamic field with usage name SSN is setup on the person.

  2. The provider is identified by the Oracle Health Insurance provider code

  3. Two dynamic fields are setup on the eligibility check with usage names product and countryOfBirth

Eligibility Status Resource

As was described in the introduction - as a result of the initiating POST operation an eligibility check will be created. As a result of this POST a HTTP 201 (Created) status is sent back along with a location header. This location header will look like this:

http://[hostName]:[portNumber]/[api-context-root]/eligibilitychecks/{id}/status

The intent is that the client that performed the initial POST, uses this location header to check the status by performing a HTTP GET operation on it. This can have three possible outcomes, which a client should use to determine 'what to do next'.

Possible Outcome #1 - the Eligibility Check is Still Processing

  { "progress" : "processing",
    "completed" : false,
    "links" : [
       {
         "href" : "http://[hostName]:[portNumber]/[api-context-root]}/eligibilitychecks/{id}/status",
         "rel" : "self"
       }
    ]
  }

Possible Outcome #2 - There was a Unexpected Exception in Processing the Eligibility Check

  { "progress" : "failed",
    "completed" : true,
    "errorDetail" : "... information about the technical error that occurred ... ",
    "links" : [
       {
         "href" : "http://[hostName]:[portNumber]/[api-context-root]/eligibilitychecks/{id}/status",
         "rel" : "self"
       }
    ]
  }

Possible Outcome #3 - the Eligibility Check Completes

  { "progress" : "succeeded",
    "completed" : true,
    "links" : [
       {
         "href" : "http://[hostName]:[portNumber]/[api-context-root]/eligibilitychecks/{id}/status",
         "rel" : "self"
       },
       { "href" : "http://[hostName]:[portNumber]/[api-context-root]/eligibilitychecks/{id},
         "rel" : "related"
       }
    ]
  }

In possible outcome #3 a situation where the eligibility check has been processed successfully. As a result of that there is a related link available in the response message. This essentially will hold the response structure for the completed eligibility check, which will be described in the next paragraph.

Response Structure

The return type of the service will be a structure returned by the dynamic logic function defined on the eligibility response definition. It can be a XML/JSON or a plain string depending upon the dynamic logic construction. ;

Eligibility Check Logic

Flow Description

A high level representation of the Eligibility Check consists of the following steps.

  • Determine the response definition code that needs to be used, processing the incoming eligibility check.

    • If the given response definition code (specified as a query parameter - e.g. ?responseDefinitionCode=DENTAL_A) does not exist or - in case no response definition code has been provided and there is no default configured a HTTP 400 (Bad Request) will be returned and no further action will follow.

  • Create the eligibility check resource - which is the representation of the incoming payload submitted over HTTP POST.

    • Information provided in the payload that specifies details of a person (mandatory) and provider (optional) are used to lookup the respective entities in Claims in order to store references thereof in the eligibility check resource. Other information in the payload (e.g. requestDate (mandatory), further dynamic fields and/or records) are stored on the eligibility check accordingly. Note that for dynamic fields/records storage, proper configuration thereof needs to be present in Claims. Certain structural validations will be an integral part of this step - e.g. checking whether required information is present. In case these result in functional errors, eligibility check messages will be created for them and added to the eligibility check. It is important to point out that typically functional errors in this preliminary resource creation phase, won’t result in rejecting the incoming payload.

    • The person is identified by either the person code or by an identifying single-value non-time-valid dynamic field on the person record, like a social security number or a passport number. If no person match can be made, error message CLA-IP-ELCH-001 will be attached to the eligibility check. If more than 1 person could be matched, error message CLA-IP-ELCH-002 will be attached to the eligibility check.

    • The provider can be identified by the provider code or by any other identifying single-value non-time-valid dynamic field on the provider record. If no provider match can be made, error message CLA-IP-ELCH-003 will be attached to the eligibility check. If more than 1 provider could be matched, error message CLA-IP-ELCH-004 will be attached to the eligibility check.

    • In case there is no person information specified in the incoming payload and/or when there is no requestDate specified as part of the payload, error message CLA-IP-ELCH-005 will be attached to the eligibility check.

    • There will be a code generated for the eligibility check. The format of this code is a 14 digits character field with leading zeros.

    • At this point the eligibility check status is going to be set - which essentially is an indication of what will be done next:

      • Denied- will be set if one or more of the aforementioned errors have been raised. Subsequently the dynamic logic that was setup as part of the response definition to construct the output of the eligibility check is called.

      • Error - will be set when a technical/unexpected error occurs during the aforementioned steps. In this case no dynamic logic will be called to construct output logic, as there is no meaningful response data. Rather in this case the fact that a technical/unexpected error occurred will be represented in the eligibility status resource.

      • In Progress- will be set when the initial resource creation including reference mapping is performed successfully. With this status the eligibility check becomes eligible for the execution of configured process steps.

    • After this an HTTP 201 (Created) response will be returned from the initiating HTTP POST operation. At this point the client - that initiated the request and the server, that is responsible for processing the eligibility check become 'detached'. Put differently the actual processing of steps and rules happens asynchronously and autonomously from the client. The client typically polls the eligibility status resource to check on progress.

  • When the process steps are completed, the system checks for any fatal messages. When fatal messages exist, the status is set to Denied. When no fatal messages exist the status is set to Approved. The response is generated based on the response definition dynamic logic and stored on the eligibility check.

It is possible to store a time period for which the eligibility is valid on the eligibility check using the valid from and valid to date attributes. These attributes are not populated by fixed logic but values can be assigned to them in the dynamic logic functions in callout, validation rules and in the response logic.

Evaluate Process Steps

The processing of an eligibility check involves sequential execution of user configured 'process steps'. Each of these steps can include a number of related and interdependent configurable business rules that are executed in a user defined order. The configuration of process steps is described in more detail in Eligibility Response Definition

The system first determines the sequence of the process steps and then starts evaluating the process steps one by one. Process steps are further subdivided into a number of rule steps. Each rule step consists of a single user configured rule. ;

This process supports two different types of user configured business rules:

  • Callout rules. This type of rule calls out to an external service. The response can then result in additional information that is added to the eligibility check.

  • Validation rules. This type of rule applies conditions and typically results in messages attached to the eligibility check.

With respect to setting up process steps and rule steps, it is typically the most efficient to execute simple validation first. For example if it is applicable that the incoming Eligibility Check data, needs to be checked for some specific information being present which does not require querying Claims - these types of rules should be executed first.

The evaluation of the different process rules is described in the sections below.

Process Step and Fatal Message

Rule Steps

During processing of a process step - the callout and validation rules are evaluated, based on the configured execution order (sequence). A rule step is not evaluated when the indicator enabled on the rule is set to 'No'.

The execution of a rule must be completed successfully (i.e. without a technical error) before the next rule (this can be a callout rule or a validation rule) is executed. If a technical error occurs in a rule step, the status of the Eligibility Check is set to Error and the eligibility check stops.

Callout Rule

When an eligibility check reaches a step in the processing for which a callout rule has been defined, the condition dynamic logic on the callout rule is evaluated to determine if the rule is applicable; if the condition evaluates to true, the callout rule is executed. The execution of a callout rule consists of sending a request message and receiving a response message. The request and response message and the processing logic for the response message of a callout rule are configurable and is done through one dynamic logic function.

Performing the Callout

The dynamic logic function of the callout rule is responsible for creating a request message. The logic then sends the created request message to the external system’s endpoint. The end point is configurable per callout rule.

The external system is required to return its response message immediately. Upon receiving the response message from the external system the same dynamic logic processes it.

Note that REST based sync callouts are supported by the callout rules.

Validation Rule

The validation rule facilitates the business to perform specific checks on the data elements of the eligibility check. Together with call out rules, validation rules form the central processing concept for eligibility checks. Typically, a call out rule will fetch information from another component on e.g enrollment information. This information will then come back to Claims and be stored there so that it can be used in a validation rule.

When the dynamic logic condition on the validation rule evaluates to true, the specified message is attached to the eligibility check and the system also executes the dynamic logic function defined on the rule.

Process Completion

When the process steps are completed, the process checks if there are any fatal messages attached to the eligibility check. If there are fatal messages, the status of the eligibility check is set of Denied. In case there are no fatal messages, the status of the eligibility check is set to Approved. The response definition dynamic logic is executed to generate the response of the eligibility check. This response is stored on the eligibility check. If the response definition dynamic logic results in a technical error, the status of the eligibility check is set to Error.

Updating Dynamic Fields or Records

A PUT operation updates the dynamic fields and records. The URL of the PUT gets known only once the POST responds back with a header that contains the {id}. This service is available on the following path:

http://[hostName]:[portNumber]/[api-context-root]/eligibilitychecks/{id}

The following is an example payload structure:

  {
    "cancellationDate" : "2017-04-01",
    "product" : "DENTAL",
    "countryOfBirth": "India"
  }
In the request, only dynamic fields should be sent in, if any other attributes are sent they get ignored.

Response Messages

A HTTP 200 (updated) is returned once the update gets completed.

Error Messages

Table 2. Error Messages
Error Message

CLA-IP-ELCH-001

Person not found for the criteria provided

CLA-IP-ELCH-002

More than one person found with the criteria provided

CLA-IP-ELCH-003

Provider not found for the criteria provided

CLA-IP-ELCH-004

More than one provider found with the criteria provided

CLA-IP-ELCH-005

One or more mandatory attributes are missing from the eligibility request

CLA-IP-ELCH-006

A PUT operation cannot be called for an eligibility check during the processing (which is in 'InProcess' status).