Pricing API

Request

Endpoint

POST https://www.clarinetlive.com/api/latest/valuationAndRiskCalculator

Role

Pricing API

Request

The request defines the cases, insureds, scenarios and settings used to create a valuation. See full definition of fields in the Schema section.

Example request:

{
  "ValueDate": "2023-01-01",
  "Cases": [
    {
      "CaseReference": "example-case",
      "InsuredLives": [
        {
          "InsuredReference": "example-insured",
          "Gender": "M",
          "DateOfBirth": "1935-09-16",
          "DateOfDeath": null,
          "UnderwriterReports": [
            {
              "Underwriter": "UserDefined",
              "ReportDate": "2014-05-21",
              "SmokingStatus": "NonSmoker",
              "Mortality": null,
              "MeanLE50": 75.0,
              "MedianLE50": null,
              "LE85": null,
              "AnnualDeaths": null
            }
          ]
        }
      ],
      "Policy": {
        "UniversalDeathBenefitType": "Level",
        "UniversalReturnType": "NonVariable",
        "Conversion": null,
        "PolicyType": "UniversalLife",
        "PolicyDate": "2000-08-28",
        "FaceAmount": 500000.0,
        "MaturityAge": 100,
        "MaturityDate": null,
        "CoverageEndDate": "2035-08-28",
        "AgeBasis": "ANB",
        "JointLifePayoutType": null,
        "CoverageEndPaymentType": "None",
        "LapseBasis": "CSV",
        "NonGuaranteedCreditingRate": 0.0,
        "SurrenderChargeType": "Annual"
      },
      "CaseProjection": {
        "TotalPremiumsPaidAmount": null,
        "AccountValueAtCoverageEnd": 0.0,
        "Premiums": [
          {
            "Date": "2023-01-28T00:00:00",
            "Amount": 2661.08
          },
          {
            "Date": "2023-02-28T00:00:00",
            "Amount": 2661.08
          },
          {
            "Date": "2023-03-28T00:00:00",
            "Amount": 2661.08
          },
          {
            "Date": "2023-04-28T00:00:00",
            "Amount": 2661.08
          },
        ],
        "NDBs": [
          {
            "Date": "2014-04-14T00:00:00",
            "Amount": 500000.0
          }
        ],
        "LoanPayments": null,
        "CashWithdrawals": null
      },
      "PaymentHistory": [],
      "Purchase": {
        "PurchaseDate": "2014-05-22T00:00:00",
        "PurchaseCost": 120518.0,
        "OriginationFee": 0.0,
        "PurchaseOtherCosts": 0.0,
        "RetainedDeathBenefit": null,
        "RetainedDeathBenefitSchedule": null
      },
      "Disposal": null,
      "Maturity": null
    }
  ],
  "Scenarios": [
    {
      "ScenarioReference": "Base Scenario",
      "IRR": 0.15
    },
    {
      "ScenarioReference": "13%",
      "IRR": 0.13
    },
    {
      "ScenarioReference": "14%",
      "IRR": 0.14
    }
  ],
  "ValuationSettings": {
    "PricingType": 0,
    "DefaultActuarialTable": "2008 VBT",
    "DefaultAgeBasis": "ANB",
    "DayCountConvention": "30/360",
    "QxAdjustment": null,
    "CalculateRealizedIRR": false,
    "DeterministicBreakevenCalculationType": 0,
    "CalculateDeterministicResults": false,
    "ExcludePaidPremiums": false,
    "IncludePayments": false,
    "AllowNegativeCSVInOptimizer": false,
    "UsePurchaseDateForValueDate": false,
    "CashflowBucketingType": "EndOfMonth",
    "FloorPolicyValuesAtZero": false,
    "NPVCap": 0.0
  },
  "PerPolicyFees": null,
  "PortfolioFees": null,
  "CarrierSettings": {
    "NDBCollectionLag": 2,
    "NDBCollectionLagRate": null,
    "ApplyNDBCollectionLagInterest": false,
    "UsePreviousMonthNDB": false
  },
  "ImprovementSettings": {
    "MNSRate": 0.0,
    "MSRate": 0.0,
    "MARate": 0.0,
    "FNSRate": 0.0,
    "FSRate": 0.0,
    "FARate": 0.0,
    "AgingType": "Regular",
    "StartType": "TableStartDate",
    "ApplyBeforeMortalityCalculation": true
  },
  "IRRSettings": {
    "IncludeOriginationFee": false,
    "IncludeOtherPurchaseCosts": false
  },
  "LEReportSettings": {
    "CalculationType": "Mean",
    "SmokingStatusOverride": "NonSmoker",
    "ReviewDateBlendingType": "Oldest",
    "LongevityBlendingType": "Mortality",
    "OverrideDateToPolicyMonthiversary": false,
    "SubtractFromLE50": 0.0,
    "FallbackToFirstReport": false
  },
  "LESelectionAndBlendingSettings": null,
  "SurvivalCurveSettings": {
    "InterpolationType": "PiecewiseConstantQx",
    "LongevityType": "Exact",
    "JointLifeType": "Frasierized",
    "VBTInterpolation": false,
    "UseFasanoIfAvailable": false,
    "ValueDateShift": "None"
  },
  "UnderwriterSettings": [
    {
      "InsuredReference": "example-insured",
      "UnderwriterWeightings": [
        {
          "Weighting": 100.0,
          "MortalitySpecifier": "LE50ActuarialMean",
          "ApplyImprovementBeforeImpliedMF": false,
          "ActuarialTable": "2008 VBT",
          "AgeBasis": "ANB"
        }
      ]
    }
  ]
}

Response

The response HTTP status code will be set appropriately. I.e. 400 for a bad request and 200 for a successful request.

{
  "IsSuccess": true,
  "Result": {
    "Valuations": [
      {
        "CaseReference": "example-case",
        "ScenarioReference": "S1",
        "NPV": 51615.519988105916,
        "UsedLE": 35.217906606316333,
        "AgedLE": 34.808884227787367,
        "ImpliedMortality": 3.0,
        "CashFlows": {
          "CashWithdrawalCfs": [
            0.0,
            ...
	       		0.0
          ],
          "FeesCfs": [
            0.0,
            ...
            0.0
          ],
          "LoanInterestPaymentCfs": [
            0.0,
            ...
            0.0
          ],
          "LoanRepaymentCfs": [
            0.0,
            ...
            0.0
          ],
          "NDBCfs": [
            0.0,
            3303.0420754897041,
            ...
          ],
          "PremiumCfs": [
            0.0,
            ...
            0.0
          ],
          "AggregateCfs": [
            0.0,
            3303.0420754897041,
            ...
          ],
          "AggregateLoanPaymentCfs": [
            0.0,
            ...
            0.0
          ],
          "AggregatePremiumAndLoanPaymentCfs": [
            0.0,
            ...
            0.0
          ]
        },
        "SurvivalProbabilities": [
          1.0,
          0.9966969579245103,
          ...
        ]
      }
    ],
    "BucketSchedule": [
      "2023-01-01T00:00:00",
	  "2023-01-01T00:00:00"
    ]
  }
}

Schema

PortfolioPricingRequestDto

Name	Type	Required
ValueDate	string
Cases	Array[CaseDto]	Yes
Scenarios	Array[ScenarioDto]	Yes
ValuationSettings	ValuationSettingsDto	Yes
PerPolicyFees	Array[RecurringFeeDto]
PortfolioFees	PortfolioFeesDto
CarrierSettings	CarrierSettingsDto
ImprovementSettings	ImprovementSettingsDto
IRRSettings	IRRSettingsDto
LEReportSettings	LEReportSettingsDto
LESelectionAndBlendingSettings	LESelectionAndBlendingSettingsDto
SurvivalCurveSettings	SurvivalCurveSettingsDto
UnderwriterSettings	Array[InsuredUnderwriterSettingsDto]

CaseDto

Name	Type	Required
CaseReference	string	Yes
InsuredLives	Array[InsuredLifeDto]	Yes
Policy	PolicyDto	Yes
CaseProjection	CaseProjectionDto	Yes
PaymentHistory	Array[PaymentDto]
Purchase	LifeSettlementDto
Disposal	PolicyDisposalDto
Maturity	PolicyMaturityDto

ScenarioDto

Name	Type	Required
ScenarioReference	string	Yes
IRR	number	Yes
LE50Floor	integer
PremiumMultiplier	number
LE50RiskBump	RiskBumpDto
MortalityRiskBump	RiskBumpDto

ValuationSettingsDto

Name	Type	Required	Potential Values
PricingType	string	Yes	Probabilistic
			DeterministicAgedJointLE
			DeterministicValueDate
			DeterministicIndividualLE
DefaultActuarialTable	ActuarialTableDto	Yes
DefaultAgeBasis	string	Yes	ALB
			ANB
DayCountConvention	string
PremiumPaymentShift	PremiumPaymentShiftDto
QxAdjustment	QxAdjustmentDto
CalculateRealizedIRR	boolean
DeterministicBreakevenCalculationType	string		None
			PurchasePrice
			CurrentValuation
			PurchasePriceAndCurrentValuation
CalculateDeterministicResults	boolean
ExcludePaidPremiums	boolean
IncludePayments	boolean
AllowNegativeCSVInOptimizer	boolean
UsePurchaseDateForValueDate	boolean
CashflowBucketingType	string		None
			EndOfMonth
			RawCashflows
FloorPolicyValuesAtZero	boolean
NPVCap	number

RecurringFeeDto

Name	Type	Required	Potential Values
Amount	number
MinimumAmount	number
Duration	number
Interval	number
Frequency	string	Yes	Monthly
			Annual
			Acquisition
			Maturity
PaymentType	string	Yes	Fixed
			AcquisitionPrice
			NDB
			NPV

PortfolioFeesDto

Name	Type	Required	Potential Values
Amount	number
Frequency	string	Yes	Monthly
			Quarterly
			SemiAnnual
			Annual

CarrierSettingsDto

Name	Type	Required
NDBCollectionLag	integer
NDBCollectionLagRate	number
ApplyNDBCollectionLagInterest	boolean
UsePreviousMonthNDB	boolean

ImprovementSettingsDto

Name	Type	Required	Potential Values
MNSRate	number
MSRate	number
MARate	number
FNSRate	number
FSRate	number
FARate	number
AgingType	string		Regular
			BeforeBlending
			Straight
			RollDown
StartType	string		TableStartDate
			UnderwritingDate
			UnderwritingDateWithExtraYear
ApplyBeforeMortalityCalculation	boolean

IRRSettingsDto

Name	Type	Required
IncludeOriginationFee	boolean
IncludeOtherPurchaseCosts	boolean

LEReportSettingsDto

Name	Type	Required	Potential Values
CalculationType	string		Mean
			Median
SmokingStatusOverride	string		NonSmoker
			Smoker
			Aggregate
ReviewDateBlendingType	string		Oldest
			Newest
			Blended
LongevityBlendingType	string		Mortality
			MeanLE50
			Mqx
			Lx
OverrideDateToPolicyMonthiversary	boolean
SubtractFromLE50	number
FallbackToFirstReport	boolean

LESelectionAndBlendingSettingsDto

Name	Type	Required
Rules	Array[LESelectionAndBlendingRuleDto]
PreventUnderwriterReselection	boolean

SurvivalCurveSettingsDto

Name	Type	Required	Potential Values
InterpolationType	string		PiecewiseConstantForceOfDeath
			PiecewiseConstantQx
			PiecewiseLinearForceOfDeath
			PiecewiseLinearQx
LongevityType	string		Exact
			ExactWithOneMonthNDBDelay
			Monthly
			ExactWithFullYearMqx
JointLifeType	string		ShortestLE
			LongestLE
			Frasierized
VBTInterpolation	boolean
UseFasanoIfAvailable	boolean
ValueDateShift	string		None
			Next
			ThisMonth

InsuredUnderwriterSettingsDto

Name	Type	Required
InsuredReference	string	Yes
UnderwriterWeightings	Array[InsuredUnderwriterWeightingDto]	Yes

InsuredLifeDto

Name	Type	Required	Potential Values
InsuredReference	string
Gender	string		M
			F
DateOfBirth	string
DateOfDeath	string
UnderwriterReports	Array[UnderwriterReportDto]

PolicyDto

Name	Type	Required	Potential Values
PolicyType	string	Yes	UniversalLife
			WholeLife
			TermLife
			Endowment
PolicyDate	string	Yes
FaceAmount	number	Yes
MaturityAge	integer
MaturityDate	string
CoverageEndAge	integer
CoverageEndDate	string
AgeBasis	string		ALB
			ANB
			ANBm
JointLifePayoutType	string		FirstToDie
			SecondToDie
CoverageEndPaymentType	string		None
			NDB
			AV
LapseBasis	string		CSV
			AV
NonGuaranteedCreditingRate	number
SurrenderChargeType	string		Annual
			MonthlyGraded
			AnnualWithDelay
			MonthlyGradedWithDelay

CaseProjectionDto

Name	Type	Required
TotalPremiumsPaidAmount	number
AccountValueAtCoverageEnd	number
Premiums	Array[PremiumProjectionRowDto]
NDBs	Array[NDBProjectionRowDto]	Yes
LoanPayments	Array[LoanPaymentProjectionRowDto]
CashWithdrawals	Array[CashWithdrawalProjectionRowDto]

PaymentDto

Name	Type	Required	Potential Values
PaymentType	string	Yes	Premium Fee
			LoanDrawdown
			LoanRepayment
			CashWithdrawal
PaymentDate	string	Yes

LifeSettlementDto

Name	Type	Required
PurchaseDate	string	Yes
PurchaseCost	number	Yes
OriginationFee	number
PurchaseOtherCosts	number
RetainedDeathBenefit	RetainedDeathBenefitDto
RetainedDeathBenefitSchedule	Array[Row]

PolicyDisposalDto

Name	Type	Required	Potential Values
DisposalDate	string	Yes
DisposalType	string		Sold
			Surrendered
			Lapsed
			Expired
DisposalAmount	number	Yes
PremiumReimbursement	number

PolicyMaturityDto

Name	Type	Required
PaymentDate	string
NDB	number	Yes
Interest	number
ReturnOfPremium	number
OtherAmount	number

RiskBumpDto

Name	Type	Required
Add	number
Multiply	number
Expression	string

PremiumPaymentShiftDto

Name	Type	Required	Potential Values
ShiftType	string	Yes	Following
			Preceding
			Next
			Previous
DayOfMonth	integer

QxAdjustmentDto

Name	Type	Required
Months	integer	Yes
Addition	number
Multiplication	number
Expression	string

LESelectionAndBlendingRuleDto

Name	Type	Required	Potential Values
SelectionType	string		MostRecent
			ShortestMeanLE50
			LongestMeanLE50
			MostRecentOnOrBeforeValueDate
			MostRecentBeforeSpecifiedDate
			MostRecentAfterSpecifiedDate
			ShortestMedianLE50
			LongestMedianLE50
			HighestMortality
			LowestMortality
			ShortestMeanLE50StraightAged
			LongestMeanLE50StraightAged
SelectionDate	string
Underwriter	string		UserDefined
			TWENTY_FIRST
			AUS
			ELEVATION
			AVS
			PREDICTIVE_RESOURCES
			LSI
			FOCUS
			CONVERGENCE
			EMSI
			FASANO
			LAPETUS
			ISC
			GLOBAL_LIFE
			POLARIS
MortalitySpecifierSelectors	Array[string]
BlendWeighting	number
ApplyImprovementBeforeImpliedMF	boolean
ActuarialTable	ActuarialTableDto
AgeBasis	string		ALB
			ANB

InsuredUnderwriterWeightingDto

Name	Type	Required	Potential Values
Weighting	number
MortalitySpecifier	string		LE50ActuarialMean
			Median
			Mortality
			FullCurve
ApplyImprovementBeforeImpliedMF	boolean
ActuarialTable	ActuarialTableDto
AgeBasis	string		ALB
			ANB

UnderwriterReportDto

Name	Type	Required	Potential Values
Underwriter	string		AUS
			AVS
			CONVERGENCE
			ELEVATION
			EMSI
			FASANO
			FOCUS
			GLOBAL_LIFE
			ISC
			LAPETUS
			LSI
			PREDICTIVE_RESOURCES
			POLARIS
			TWENTY_FIRST
			UserDefined
ReportDate	string	Yes
SmokingStatus	string		NonSmoker
			Smoke
			Aggregate
Mortality	number
MeanLE50	number
MedianLE50	number
LE85	number
AnnualDeaths	Array[number]

PremiumProjectionRowDto

Name	Type	Required
Date	string	Yes
Amount	number	Yes

NDBProjectionRowDto

Name	Type	Required
Date	string	Yes
Amount	number	Yes

LoanPaymentProjectionRowDto

Name	Type	Required
Date	string	Yes
Principal	number
Interest	number

CashWithdrawalProjectionRowDto

Name	Type	Required
Date	string	Yes
GrossPaymentAmount	number
SurrenderCharge	number
NetPaymentAmount	number

RetainedDeathBenefitDto

Name	Type	Required
Amount	number
Percentage	number

Row

Name	Type	Required
Date	string	Yes
Amount	number
Percentage	number