Touchstone 11.0 API Reference
Touchstone 11.0 API Features
 Overview

Verisk first introduced the NGM financial engine in a limited capacity with Touchstone © 2021 and now fully integrated with Touchstone 2023 (11.0) (a.k.a. Touchstone NGM). In this release, the financial engine replaces the legacy financial engine. It was developed to keep pace with the increased demands and complexities of the (re)insurance markets, and with the need to incorporate more complex and realistic algorithms to modeling that were made possible with improved claims data, more detailed model data, more sophisticated algorithms, and increased computing power. With this release, clients can:

The new and improved engine includes a suite of enhancements discussed in detail in the following sections.

 Support for additional policy loss
The Detailed loss analysis module includes additional policy terms. Policy terms includes original methodologies and introduces the following enhancements.

We added the Aggregate Deductible and Aggregate Limit terms for the existing Layer and Sublimits classes in the AIR.Services.Common.Exposure.Data namespace.

Related method: SubmitDetailedLossAnalysis

Related request: SubmitDetailedLossAnalysisRequest XML

For information related to policy terms and conditions, refer to the Insurance term limits section in the NGM Financial guide on the Client Portal.

 Support for additional coverage terms and conditions

The Loss Analysis service client includes terms and conditions for:

We added the following new terms for the location, policy and layer, and facultative and treaty terms.

Namespace New Objects
AIR.Services.Common.Exposure.Data

Risk aggregation is performed by combining probability distributions with differing loss sizes. Therefore, deductibles and limits are applied directly on these distributions. For any analysis:

When you run:

Class Updated Objects

DetailedLossAnalysisOptions

ExposureConcentrationAnalysisOptions

The existing ApplyDeductibleBeforeLimit property in the DetailedLossAnalysisOptions and ExposureConcentrationAnalysisOptions classes is set to "true" always.

Related methods: SubmitDetailedLossAnalysis and SubmitRingExposureConcentrationAnalysis

Related requests: SubmitDetailedLossAnalysisRequest XML and SubmitRingExposureConcentrationAnalysisRequest XML

Refer to the NGM Change Management guide for coding exposures.

 Optimized performance

We updated the  MinimumCores and MaximumCores in the DetailedLossAnalysisOptions class that take into account the resource requirements for computing analyses. The updated Loss Engine uses cores in place of nodes for computing each analyses. To optimize memory usage, we recommend assigning cores in multiples of two for all analyses. To ensure backward compatibility in the updated engine, the API requests accept an odd number of Minimum or Maximum cores.  Internally, the API mechanism rounds the odd number to an even number of cores. That is for a request with one core, the engine rounds up to two cores; and for all other odd numbers of cores, the engine rounds down to the nearest even number. Note that the Touchstone user interface accepts only cores in multiples of two for all analyses. 

Refer to the Technical Specifications for more information.

 Enhanced the analysis log

The analysis log file now includes valuable information such as a detailed errors/warnings summary, construction and occupancy codes, and statistics of modeled exposures. You can use the activity analysis log to:

We updated the existing GetFile and GetFileTemplates responses to include the remapped construction and occupancy codes associated with a specific Loss Analysis template.

Related requests: GetFileRequest XML GetFileTemplatesRequest XML

 Support for specifying multiple loss modification templates

Previously, Touchstone allowed users to apply a single loss modification analysis template to the detailed loss analysis results during a loss modification analysis. Now you can apply a single template or multiple templates to the detailed loss analysis results using a new SubmitLossModAnalyses method. This enhancement enables you to control the loss modification factors for each template and apply specific templates for each analysis. From the Touchstone user interface:

 We introduced the following changes for the Loss Analysis service client:

Namespace New Method/Request/Response
AIR.Services.LossAnalysis.API  

SubmitLossModAnalyses (including SubmitLossModAnalysesRequest Class and SubmitLossModAnalysesResponse Class)

The new SubmitLossModAnalysesRequest class includes the following properties:

The new SubmitLossModAnalysesResponse class includes the following properties:

AIR.InformationModel.LossAnalysis

The LossModActivity Class includes the following:

Enhanced workflow to include one or more loss modification templates

To retrieve the existing templates including the event parameters, loss modification rules, and factors associated with a business unit in Touchstone, you can use the GetLossModTemplates method.

GetLossModTemplatesRequest
<GetLossModTemplates xmlns="AIR.Services.ObjectManagementService.Api">    
<request>        
<BusinessUnitSid xmlns="AIR.Services.Common.Api">1</BusinessUnitSid>
</request>    
</GetLossModTemplates>

You can then specify a single or multiple template SIDs when you configure the loss modification analyses.  

SubmitLossModAnalysesRequest
<LossModTemplateSids xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <d2p1:int>27</d2p1:int>
        <d2p1:int>28</d2p1:int>
        <d2p1:int>29</d2p1:int>
    </LossModTemplateSids>

Related request: SubmitLossModAnalyses

Reference: Review requests for the NGM Financial Engine

 Enhanced view of the loss results

You can specify save loss results by subperils in the detailed loss analyses.

Namespace New Objects
AIR.Services.LossAnalysis.Data

We updated the existing LossAnalysisOutputOptions class

Related request: SubmitDetailedLossAnalysisRequest XML

 Enhanced export of the loss results

You can export the detailed loss analysis results by subperils.

       
Namespace New Objects
AIR.Services.DataExport.Data

We implemented the following property in the existing LossAnalysisExportOptions class for enhanced viewing of the detailed loss analysis results:

Related method: SubmitLossAnalysisExport

Related request: SubmitLossAnalysisExportRequest XML

Reference: Review requests for the NGM Financial Engine

 Enhancement for demand surge

Touchstone now supports a new demand surge methodology for selected European models along with the existing demand surge functions. This new methodology calculates core economic demand surge factors by finding the largest industry loss event(s) for each country in each year of each model. If it meets a threshold, the calculated core economic demand surge factor is applied according to a model- and country-specific formula that is a function of that maximum annual industry loss. Additionally, a default or custom construction cost inflation factor for each country is added to the core economic Demand Surge Factor. The custom construction cost inflation factors can also be imported and exported across environments. Default industry exposure exclusions from the new demand surge calculations are auto, forestry, greenhouses, and offshore. Touchstone users can also customize new demand surge industry exposure exclusions by construction code, occupancy code, and user-supplied LOB.

Namespace New Objects
AIR.Services.LossAnalysis.Data

We added a new property for accounting the country-specific surge in the existing DemandSurgeRegionOption class.

Related method: SubmitDetailedLossAnalysis

Related request: SubmitDetailedLossAnalysisRequest XML

Reference: Review requests for the NGM Financial Engine

 Ability to import and export administrative boundaries

For many clients, the list of administrative boundaries has expanded over time. They define the pre-select geographic boundaries for the marginal impact analyses. The current workflow only allows users manually create or update individual administrative boundaries and then share boundaries with the new Touchstone environments or BUs. Therefore, reusing the existing administrative boundaries across different BUs has been time-consuming. To streamline and promote data exchange, we introduced a suite of enhancements for the Object Management service client. 

Namespace New Method/Request/Response
AIR.Services.ObjectManagement.Api

SubmitImportAdminBoundary (including SubmitImportAdminBoundaryRequest Class and SubmitImportAdminBoundaryResponse Class)

The new SubmitImportAdminBoundaryRequest class includes the following:

The ImportOptions class contains a ObjectImportOptions sub-class. This sub-class includes the following:

The new SubmitImportAdminBoundaryResponse class returns the following:

The SubmitImportObjectResultInfo class contains a OperationResultInfoBase sub-class.

We updated the existing GetAdminBoundariesResponse class to include a new Object SID property for each administrative boundary and the corresponding BU SID. 

SubmitExportAdminBoundary (including SubmitExportAdminBoundaryRequest Class and SubmitExportAdminBoundaryResponse Class)

The SubmitExportAdminBoundaryRequest class includes the following:

The ExportOptions class includes a ObjectExportOptions sub-class. This sub-class contains the following:

The SubmitExportAdminBoundaryResponse returns the following:

The SubmitExportObjectResultInfo class contains a OperationResultInfoBase sub-class.

The OperationResultInfoBase sub-class stores the user comments related to the import and export of the administrative boundaries. This sub-class stores the following:

Updated workflow for sharing the administrative boundaries across BUs and Touchstone environments

Import administrative boundaries

You can import administrative boundaries for a business unit into Touchstone using a new SubmitImportAdminBoundary method. Associate perils for each administrative boundary. Configure loss modification analyses with the imported boundaries in a different Touchstone environment or business unit (BU).

Related request: SubmitImportAdminBoundaryRequest XML

Identify a specific administrative boundary

You can use the existing GetAdminBoundaries method to identify a specific boundary name and its BU. 

Related request: GetAdminBoundariesRequest XML

Export administrative boundaries

You can export the administrative boundaries available in a BU using the new SubmitExportAdminBoundary method. And then use the exported boundaries to configure loss modification analyses in a different Touchstone environment or BU.

Related request: SubmitExportAdminBoundaryRequest XML

 Ability to import and export the Marginal Boundary Peril templates

Previously, clients had to manually update the parameters defined in the Boundary Peril template to use it in different business units or Touchstone environments. This process has been tedious. For audit reasons, some clients want to be able to share the Marginal Boundary Peril templates between different Touchstone environments and/or between different BUs in the same Touchstone environment.

Namespace New Method/Request/Response
AIR.Services.ObjectManagement.Api

SubmitImportMarginalImpactBoundaryPerilTemplate (including SubmitImportMarginalImpactBoundaryPerilRequest Class and SubmitImportMarginalImpactBoundaryPerilResponse Class)

The SubmitImportMarginalImpactBoundaryPerilRequest class contains the following:

The ImportOptions class includes a ImportOperationResultInfo sub-class. This sub-class stores the following:

The SubmitImportMarginalImpactBoundaryPerilResponse class contains the following:

SubmitExportMarginalImpactBoundaryPerilTemplate (including SubmitExportMarginalImpactBoundaryPerilRequest Class and SubmitExportMarginalImpactBoundaryPerilResponse Class)

The SubmitExportMarginalImpactBoundaryPerilRequest class includes the following:

The ExportOptions class includes a ExportOperationResultInfo sub-class. This sub-class stores the following:

The SubmitExportMarginalImpactBoundaryPerilResponse class returns the following

Updated workflow for sharing the Marginal Boundary Peril templates across BUs and Touchstone environments

Import Marginal Impact Boundary Peril templates

We implemented a new SubmitImportMarginalImpactBoundaryPerilTemplate method that lets you import the Marginal Boundary Peril template across business units and Touchstone environments.

Related request: SubmitImportMarginalImpactBoundaryPerilRequest XML

Export Marginal Impact Boundary Peril templates

You can export the existing Boundary Peril templates out of Touchstone using a new SubmitExportMarginalImpactBoundaryPerilTemplate method. The Boundary Peril template contains a list of the existing countries or regions mapped by sub-perils that is relevant to the geographic locations. You can configure the export job including the template name, destination business unit, and file path where you want to export the Peril objects template.

Related request: SubmitExportMarginalImpactBoundaryPerilRequest XML

 Perform marginal impact analyses by subperils

You can configure a marginal impact analysis with sub-perils for each location. After successful analyses, Touchstone generates summary exceedance probability data (aggregate and occurrence), event totals, and distributions based on the geographic resolution used to save the loss results for both sets of the marginal impact results. Therefore, you can:

       
Namespace New Objects
AIR.Services.Common.Data

We implemented the following new peril set codes for the existing MarginalImpactPerilSetCode class that you can specify for each contract and portfolio in a marginal impact analysis. 

Related request: SubmitMarginalImpactAnalysisRequest XML

Reference: Review requests for the NGM Financial Engine

 Perform geospatial analyses with custom boundaries

Custom boundaries are particularly helpful in assessing the impact of ongoing or new events such as wildfires, floods, or hurricanes. We enhanced our suite of geospatial APIs to help further streamline your workflow that use custom boundaries. This release includes a number of custom boundary related APIs to automate geospatial analyses. Thereby, clients licensing the geospatial module can now retrieve the existing custom boundaries, apply perils on custom boundaries, specify a single custom boundary or multiple boundaries, and configure geospatial analyses.

Namespace New Method/Request/Response/Objects
AIR.Services.ExposureConcentrationAnalysis.Data

The BoundingBox Class includes the following properties:

AIR.Services.ExposureConcentrationAnalysis.Api

GetCustomBoundaries (including GetCustomBoundariesRequest Class and GetCustomBoundariesResponse Class)

The GetCustomBoundariesRequest class inherits the Business Unit SID and SQL Instance SID.

The GetCustomBoundariesResponse class returns the following: 

GetCustomBoundariesDetails (including GetCustomBoundariesDetailsRequest Class and GetCustomBoundariesDetailsResponse Class)

The GetCustomBoundariesDetailsRequest class includes the following:

The GetCustomBoundariesDetailsResponse class returns the following:

SubmitCustomBoundaryExposureConcentrationAnalysis (including SubmitCustomBoundaryExposureConcentrationAnalysisRequest Class and SubmitCustomBoundaryExposureConcentrationAnalysisResponse Class)

The SubmitCustomBoundaryExposureConcentrationAnalysisRequest class includes the following:

The SubmitCustomBoundaryExposureConcentrationAnalysisResponse class includes the following:

GetCustomBoundaryResults (including GetCustomBoundaryResultsRequest Class and GetCustomBoundaryResultsResponse Class)

The GetCustomBoundaryResultsRequest class includes the following:

The GetCustomBoundaryResultsResponse class returns the following:

Retrieve a list of the custom boundaries

You can obtain the existing custom boundaries in polygon spatial shape available in a Touchstone BU using a new GetCustomBoundaries method.

Related request: GetCustomBoundariesRequest XML

Retrieve a specific custom boundary details

You can retrieve details of each custom boundary using a new GetCustomBoundariesDetails method. The response returns the custom boundary options including legend information, damage ratio, custom boundary name, unique SID, the spatial file type, and the peril associated within this boundary. You can reuse these predefined custom boundary details in various geospatial analyses

Related request: GetCustomBoundariesDetailsRequest XML

Configure geospatial analyses with a specific custom boundaries

The new SubmitCustomBoundaryExposureConcentrationAnalysis method enables you to configure the geospatial analyses with a single custom boundary or multiple custom boundaries. You can apply peril for each custom boundary and configure the geospatial analysis options such as the exposures, currency, and the result data source for storing the results of your geospatial analysis request job.

Related request: SubmitCustomBoundaryExposureConcentrationAnalysisRequest XML

Retrieve results of the geospatial analysis

The new GetCustomBoundaryResults method enables you to retrieve the accumulation results of geospatial analyses with custom boundaries. You can specify the pagination and order in which you want to sort the retrieved geospatial analysis results. The response returns the pagination details, accumulator type, gross, ground-up, and other terms.

Related request: GetCustomBoundaryResultsRequest XML

Support for additional deductibles

We made changes to our Geospatial engine to align more closely with the updated NGM loss engine. In the same way that we updated algorithms for detailed loss analysis, we included in geospatial analysis a revised logic for calculating the minimum maximum deductibles at both the layer and sub-limit levels.

In the same way that we updated algorithms for detailed loss analysis, we included in geospatial analysis a revised logic for calculating the minimum maximum deductibles at both the layer and sub-limit levels. Also, the updated Loss and Geospatial engines no longer take into account the AIR Default Behavior for residential contracts; this is because all residential contracts apply location deductibles before location limits.

Support for the bounding box capability

The bounding box functionality enables you to run the same exposures for different locations to evaluate limits and marginal impact. Since this functionality was not available in our public API services, clients had to depend on a workaround process where they identified grid points for locations of interest and then had to manually maintain a list of these grid points to include in their automated workflow. This workaround was time-consuming to perform on production environments and allowed users to add up to only 50,000 grid locations per analysis. To solve these limitations, we created a new BoundingBox class in the AIR.Services.ExposureConcentrationAnalysis.Data namespace. This class includes the Point1LatitudePoint2LatitudePoint1Longitude, and Point2Longitude parameters that you can specify and configure the geospatial analyses.

Related request: SubmitRingExposureConcentrationAnalysisRequest XML

 Export exposures between Touchstone and Touchstone Re

Clients export aggregate exposure information from Touchstone, including sums insured, risk count, and premium data, into a format that can be imported into Touchstone Re for further downstream analysis. The current workflow allows you to export the aggregate information only via the Touchstone user interface (UI). Therefore, the exported data from the Touchstone UI requires manual intervention to feed into automated workflow. To address this gap in the data transfer process, we implemented a more comprehensive workflow for the Data Export service client.

Namespace New Method/Request/Response/Objects
AIR.Services.DataExport.Api

SubmitExportUnicede2 (including SubmitExportUnicede2Request Class and SubmitExportUnicede2Response Class)

The SubmitExportUnicede2Request class includes the following:

The ExportOptions class contains a ExportUnicede2Options sub-class for storing the exposure data that you want to export to a UNICEDE/2 file.

The SubmitExportUnicede2Response class returns the following:

SubmitAssociateExposureToCompany (including SubmitAssociateExposureToCompanyRequest Class and SubmitAssociateExposureToCompanyResponse Class)

The SubmitAssociateExposureToCompanyRequest class includes the following:

The ExportOptions class contains a AssociateExposureToCompanyOption sub-class for storing the Touchstone Re company information that you want to associate with Touchstone aggregate exposures.                

The SubmitAssociateExposureToCompanyResponse class returns the following:

AIR.Services.DataExport.Data

The ExportUnicede2Options Class contains the following:

Note: The TargetSid property contains the exposure data that you want to export to UNICEDE/2 file. The TargetSid property must NOT contain blank spaces, null, commas, or the following special characters: ?©•#/<>‐&°()+:;'!". You must specify a valid Exposure View SID associated with exposures in the SubmitExportUnicede2Request class.

AIR.Services.DataExport.Data

The AssociateExposureToCompanyOption Class contains the following:

AIR.Services.DataExport.Api

GetUnicede2LOBByCountry (including GetUnicede2LOBByCountryRequest Class and GetUnicede2LOBByCountryResponse Class)

The GetUnicede2LOBByCountryRequest  class includes the following:

The GetUnicede2LOBByCountryResponse class includes the following:

AIR.Services.ExposureViewSummary.Api

GetUserLineOfBusinessesByCountry (including GetUserLineOfBusinessesByCountryRequest Class and GetUserLineOfBusinessesByCountryResponse Class)

The GetUserLineOfBusinessesByCountryRequest class inherits the Business Unit SID and SQL Instance SID.

The GetUserLineOfBusinessesByCountryResponse class returns the following:

Transfer data across BUs and Touchstone environments

You can export aggregate exposure information to a UNICEDE/2 file using the SubmitExportUnicede2 method. This method stores the export options such as company data, the user-provided line of business, the source folder path containing the aggregate exposures you want to export, and the destination file path to which you want to export the aggregate exposure data.

Depending on where you placed the exported exposures, you can either associate the exposures directly with a Touchstone Re company or import the UNICEDE/2 file into Touchstone Re if you license both the applications. The file extension for exposure data that you export to UNICEDE/2 format is .txt. For more information about the UNICEDE/2 format, visit www.unicede.com.

Related request: SubmitExportUnicede2Request XML

Associate Touchstone exposures with Touchstone Re

You can associate the Touchstone exposures to companies in Touchstone Re using a new SubmitAssociateExposureToCompany method. This method includes company association data such as the market share, loss set name, and the company BU in Touchstone Re with which that you want to associate the Touchstone exposures.

Related request: SubmitAssociateExposureToCompanyRequest XML

Support for the custom lines of business in UNICEDE/2

This release includes the following enhancements for managing exposures in UNICEDE/2.

Related requests: GetUnicede2LOBByCountryRequest XML GetUserLineOfBusinessesByCountryRequest XML

 Downgrade the Touchstone exposure database

Previously, we provided clients with database downgrade scripts to run outside the Touchstone user interface, which allowed clients to downgrade their exposure databases from the current version to a prior version. However, clients with numerous exposure databases found that their downgrades using the database scripts were time-consuming. Some clients always want to be on the latest version of Touchstone so that they can take advantage of new models and functionality. At the same time, these clients also had vendors who were on different Touchstone release versions. Now clients can use the SubmitDowngradeDatabases method to downgrade their current version of the exposure databases to a prior version. You cannot use the public API service to downgrade the Touchstone Result database. 

Namespace New Method/Request/Response
AIR.Services.DataSourceManagement.Api

SubmitDowngradeDatabases (including SubmitDowngradeDatabasesRequest Class and SubmitDowngradeDatabasesResponse Class)

The SubmitDowngradeDatabasesRequest class contains the following:

The SubmitDowngradeDatabasesResponse class returns the following:

Related request: SubmitDowngradeDatabasesRequest XML