Internal Valuations API

Get Valuation Templates

GET https://www.clarinetlive.com/api/v4/valuation-templates

Returns the list of valuation templates available to your organisation. The template name is required when running a valuation.

Request

No body.

Query parameters:

isDefault — optional boolean. When true, returns only the default valuation template. Defaults to false.

Response

Code	Message	Description
200	OK	A list of valuation templates.
403	Forbidden	The API key does not have permission.

200 response content:

json

[
  {
    "name": "Standard Probabilistic",
    "isDefault": true,
    "isArchived": false
  },
  {
    "name": "Legacy 2021",
    "isDefault": false,
    "isArchived": true
  }
]

Get Fees Templates

GET https://www.clarinetlive.com/api/v4/fees-templates

Returns the list of fees templates available to your organisation. The template name is required when running a valuation.

Request

No body.

Query parameters:

isDefault — optional boolean. When true, returns only the default fees template. Defaults to false.

Response

Code	Message	Description
200	OK	A list of fees templates.
403	Forbidden	The API key does not have permission.

200 response content:

json

[
  {
    "name": "Standard Fees",
    "isDefault": true,
    "isArchived": false
  },
  {
    "name": "Zero Fees",
    "isDefault": false,
    "isArchived": false
  }
]

Get Qx Adjustments

GET https://www.clarinetlive.com/api/v4/qx-adjustments

Returns the list of mortality (Qx) adjustment factors available to your organisation.

Request

No body.

Query parameters:

isDefault — optional boolean. When true, returns only the default Qx adjustment. Defaults to false.

Response

Code	Message	Description
200	OK	A list of Qx adjustment entries.
403	Forbidden	The API key does not have permission.

200 response content:

json

[
  {
    "name": "No Adjustment",
    "isDefault": true
  },
  {
    "name": "Covid Adjustment",
    "isDefault": false
  }
]

Get Risk Scenarios

GET https://www.clarinetlive.com/api/v4/risk-scenarios

Returns the list of risk scenarios available to your organisation. Risk scenarios are used in probabilistic valuations.

Request

No body. No query parameters.

Response

Code	Message	Description
200	OK	A list of risk scenarios.
403	Forbidden	The API key does not have permission.

200 response content:

json

[
  {
    "name": "Base"
  },
  {
    "name": "Stressed"
  }
]

Get Deterministic Pricing Scenarios

GET https://www.clarinetlive.com/api/v4/deterministic-pricing-scenarios

Returns the list of deterministic pricing scenarios available to your organisation.

Request

No body. No query parameters.

Response

Code	Message	Description
200	OK	A list of deterministic pricing scenarios.
403	Forbidden	The API key does not have permission.

200 response content:

json

[
  {
    "name": "Base IRR"
  },
  {
    "name": "High IRR"
  }
]

Get Mortality Tables

GET https://www.clarinetlive.com/api/v4/mortality-tables

Returns the list of actuarial mortality tables available to your organisation. These are used when constructing on-the-fly or existing report weightings.

Request

No body. No query parameters.

Response

Code	Message	Description
200	OK	A list of mortality tables.
403	Forbidden	The API key does not have permission.

200 response content:

json

[
  {
    "name": "2015 VBT",
    "ageBasis": "ALB",
    "isDefault": true
  },
  {
    "name": "2008 VBT",
    "ageBasis": "ANB",
    "isDefault": false
  }
]

Get Case Weighting Names

GET https://www.clarinetlive.com/api/v4/case-weighting-names

Returns the named case weighting presets available. A case weighting name groups a pre-configured set of LE report weightings for use when fetching default valuation inputs.

Request

No body.

Query parameters:

isDefault — optional boolean. When true, returns only the default case weighting name. Defaults to false.

Response

Code	Message	Description
200	OK	A list of case weighting names.
403	Forbidden	The API key does not have permission.

200 response content:

json

[
  {
    "name": "Equal Weight",
    "isDefault": true
  },
  {
    "name": "Most Recent Only",
    "isDefault": false
  }
]

List Valuations

GET https://www.clarinetlive.com/api/v4/cases/{casePublicId}/valuations

Returns a paginated list of saved valuations for a case, ordered most recent first.

Request

No body.

Route parameters:

casePublicId — required UUID. The PublicID of the case.

Query parameters:

page — optional integer. The 1-indexed page number to return. Defaults to 1.
pageSize — optional integer. The number of results per page. Defaults to 20.

Response

Code	Message	Description
200	OK	A paginated list of valuations for the case.
404	Not Found	The case was not found.
403	Forbidden	The API key does not have permission.

200 response content:

json

{
  "currentPage": 1,
  "pageSize": 20,
  "totalResults": 2,
  "items": [
    {
      "publicId": "00000000-0000-0000-0000-000000000001",
      "premiumSchedulePublicId": "00000000-0000-0000-0000-000000000002",
      "policyDate": "2018-03-01",
      "carrierName": "Pacific Life",
      "frozen": false,
      "valueDate": "2026-05-01",
      "description": "Q2 2026 Valuation",
      "valuationTemplateName": "Standard Probabilistic",
      "feesTemplateName": "Standard Fees",
      "qxAdjustmentName": "No Adjustment",
      "riskScenarioName": "Base",
      "deterministicPricingScenarioName": null,
      "pricingType": "Probabilistic",
      "floorPolicyValueAtZero": false,
      "calculateDeterministicBreakevenValues": false,
      "rdbType": "None",
      "rdbAmount": null,
      "rdbPercentage": null,
      "scheduledRBDRows": [],
      "jointLE": 32.5,
      "jointLifeHandlingType": null,
      "customIrrs": [],
      "insureds": [
        {
          "dateOfBirth": "1942-06-15",
          "dateOfDeath": null,
          "gender": "Female",
          "leReportWeightings": [
            {
              "underwriter": "ISC",
              "reportDate": "2020-12-10",
              "mortality": 3.75,
              "meanLE": 44.0,
              "medianLE": null,
              "lE85": null,
              "smoker": "NonSmoker",
              "weighting": 1,
              "actuarialTable": "2015 VBT",
              "useImprovement": false,
              "impliedMortality": null,
              "mortalitySpecifier": "LE50ActuarialMean",
              "underwriterFullName": "ISC",
              "fullCurveAvailable": false
            }
          ],
          "blendedLEReport": null
        }
      ],
      "results": [
        {
          "valuationTemplateName": "Standard Probabilistic",
          "blend": "ISC: 100%",
          "usedLE": 32.5,
          "agedJointLE": null,
          "insured1UsedLE": 32.5,
          "insured1MF": 1.0,
          "agedInsured1LE": 30.1,
          "insured2UsedLE": null,
          "insured2MF": null,
          "agedInsured2LE": null,
          "npvs": [
            {
              "value": 285000.00,
              "feesIrr": 0.12,
              "premiumIrr": 0.12,
              "ndbIrr": 0.12
            }
          ]
        }
      ]
    }
  ]
}

Get Valuation

GET https://www.clarinetlive.com/api/v4/cases/{casePublicId}/valuations/{publicId}

Returns the full details of a single saved valuation.

Request

No body.

Route parameters:

casePublicId — required UUID. The PublicID of the case.
publicId — required UUID. The PublicID of the valuation.

Response

Code	Message	Description
200	OK	The valuation details.
404	Not Found	The case or valuation was not found.
403	Forbidden	The API key does not have permission.

200 response content: A single Valuation object — see the list response above for the full structure.

Get Default Valuation Inputs

GET https://www.clarinetlive.com/api/v4/cases/{casePublicId}/valuations/inputs

Returns the default valuation input parameters for a case. This includes the default template names, pricing settings, and pre-populated LE report weightings for each insured on the case. Use this as a starting point when constructing a new valuation request.

Request

No body.

Route parameters:

casePublicId — required UUID. The PublicID of the case.

Query parameters:

caseWeightingName — optional string. The name of a case weighting preset to apply when pre-populating the insured LE report weightings.

Response

Code	Message	Description
200	OK	Default valuation inputs for the case.
400	Bad Request	The `caseWeightingName` provided was not recognized.
404	Not Found	The case was not found.
403	Forbidden	The API key does not have permission.

200 response content:

json

{
  "valueDate": "2026-05-12",
  "valuationTemplateName": "My Valuation Template",
  "feesTemplateName": "Standard Fees",
  "qxAdjustmentName": "No Adjustment",
  "premiumSchedulePublicId": "00000000-0000-0000-0000-000000000001",
  "pricingType": "Probabilistic",
  "riskScenarioName": "Base",
  "deterministicPricingScenarioName": null,
  "customIrrNames": [],
  "purchaseCost": 125000.0,
  "purchaseDate": "2022-12-15",
  "floorPolicyValueAtZero": false,
  "calculateDeterministicBreakevenValues": false,
  "description": "",
  "availableCustomIrrNames": [],
  "insureds": [
    {
      "insuredPublicId": "00000000-0000-0000-0000-000000000002",
      "insuredName": "Alice Murphy",
      "existingReportWeightings": [
        {
          "reportPublicId": "00000000-0000-0000-0000-000000000003",
          "weighting": 0.3333,
          "mortalitySpecifier": "LE50ActuarialMean",
          "actuarialTableName": "2015 VBT",
          "ageBasis": "ALB",
          "useImprovement": false
        },
        {
          "reportPublicId": "00000000-0000-0000-0000-000000000004",
          "weighting": 0.3333,
          "mortalitySpecifier": "LE50ActuarialMean",
          "actuarialTableName": "2015 VBT",
          "ageBasis": "ALB",
          "useImprovement": false
        },
        {
          "reportPublicId": "00000000-0000-0000-0000-000000000005",
          "weighting": 0.3334,
          "mortalitySpecifier": "LE50ActuarialMean",
          "actuarialTableName": "2015 VBT",
          "ageBasis": "ALB",
          "useImprovement": false
        }
      ],
      "onTheFlyReportWeightings": [],
      "availableReports": [
        {
          "reportPublicId": "00000000-0000-0000-0000-000000000003",
          "reportName": "ISC",
          "reportDate": "2020-12-10",
          "smokingStatus": "NonSmoker",
          "meanLE": 44.0,
          "medianLE": null,
          "mortality": 3.75,
          "fullCurveAvailable": false
        },
        {
          "reportPublicId": "00000000-0000-0000-0000-000000000004",
          "reportName": "ITM 21st",
          "reportDate": "2021-09-28",
          "smokingStatus": "NonSmoker",
          "meanLE": 39.6,
          "medianLE": null,
          "mortality": 16.15,
          "fullCurveAvailable": false
        },
        {
          "reportPublicId": "00000000-0000-0000-0000-000000000005",
          "reportName": "Predictive",
          "reportDate": "2023-09-06",
          "smokingStatus": "NonSmoker",
          "meanLE": 32.0,
          "medianLE": null,
          "mortality": 8.6,
          "fullCurveAvailable": false
        }
      ]
    }
  ]
}

Key response fields:

valuationTemplateName, feesTemplateName, qxAdjustmentName — the system defaults, ready to submit directly or override.
premiumSchedulePublicId — the premium schedule linked to the case that will be used by default.
insureds[].existingReportWeightings — pre-populated weightings based on the case’s LE reports. weighting values must sum to 1.0 across all weightings for an insured.
insureds[].availableReports — all LE reports available for the insured that can be used in existingReportWeightings. Use reportPublicId to reference a specific report.
availableCustomIrrNames — custom IRR names available to include in the valuation when pricingType is CustomIRR.

Get Valuation Inputs From Existing Valuation

GET https://www.clarinetlive.com/api/v4/cases/{casePublicId}/valuations/{publicId}/inputs

Returns the input parameters from a previously saved valuation, formatted ready to be used as the body of a new valuation request. Use this when you want to re-run or adjust an existing valuation.

Request

No body.

Route parameters:

casePublicId — required UUID. The PublicID of the case.
publicId — required UUID. The PublicID of the saved valuation to copy inputs from.

Response

Code	Message	Description
200	OK	Valuation inputs from the specified saved valuation.
404	Not Found	The case or valuation was not found.
403	Forbidden	The API key does not have permission.

200 response content: A default valuation inputs object — see the default inputs response above for the full structure. The fields will be populated with the values from the specified saved valuation.

Run Valuation

POST https://www.clarinetlive.com/api/v4/cases/{casePublicId}/valuations

Runs a valuation for a case. The valuation can be run ad-hoc (returning the result without saving) or saved to the case by specifying "save": true.

Request

Route parameters:

casePublicId — required UUID. The PublicID of the case.

Request body:

json

{
  "save": true,
  "valueDate": "2026-05-12",
  "valuationTemplateName": "My Valuation Template",
  "feesTemplateName": "Standard Fees",
  "qxAdjustmentName": "No Adjustment",
  "premiumSchedulePublicId": "00000000-0000-0000-0000-000000000001",
  "pricingType": "Probabilistic",
  "riskScenarioName": "Base",
  "deterministicPricingScenarioName": null,
  "customIrrNames": [],
  "purchaseCost": 0.0,
  "purchaseDate": "2022-12-15",
  "floorPolicyValueAtZero": false,
  "calculateDeterministicBreakevenValues": false,
  "description": "Q2 2026 Valuation",
  "insureds": [
    {
      "insuredPublicId": "00000000-0000-0000-0000-000000000002",
      "existingReportWeightings": [
        {
          "reportPublicId": "00000000-0000-0000-0000-000000000003",
          "weighting": 0.3333,
          "mortalitySpecifier": "LE50ActuarialMean",
          "actuarialTableName": "2015 VBT",
          "ageBasis": "ALB",
          "useImprovement": false
        },
        {
          "reportPublicId": "00000000-0000-0000-0000-000000000004",
          "weighting": 0.3333,
          "mortalitySpecifier": "LE50ActuarialMean",
          "actuarialTableName": "2015 VBT",
          "ageBasis": "ALB",
          "useImprovement": false
        },
        {
          "reportPublicId": "00000000-0000-0000-0000-000000000005",
          "weighting": 0.3334,
          "mortalitySpecifier": "LE50ActuarialMean",
          "actuarialTableName": "2015 VBT",
          "ageBasis": "ALB",
          "useImprovement": false
        }
      ],
      "onTheFlyReportWeightings": []
    }
  ]
}

Request body fields:

Field	Type	Required	Description
`save`	boolean	Yes	Set to `true` to save the valuation to the case. Set to `false` to run an ad-hoc valuation that returns a result without persisting it.
`valueDate`	date	No	The date as of which the valuation is calculated. Defaults to today if not provided.
`valuationTemplateName`	string	No	The name of the valuation template to use.
`feesTemplateName`	string	No	The name of the fees template to use.
`qxAdjustmentName`	string	No	The name of the Qx adjustment to apply.
`premiumSchedulePublicId`	UUID	No	The PublicID of the premium schedule to use.
`pricingType`	string	No	One of `Probabilistic` , `CustomIRR` , `DeterministicAgedJointLE` , `DeterministicValueDate` , `DeterministicIndividualLE` .
`riskScenarioName`	string	No
`deterministicPricingScenarioName`	string	No	Required when `pricingType` is a deterministic type.
`customIrrNames`	string[]	Yes	Array of custom IRR names. Required when `pricingType` is `CustomIRR`
`purchaseCost`	number	No	The purchase cost of the policy.
`purchaseDate`	date	No	The date the policy was purchased.
`floorPolicyValueAtZero`	boolean	Yes	When `true` , the policy value is floored at zero (cannot go negative).
`calculateDeterministicBreakevenValues`	boolean	Yes	When `true` , deterministic break-even values are calculated. Relevant for saved valuations only.
`description`	string	No	A description for the valuation, used when `save` is `true` .
`insureds`	array	Yes	One entry per insured on the case. At least one insured is required.

Insured object fields (insureds[]):

Field	Type	Required	Description
`insuredPublicId`	UUID	Yes	The PublicID of the insured. Obtain the available insured IDs from the inputs endpoint.
`existingReportWeightings`	array	No	Weightings referencing LE reports already stored in ClariNet. Weightings across all entries for this insured must sum to 1.0.
`onTheFlyReportWeightings`	array	No	Weightings for custom (on-the-fly) mortality assumptions not tied to a stored LE report.

Existing report weighting fields (existingReportWeightings[]):

Field	Type	Required	Description
`reportPublicId`	UUID	Yes	The PublicID of the LE report. Available from the inputs endpoint `availableReports` .
`weighting`	number	Yes	The proportional weighting (e.g. `0.3333` ). All weightings for the insured must sum to `1.0` .
`mortalitySpecifier`	string	Yes	How mortality is extracted from the report. One of `Mortality` , `LE50ActuarialMean` , `FullCurve` , `LE50Median` .
`actuarialTableName`	string	No	The actuarial table to use when converting the LE to a mortality curve. Required except when using `FullCurve` reports.
`ageBasis`	string	No	Age basis for the actuarial table: `ANB` , `ALB` .
`useImprovement`	boolean	Yes	Whether to apply mortality improvement factors.

On-the-fly report weighting fields (onTheFlyReportWeightings[]):

Field	Type	Required	Description
`weighting`	number	Yes	The proportional weighting. All weightings for the insured must sum to `1.0` .
`actuarialTableName`	string	Yes	The actuarial table to use.
`useImprovement`	boolean	Yes	Whether to apply mortality improvement factors.
`reportDate`	date	No	The date of the notional LE report.
`smokingStatus`	string	No	One of `NonSmoker` , `Smoker` .
`mortalitySpecifier`	string	No	How the mortality assumption is specified. One of `Mortality` , `LE50ActuarialMean` .
`mortalitySpecifierValue`	number	No	The value corresponding to the `mortalitySpecifier` (e.g. mortality percentage or LE in months).
`ageBasis`	string	No	Age basis for the actuarial table: `ANB` , `ALB` .

Response

Code	Message	Description
200	OK	Ad-hoc valuation completed ( `save: false` ). The result is returned but not stored.
201	Created	Valuation saved successfully ( `save: true` ). The `Location` header is set to the URI of the newly created valuation resource.
400	Bad Request	Request validation failed. The response body will contain details.
403	Forbidden	The API key does not have permission.
422	Unprocessable Entity	The valuation could not be calculated. The response body will contain details of the failure.
429	Too Many Requests	Rate limit exceeded.
500	Server Error	An unexpected error occurred during the valuation calculation.

200 / 201 response content: A single Valuation object — see the list response above for the full structure

Expected Flow

The following describes the recommended sequence of API calls to run and save a valuation for a case.

Step 1 — Gather Reference Data

Before constructing a valuation request, retrieve the available configuration options:

plain

GET /api/v4/valuation-templates
GET /api/v4/fees-templates
GET /api/v4/qx-adjustments
GET /api/v4/risk-scenarios
GET /api/v4/mortality-tables

Store the name values from each response. These are required when building the valuation request body.

These endpoints return organization-wide configuration and change infrequently. You may cache the results rather than calling them on every valuation run.

Step 2 — Get Valuation Inputs

There are two ways to get the inputs for your valuation request:

Option A — Start from defaults (new valuation)

Call the default inputs endpoint to get system-default parameters pre-populated with the case’s LE reports:

plain

GET /api/v4/cases/{casePublicId}/valuations/inputs

Optionally supply a caseWeightingName query parameter to apply a named weighting preset to the LE reports.

The response gives you a ready-to-use object containing:

The default template, fees, and Qx adjustment names.
The premium schedule in use on the case.
Each insured with their existingReportWeightings pre-populated.
The availableReports list for each insured, showing all LE reports you can choose from.

Option B — Start from a previous valuation

If you want to re-run or adjust an existing valuation, first list saved valuations for the case:

plain

GET /api/v4/cases/{casePublicId}/valuations

Then retrieve the inputs from the valuation you want to repeat:

plain

GET /api/v4/cases/{casePublicId}/valuations/{publicId}/inputs

The response has the same structure as Option A, but populated with the settings from the selected valuation rather than case defaults.

Step 3 — Adjust the Parameters

Review and modify the inputs as required before submitting. Common adjustments include:

Changing the valueDate to the desired valuation date.
Changing LE report weightings in existingReportWeightings, ensuring weightings still sum to 1.0 per insured.
Overriding valuationTemplateName, feesTemplateName, or qxAdjustmentName with alternative values from the reference data endpoints.
Adding onTheFlyReportWeightings for mortality assumptions not tied to a stored LE report.
Providing a description that will be stored with the valuation record.

Step 4 — Run the Valuation

Submit the inputs to the run valuation endpoint:

plain

POST /api/v4/cases/{casePublicId}/valuations

Set "save": true in the request body to persist the valuation to the case record. The response will be 201 Created and the Location header will contain the URI of the new valuation.

Set "save": false for an exploratory run. The response will be 200 OK with the valuation result, but nothing will be stored — publicId will not be set in the response.

Step 5 — Read the Results

The response body contains the full valuation result. The key output is found in the results array:

results[].npvs[].value — the net present value of the policy.
results[].usedLE — the blended life expectancy (months) used in the calculation.
results[].npvs[].feesIrr / premiumIrr / ndbIrr — the IRR rates applied.

When save: true, the saved valuation’s publicId is returned in the response. You can subsequently retrieve it using:

plain

GET /api/v4/cases/{casePublicId}/valuations/{publicId}

Internal Valuations API ​

Get Valuation Templates

Request

Response

Get Fees Templates

Request

Response

Get Qx Adjustments

Request

Response

Get Risk Scenarios

Request

Response

Get Deterministic Pricing Scenarios

Request

Response

Get Mortality Tables

Request

Response

Get Case Weighting Names

Request

Response

List Valuations

Request

Response

Get Valuation

Request

Response

Get Default Valuation Inputs

Request

Response

Get Valuation Inputs From Existing Valuation

Request

Response

Run Valuation

Request

Response

Expected Flow

Step 1 — Gather Reference Data

Step 2 — Get Valuation Inputs

Step 3 — Adjust the Parameters

Step 4 — Run the Valuation

Step 5 — Read the Results

Internal Valuations API