Monte Carlo API Endpoint

Initial Request

Endpoint

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

Role

Portfolio Pricing (Monte Carlo)

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.
- All defaulted values are included in the output.

Request Parameters

Portfolio: Only a single Portfolio should be specified of a valid ClariNet LS Portfolio. String, required

ValueDate: ISO 8601 format - yyyy-MM-dd Date, required

LeSelectionAndBlending: The name of a ClariNet LS LE Report Selection rule set. String, optional

ActuarialTable: This should take the format {TableName} {AgeBasis} {Gender} {SmokerStatus}, for example “MyTable ANB M Smoker”. String, optional

UsedValuationWeightings: Either “Primary”, “Actual Expected” or any Custom Case Weightings. String, optional

FloorPolicyValueAtZero: true or false Boolean, optional OverridePremiumSchedules: true or false String, optional

PremiumCalculatorTemplate: The name of a Clarinet LS Premium Calculator template. String, optional

StartDate: ISO 8601 format - yyyy-MM-dd. Date, optional

CalculateRealizedIRR: true or false Boolean, optional

CalculateRealizedLE: true or false Boolean, optional

IgnoreDateOfDeath: true or false Boolean, optional

IncludeHistoricPayments: true or false Boolean, optional

RiskScenario: The name of a ClariNet LS Risk Scenario String, optional

CashFlowBucketingType: “None”, “End of Month”, “Raw Cashflows”. String, optional

NumOfSimulations: An integer between 2 and 50,000 – even numbers only. Integer, required

RandomSeed: Any 32-bit integer value. Integer, optional

SamplingType: For future usage, currently only “Random” is supported. String, optional

Percentiles: When requesting a Decile report output type, the percentiles to run – maximum 100 values. 1.0 = 100%. Numeric array, required if an outputType of DecileCumulative or DecileNPV is requested. ValuePrecision: Precision to round output values to – between 1 and 8. Integer, optional

Horizon: ISO 8601 format – yyyy-MM-dd. This date is a threshold to limit dates included in the output. You can use this to reduce output size if you do not require a full set of output dates. For example, if you provided a date of 2040-01-01, no buckets after that date would be present in the output. Date, optional

OutputTypes: An array of output types you want to receive in the output. One or more of the following values: DecileCumulative, DecileNPV, AggregateCashFlows, CumulativeCashFlows, AggregateDeathBenefitCashFlow, AggregatePremiumPayments. String array, required

AdditionalUsers: An array of valid usernames to which the report is also visible from the “MyReports” screen in ClarinetLS. String array, optional

SubscriberWide: True or false – if set to true, the report is visible to all users within the requestor’s company. Boolean, optional

The inputs correspond to on-screen settings on the Clarinet LS Monte Carlo screen as below:

The Output Types map to the available results on the Clarinet LS Monte Carlo screen as below:

Request Examples

Here is an example valid request body:

json

{
    "portfolio":"Active Cases",
    "valueDate":"2020-06-24", 
    "valuationTemplate":"Standard Valuation Template", 
    "underwriterWeightings":"Valuation", 
    "cashflowBucketingType":"End of Month", 
    "numOfSimulations":1000,
    "randomSeed":1,
    "percentiles":[
        0.01,
        0.05,
        0.10,
        0.25,
        0.50,
        0.75,
        0.90,
        0.95,
        0.99
    ],
    "outputTypes":[
        "DecileCumulative"
    ]
}

Responses

Below are listed some specific responses for this endpoint. General information about responses, status codes and errors can be found in Responses and Errors.

Code	Description
201	If the request has been validated successfully, you will receive a 201 Created response. The response body will contain a status object, as described under the Status Request endpoint. The response Location header will contain a URL for this status object.
200	The report request is a duplicate of another and so the original report request will be fulfilled and this one will be ignored. The response body will contain a status object, as described under the Status Request endpoint, that corresponds to the original report request. The response Location header will contain a URL for this status object.

Status Request

Endpoint

GET https://www.clarinetlive.com/api/latest/report/status?reportId=xxxxxxxxxxx

Request

Once the report has been successfully created (a 201-response described above), ClariNet LS will schedule and execute the report.

You can query the status endpoint, the URL of which is in the “Location” header of the initial request. reportId in that URL is a unique identifier for the report you requested.

Response Examples

This will return a JSON object that initially looks like the below:

json

{
    "fileName": "montecarlo_Active Cases_20200625 082019",
    "title": "Monte Carlo – Active Cases - 25/06/2020", 
    "status": "Requested",
    "message": ""
}

Once Clarinet LS begins processing the request, it will change to:

json

{
    "fileName": "montecarlo_Active Cases_20200625 082019",
    "title": "Monte Carlo – Active Cases - 25/06/2020", 
    "status": "Started",
    "message": ""
}

And once complete, it will look like this:

json

{
    "fileName": "montecarlo_Active Cases_20200625 082019",
    "title": "Monte Carlo – Active Cases - 25/06/2020", 
    "status": "Completed",
    "message": "Report complete. See header for location."
}

The location header will then contain a URL to get the actual report.

Download Request

Endpoint

GET https://www.clarinetlive.com/api/latest/report?reportId=xxxxxxxxxxx

Request

Querying this endpoint will then return a JSON response containing the output of the Monte Carlo Simulation.

Responses

The Monte Carlo output is structured as follows:

outputType: The type of this output – “DecileCumulative” for example.
data: The results of the report.
- dates: An array of buckets in the report – date only, no timestamp, in ISO 8601 format – yyyy-MM-dd
- metrics: This is an array of metric result outputs. Only present for Decile report types.
  - metric: This is the type of the metric – NetCashFlow, NetDeathBenefit, Premium, or Other.
  - statistics: An array of statistical values for the metric.
    - statistic: Type of the statistic, Mean, StdDev, Percentile
    - percentile: If a percentile, which percentile, as a fraction – i.e. 1 = 100%.
    - values: An array of values, the same length as the dates array – i.e. the value at position 1 corresponds to the date bucket in the dates array at position 1.
- simulations: This is present for cashflow report types. It will have the same length as the numOfSimulations requested.
  - simulation: The simulation this entry corresponds to, 1-based-index.
  - values: The cash flow values for this simulation. Will have the same length as the dates array for the output; i.e. value at position 1 corresponds to the date in the dates array at position 1.

Monte Carlo API Endpoint ​

Initial Request

Status Request

Download Request

Monte Carlo API Endpoint