ClearLife Price Estimator API
Overview
The API can be used to estimate a range of values for a policy based on minimal policy information and pricing parameters. A premium schedule is not required, so the estimate can be generated without the details typically required for LS pricing. Access to the API is controlled via access to ClariNet (demo accounts are available on request).
API Specification
For general API specification details see Authentication, API Keys and General Notes.
Endpoint
POST https://www.clarinetdemo.com/api/latest/policyEstimator
Authentication
API users will need an account on ClariNet. As detailed in the API specification, an access token is required which can be generated from your user account.
Request
The body of the POST should be a JSON object, described in more detail below.
- The Content-Type header should be set to application/json.
- For optional fields:
- You can either specify null as their value or omit them entirely.
- Optional fields that are missing or set to null will have a default value set by ClariNet LS. Some of these defaults can be set via the Admin menu using the ClariNet LS website.
Request Parameters
- A list of Policy objects.
- Policy Estimator Parameters
Policy
| Field | Type | Required | Valid Values | Default if not specified |
|---|---|---|---|---|
| Id | String | Yes | Anything | n/a |
| PolicyType | String | Yes | {“UniversalLife”, “WholeLife”, “TermLife”} | n/a |
| AgeToday | Integer | Yes | {18…120} | n/a |
| IssueAge | Integer | Yes | {18…120} | n/a |
| DeductionEndAge | Integer | No | {18…149} | See AssumedDeductionEndAge |
| CoverageEndAge | Integer | No | {18…149} | See AssumedCoverageEndAge |
| Gender | String | Yes | {“M”, “F”} | n/a |
| SmokingStatus | String | Yes | {“Smoker”, “NonSmoker”, “Aggregate”} | n/a |
| FaceAmount | Float | Yes | Anything | n/a |
| CashValue | Float | No | Anything | 0 |
| TotalPremiums | Float | No | Anything | 0 |
| AnnualPremium | Float | No | Anything | 0 |
| HealthRatingAtIssue | String | No | {“MuchWorse”, “Worse”, “Average”, “Better”, “MuchBetter”} | Average |
| HealthRatingNow | String | No | {“MuchWorse”, “Worse”, “Average”, “Better”, “MuchBetter”} | Average |
| PolicyRating | String | No | {“Standard”, “StandardPlus”, “Preferred”, “PreferredPlus”, “TableRated”, “Unknown”} | Standard |
| Popc | Float | No | Anything | 0 |
| FixedLoadPerMonth | Float | No | Anything | 0 |
| PerUnitPerMonth | Float | No | Anything | 0 |
Many of the parameters are self-explanatory, however, the following are defined here:
- CashValue: the policy cash value. Used to reduce the projected premiums on the policy. For an AV lapse policy this would be Account Value, for a CSV lapse, it would be Cash Surrender Value.
- TotalPremiums: the total premiums paid to date on the policy. Currently not used.
- AnnualPremium: the current annual premium on the policy. Currently not used.
- HealthRatingAtIssue: an indication of the insured health status at policy issue. This is used to index into the PremiumAdjustmentRates specified in the estimator parameters to project premiums.
- HealthRatingNow: an indication of the insured health status today. This is used to index into the MortalityAdjustmentRates specified in the estimator parameters which calculate a mortality curve from the mortality table.
- PolicyRating: this specifies the carrier policy rating at issue.
Policy Estimator Parameters
| Field | Type | Required | Valid Values | Default if not specified |
|---|---|---|---|---|
| CarrierProfitLoad | Float | No | Anything | 0 |
| AssumedDeductionEndAge | Integer | Yes | {18…120} | n/a |
| AssumedCoverageEndAge | Integer | Yes | {18…120} | n/a |
| MortalityTable | String | Yes | * | n/a |
| MortalityTableAgeBasis | String | Yes | {"ALB", "ANB"} | n/a |
| ImprovementMNS | Float | No | Anything | 0 |
| ImprovementMS | Float | No | Anything | 0 |
| ImprovementFNS | Float | No | Anything | 0 |
| ImprovementFS | Float | No | Anything | 0 |
| ValueDate | Date | Yes | "YYYY-MM-DD" (e.g. “2022-05-24” ) | n/a |
| DiscountRate | Float | Yes | Anything | n/a |
| UseCOIModifier | String | Yes | {“True”, “False”} | n/a |
| CoiRatioYear | List<Integer> | No | Anything | * |
| CoiRatio | List<Integer> | No | Anything | * |
| PremiumAdjustmentRates | List<Float> | Yes | Anything | |
| MortalityAdjustmentRates | List<Float> | Yes | Anything | |
| PolicyRatingToHealthRatingMapping | List<String> | Yes | [{“MuchWorse”, “Worse”, “Average”, “Better”, “MuchBetter”, “Average”}] |
- CarrierProfitLoad: Premiums will be adjusted upwards based on the carrier profit load. Without this load, the premiums are calculated in order for the carrier to break even based on mortality.
- AssumedDeductionEndAge/AssumedCoverageEndAge: Specifies default values for policies where no value is specified.
- MortalityTable: Both ClariNet LS inbuilt mortality tables and user specified mortality tables are supported. Inbuilt tables include “2001 VBT”, “2008 VBT”, “2015 VBT”. Many others are available.
- MortalityTableAgeBasis: Valid values are “ALB”, “ANB”. String, required
- ImprovementMNS: Any value is valid. Float, optional, default is 0
- ImprovementMS: Any value is valid. Float, optional, default is 0
- ImprovementFNS: Any value is valid. Float, optional, default is 0
- ImprovementFS: Any value is valid. Float, optional, default is 0
- ValueDate: Valid values must be in date format “YYYY-MM-DD” (e.g. “2022-05-24”). Date, required
- DiscountRate: Any value is valid. Float, required, default is 0
- UseCOIModifier: The qx from the mortality table can be adjusted using a vector of COI modifiers. If this value is true, the following two parameters must be specified.
- CoiRatioYear, CoiRatio: With these two parameters, the qx value from the mortality table is multiplied by the COI ratio.
- PremiumAdjustmentRates: This contains a vector of factors that are applied to the premiums for each health rating. There must be 5 values in the vector.
- MortalityAdjustmentRates: This contains a vector of factors that are applied to the mortality rates for each health rating. There must be 5 values in the vector.
- PolicyRatingToHealthRatingMapping: This vector contains the health rating that will be used for each policy type. For example, specifying
[{“Average”, “Average”, “Average”, “Average”, “Average” , “Average”}]means that{“Standard”, “StandardPlus”, “Preferred”, “PreferredPlus”, “TableRated”, “Unknown”}would all be mapped to average health rating at issue.
Results
A list of Priced Policies. Each one contains:
- Id the input identifier of the policy
- NPVTotalCon
- NPVTotalNormal
- NPVTotalAgg
- NPVPremiumCon
- NPVPremiumNormal
- NPVPremiumAgg
- NPVdbCon
- NPVdbNormal
- NPVdbAgg
There are 3 types of valuation: Conservative (Con), Aggressive (Agg) and Normal (Normal). These correspond to the heath ratings at issue and today for each policy with notches higher and lower applied to both ratings. For each valuation we show the NPV for Death Benefit, Premium and the total.
Example Requests
Minimum Request
json
{
"Policies": [
{
"Id": "1",
"PolicyType": "UniversalLife",
"AgeToday": 81,
"IssueAge": 75,
"Gender": "F",
"SmokingStatus": "NonSmoker",
"FaceAmount": 3000000.0,
}
],
"Parameters": {
"CarrierProfitLoad": 0.0,
"AssumedDeductionEndAge": 100,
"AssumedCoverageEndAge": 120,
"MortalityTable": "2015 VBT",
"MortalityTableAgeBasis": "ALB",
"ValueDate": "2022-05-24T00:00:00",
"DiscountRate": 0.12,
"UseCOIModifier": false,
"PremiumAdjustmentRates":[1.5,1.05,1.0,0.9,0.75],
"MortalityAdjustmentRates":[1.5,1.1,0.95,0.8,0.65],
"PolicyRatingToHealthRatingMapping":["Average","Better","MuchBetter","Better","Average","Average"]
}
}Fully Populated Request
json
{
"Policies": [
{
"Id": "1",
"PolicyType": "UniversalLife",
"AgeToday": 81,
"IssueAge": 75,
"DeductionEndAge": 100,
"CoverageEndAge": 120,
"Gender": "F",
"SmokingStatus": "NonSmoker",
"FaceAmount": 3000000.0,
"CashValue": 0.0,
"TotalPremium": 538975.26,
"AnnualPremium": 89829.21,
"HealthRatingAtIssue": "Average",
"HealthRatingNow": "Average",
"Popc": 0.0,
"FixedLoadPerMonth": 0.0,
"PerUnitPerMonth": 0.0
}
],
"Parameters": {
"CarrierProfitLoad": 0.0,
"AssumedDeductionEndAge": 100,
"AssumedCoverageEndAge": 120,
"MortalityTable": "2015 VBT",
"MortalityTableAgeBasis": "ALB",
"ImprovementMNS": 0.0,
"ImprovementMS": 0.0,
"ImprovementFNS": 0.0,
"ImprovementFS": 0.0,
"ValueDate": "2022-05-24T00:00:00",
"DiscountRate": 0.12,
"UseCOIModifier": true,
"CoiRatioYear": [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32],
"CoiRatio": [3.0781,2.1384,1.6627,1.3838,1.2056,1.0802,0.9851,0.906,0.8382,0.7747,0.7155,0.6593,0.6052,0.5378,0.5093,0.4735,0.4425,0.396,0.3589,0.358,0.3392,0.3251,0.3164,0.3163,0.3529,0.3598,0.3721,0.3838,0.391,0.382,0.3426,0.3207],
"PremiumAdjustmentRates": [1.5,1.05,1.0,0.9,0.75],
"MortalityAdjustmentRates": [1.5,1.1,0.95,0.8,0.65],
"PolicyRatingToHealthRatingMapping": ["Average","Better","MuchBetter","Better","Average","Average"]
}
}Response Example
This is the response from the Fully Populated Request above
json
{
"statusCode": 0,
"pricedPolicies": [
{
"id": "1",
"npvTotalCon": -80365.84225052048,
"npvTotalNormal": 52274.398562899325,
"npvTotalAgg": 209312.19153694587,
"npvPremiumCon": 855476.6782320675,
"npvPremiumNormal": 786282.71195121051,
"npvPremiumAgg": 684864.35582940374,
"npvdbCon": 775110.835981547,
"npvdbNormal": 838557.11051410984,
"npvdbAgg": 894176.54736634961
}
]
}