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