Product Service Consumption Integration Point

The primary use of this integration point is to provide an overview of the maximum heights and consumptions defined for a person for a specific service option (e.g Physiotherapy) on a specific date.

Typical use of this integration point is from a member portal where the member searches by service option and date. The service option for the member’s product may be included in a combination limit along with other service options.

This integration point works only in combination with the person covered services functionality.

Request

The HTTP POST request to: http://[hostName]:[portNumber]/[api-context-root]/productserviceconsumptions enables external systems to read the status of consumptions on limits for a person’s service option.

This integration point exposes a POST method. The payload for this request contains the selection criteria for the product service consumptions. A few selection criteria are embedded in the request:

• person code

• service option service code

• search date

• product history table

All selection criteria are required.

The request message has the following structure:

{
   "personCode" : "",
   "serviceOptionServiceCode" : "",
   "searchDate" : "",
   "productHistoryList" : [
      {
        "productCode" : "",
        "serviceOptionServiceCode" : "",
        "startDate" : "",
        "endDate" : "",
        "parameterAliasList" : [
        {
           "parameterAliasCode" : "",
           "startDate" : "",
           "endDate" : "",
           "maximumNumber" : "",
           "maximumAmount" : "",
           "amountCurrency" : ""
         }
         ...
        ]
      }
      ...
      ]
}

To reduce the payload of the request, limit the product history table to products with the service option in the request

Response

For a given combination of person, service option service code and search date, this operation retrieves all limits with reached action 'Stop', for the product valid on the search date.

The limit maximum values can be defined in the product history table from the request input and as part of the product benefit specification. If the maximum value is defined in the product history table, this value overrides the value that would be retrieved from the product configuration.

The output of the request is a list of limit maximum values and consumptions for a service option.

The response has the following elements:

Product

The product the person is enrolled for on the search date.

Limit Product

The product for which the maximum limit values are returned. This can be different from the enrolled product when a waiting period applies.

Service Option

The service option service code of the limit or sublimit. If the total consumption for a combination limit exceeds the total consumption for the related sublimits, this field shows 'Unspecified'.

Limit Alias

The alias code for the (sub)limit.

Limit Display Name

The display name for the (sub)limit.

Limit Maximum

The limit height. If a value is specified in the product history table from the request input, this value overrides the product benefit specification maximum value.

Consumption

The total consumption logged for the (sub)limit in the counter period that includes the reference date. This includes external consumption, even when no claim has been processed for that particular counter period. If the service option is 'Unspecified', this field shows the difference between the combination limit consumption and the total consumption of all related sublimits.

Waiting Period

Displays the waiting period status of the current product. Possible values are:

• N/A: No waiting period is defined on benefit specification

• Served: A waiting period is defined and the search date is beyond the waiting period

• Not Served: A waiting period is defined and the search date is in the waiting period

• Waived: A waiting period is defined and the search date is in the waiting period, but the person product service indicates a waiver for this person’s product service.

Waiver Reason

If the waiting period has the status waived, the response includes the waiver reason.

End Waiting Period

If the waiting period of the current product is not served, the response includes the date on which the waiting period ends.

Response Payload

The output request massage has the following structure:

{
   "productCode" : "",
   "limitProductCode" : "",
   "serviceOptionServiceCode" : "",
   "currentProductWaitingPeriod" : "",
   "currentProductWaiverReason" : "",
   "currentProductWaitingPeriodEndDate" : "",
   "limitList" : [ {
            "aliasCode" : "",
            "displayName" : "",
            "maximumNumber" : "",
            "maximumAmount" : "",
            "amountCurrency" : '',
            "consumedNumber" : "",
            "consumedAmount" : "",
            "consumedCurrency" : '',
            "sublimitList : [ {
                 "sublimitDisplayName" : "",
                 "serviceOptionServiceCode" : "",
                 "consumedNumber" : ""
                 "consumedAmount" : "",
                 "consumedCurrency" : '',
             }
             ...
           ]
         }
       ....
      ]
}

Waiting Periods

The integration point evaluates whether there are waiting periods to be considered. If there is no waiting period defined on the benefit specification, no waiting period is evaluated.

If there is a waiting period defined on the benefit specification, the waiting period start date from the Person Covered Services is compared to the search date. If the waiting period is served, the maximum values for the current product are used in the request output. If the Person Product Service indicates that a waiver applies to the waiting period, no waiting period applies.

If the waiting period is not served, the system retrieves the preceding product, based from the product history in the request. The system then attempts to retrieve the limit maxima from that product. If the preceding product’s wait period is also not served, the system tries again with the product before that. This pattern repeats until the system either retrieves the applicable limit maxima, or when none of the prior products have applicable limit maxima.

Example

In this example, the request is for service option Physiotherapy. The waiting period for the benefit specification of physiotherapy is 2 months.

The person product services for the person are defined as follows:

Product	Service Option	Start Date	End Date	Start Waiting Period
GOLD	Physiotherapy	1-Jul-2020		1-Jul-2020
SILVER	Physiotherapy	1-Jan-2020	30-Jun-2020	1-Jan-2020
BRONZE	Physiotherapy	1-Jan-2019	31-Dec-2019	1-Jan-2019

Request Date 1-Aug-2020

The waiting period is not served because the request date of 1-Aug-2020 is within the 2 months waiting period starting 1-Jul-2020. This means that the limit heights for product SILVER are returned in the request output.

Request Date 1-Nov-2020

In this case, the waiting period of 2 months is served, so the limit heights for product GOLD are returned in the request output.

Combination Limits

Combination limits are limits that have a total maximum value that applies to the combination of sublimits defined under the combination limit. The combination limit is defined as a 'stop' limit where the sublimits are defined as 'continue' limits. All sublimits of the combination limits are included in the response. The sublimits can be related to different service options, but as they are related to the same combination limit, they are reported in the output.

The result of the search for combination limits is:

• All service options that share the same combination limit with the search service option

• The limit max of the combination limit as applicable on the search date

• The total consumption of the combination limit for the counter period based on search date

• Consumption by service option for the counter period based on search date (each service option has a continue limit to count consumption per service option).

• An additional service option 'Unspecified' may be returned in case the total consumption for the combination limit exceeds the total consumption of the service options in the combination limit.

Example

From the product benefit specification configuration, the following limits and sublimits are defined for service option Physiotherapy. Physiotherapy shares a limit with chiropractic and osteopathy.

Although the request is for physiotherapy, the consumptions for chiropractic and osteopathy are also reported in the response because they share a limit with physiotherapy.

Service Option	Limit	Sub Limit	Reached Action	Max Amount
Physiotherapy	P_Flex		Stop	USD 700,00
Physiotherapy		L_Physio	Continue	USD 300,00
Chiropractic		L_Chiro	Continue	USD 300,00
Osteopathy		L_Osteo	Continue	USD 300,00

Consumption

The request output returns the total consumption per limit. This includes combination limits and sublimits. The consumption is captured from the limit counter period valid on the search date.

Response Messages

This service can respond with the following messages:

Code	Message
CLA-IP-PSCO-001	The request has to include a person code
CLA-IP-PSCO-002	The request has to include a service option service code
CLA-IP-PSCO-003	The request has to include a search date
CLA-IP-PSCO-004	The request has to include a product history table
CLA-IP-PSCO-005	Person {code} is unknown
CLA-IP-PSCO-007	No service option service code found on the product history element
CLA-IP-PSCO-008	Could not determine a product on search date

Authorization

This operation is protected by the access restriction "productServiceConsumption IP".