Risk and Coverage Parameters

Heralds version of underwriting, rating, and coverage questions.

We break out the questions of an application into two major categories: [.h-code-link]risk_values[.h-code-link] and [.h-code-link]coverage_values[.h-code-link].

  • Risk values are the values needed to describe a business and its operations, which will vary depending on the product(s) you are using. Each question that falls under the risk value umbrella is a [.h-code]risk_parameter[.h-code].
  • Coverage values describe the nature of coverage for an insurance policy, and vary by line of business and carrier product. Each question that falls under the coverage value umbrella is a [.h-code]coverage_parameter[.h-code].

Here are some examples:

risk_parameter_id Description
rsk_4b4z_business_name Business Name
rsk_t3cx_guest_shuttle_service Does the applicant provide a shuttle service for guests?
(conditional for certain industries)
rsk_z1ja_total_gross_sales Total Gross Sales
coverage_parameter_id Description
cvg_38ue_bop_effective_date Effective Date
(for a BOP policy)
cvg_0la5_gl_deductible Deductible
(for a GL policy)
cvg_lw22_cyb_computer_fraud_endorsement Computer Fraud Endorsement
(for a Cyber policy)

There are a few complexities when dealing with risk and coverage parameters.

It’s important to be aware of the following relationships and behaviors, which are documented in more detail below.

  1. Risk and coverage parameters can have parent/child relationships. Some parameters are children of parent parameters, and some child parameters can be parents to other parameters. For example, if an applicant performs work in multiple industries, they may need to submit revenue for each industry. In this case, the risk parameter for industry (class code) would be a parent of the risk parameter for revenue.
  2. Risk and coverage parameters can have conditional relationships. In many cases, a parameter is only relevant under certain conditions. For example, a carrier may need to ask if an applicant serves alcohol, but only if the applicant has provided a certain class code for an industry such as catering.
  3. The same risk or coverage parameter can have multiple values, appearing multiple times. Let’s imagine that an applicant has multiple locations- one in San Francisco and one in Los Angeles. In this case the “Location” risk parameter (a parent) should appear twice. We flag when this is a possible using [.h-code]creates_array: true[.h-code], and use [.h-code]instance[.h-code] to differentiate between each instance of the parameter.

Using Risk and Coverage Parameters

Whether you are building a static application or using Herald’s Dynamic Application, you’ll need to work with risk and coverage parameters. Every individual risk or coverage parameter has information associated with it, like the products it’s relevant for, any associated conditionality, the text for the question, the acceptable values….the list goes on.

If you are building a static application, you’ll have to get this information from the Appendix. The appendix serves as our question library, listing each question and all of its associated data. If you use the Dynamic Application, all of this information is provided in the [.h-endpoint-link]/applications[.h-endpoint-link] response.

While the information is the same, we’ll take a look at how this data is provided when using the Dynamic Application. Each risk and coverage parameter returned in the application response includes the following metadata:

Learn how to use these properties to build your application in our guide to building a front-end application.
Property Type Description
text String Description of the risk or coverage parameter.
affects_conditions Boolean True if the value potentially impacts the relevance of other risk or coverage values.
creates_array Boolean True if multiple values can be submitted with the same parameter ID. For example, since an application can have more than one location, the associated risk value will have creates_array: true.
instance String Unique identifier to distinguish different instances of risk or coverage parameter that have the same parameter ID. Ex: if you have 2 locations, they would have the instances location_1 and location_2 respectively. Only relevant when creates_array: true.
schema Object A JSON schema describing the expected value.
input_type String String meant to assist in customizing inputs beyond what is denoted by the JSON schema, e.g. 'short_text', 'long_text', 'address'.
required_for Array Array of actions that require this value. For example, an empty array [] represents an optional field, and ['quote'] means that the value is required to get a quote.
relevant_products Array Array of product IDs this risk or coverage parameter is relevant for. For example, ['prd_mc4r_herald_general_liability'] means that this parameter is relevant for the Herald General Liability product. Some risk and coverage parameters are relevant for all products, but some are unique to a certain product.
child_risk_values +
child_coverage_values
Array Signifies that the parameter is a parent, and the array contains all of the child parameters. The name of this property depends on if it is a risk or coverage value. Learn more about the parent/child relationship.

Relationships and unique behavior

Conditional Relationships

[.icon-circle-yellow][.icon-circle-yellow] When using the Dynamic Application, a parameter that can trigger conditional questions is given the property [.h-code]affects_conditions: true[.h-code].

Some risk parameters are only required under certain conditions. For every risk parameter, the Appendix specifies if it is conditional, and if so, lists its specific conditions. If a risk parameter does not have any conditions listed, then it is required whenever requesting any of that parameter’s relevant products.

If you’re using the Dynamic Application, every parameter that can potentially yield conditional questions is assigned the property [.h-code]affects_conditions: true[.h-code]. Conditional questions will only be returned if they become relevant after you submit a value. Let’s look at a case where you receive a [.h-code]risk_parameter[.h-code] for the applicants Home State. You would submit that value by sending in:

Copied

{
  "risk_values": [
    {
      "risk_parameter_id": "rsk_1rdc_home_state",
      "value": "MA",
    }
  ]
}
 

If the product you are using has conditional logic to ask every applicant in the state MA for their legal entity type, the following response would look like this:

Copied

{
  "application": {
    "id": "6e7c1486-9720-4135-b2b3-44e46df0404c",
    "status": "incomplete",
    "products": [
      "prd_mc4r_herald_general_liability"
    ],
    "risk_values": [
      {
        "risk_parameter_id": "rsk_1rdc_home_state",
        "value": "MA",
        "affects_conditions": true,
        ......
      },
      {
        "risk_parameter_id": "rsk_837r_legal_entity",
        "value": null,
        "schema": {
            "type": "string",
            "enum": [
                "Government/Public Entity",
                "Non-Profit Corporation",
                "Association",
                "Estate",
                "Individual",
                "C Corporation",
                "S Corporation",
                "General Partnership",
                "Limited Partnership",
                "Limited Liability Company",
                "Trust",
                "Sole Proprietorship",
                "Joint Venture",
                "Religious Organization",
                "Trustee"
            ]
        }
        ......
      },
    ]
  }
}
 

Parent/Child Relationships

[.icon-circle-yellow][.icon-circle-yellow] When using the Dynamic Application, a parent parameter contains the child parameters in a [.h-code]child_risk_values[.h-code] or [.h-code]child_coverage_values[.h-code] array.

Risk parameters describe the risks associated with the applicant. For example, the parameter “loss free years” describes the number of previous years that the applicant has gone consecutively without a loss. Here’s how we would reflect that an applicant has 3 loss free years:

Copied

{
  "risk_parameter_id": "rsk_h9hl_loss_free_years",
  "value": 3
}
 

By default, risk and coverage values are associated with the entire applicant. However, certain risks and coverages only relate to a subset of the applicant. These subsets are defined by “parent parameters”, and their associated “child parameters” denote that are only related to the level of their parent. A parent parameter has a [.h-code]risk_parameter_id[.h-code] (or [.h-code]coverage_parameter_id[.h-code]) and [.h-code]value[.h-code] as usual, with the addition of a [.h-code]child_risk_values[.h-code] (or [.h-code]child_coverage_values[.h-code]) that contains an array of child parameters and their values. 

If you’re using the Dynamic Application, these child parameters will come back in the response as they become relevant. These relationships are also documented in the Appendix.

[.icon-circle-blue][.icon-circle-blue] A child parameter can also be a parent. For instance, “class code” is a child of “Location”, but a parent for a variety of “rating basis” parameters.

For example, let’s say that this same applicant has several locations providing several services. Specifically, their Hill Valley location is associated with the class code [.h-code]96816[.h-code] (Janitorial Services). Since “Janitorial Services” describes the nature of the risk only at this location, we would show that information like this:

Copied

"risk_values":[
  {
  "risk_parameter_id": "rsk_h9hl_loss_free_years",
  "value": 3
  },
  {
    "risk_parameter_id": "rsk_yor8_location",
    "value": {
      "line1": "1640 Riverside Drive",
      "line2": "#3",
      "city": "Hill Valley",
      "state": "CA",
      "postal_code": "95420",
      "country_code": "USA"
    },
    "child_risk_values":[
      {
        "risk_parameter_id": "rsk_km7k_gl_class_code",
        "value": "96816"
      }
    ]
  }
]
 

Parameters that can have multiple values

[.icon-circle-yellow][.icon-circle-yellow] When using the Dynamic Application, a parameter that can have multiple values has the property [.h-code]creates_array: true[.h-code].

Some risk and coverage parameters can have multiple values. Parameters with this concept are given the property [.h-code]creates_array: true[.h-code], and each instance of that parameter is given a unique [.h-code]instance[.h-code] to distinguish between them.

The example we referenced earlier was an applicant that has multiple locations. In this case, the parameter [.h-code]rsk_yor8_location[.h-code], which is for Location, should appear twice. Today, we automatically generate and return the next incremental instance in the Dynamic Application for all [.h-code]creates_array: true[.h-code] parameters. A few things to note for these situations:

  • Each instance of the parameter will have [.h-code]creates_array: true[.h-code] to communicate that it can have multiple values.
  • The name of each [.h-code]instance[.h-code] is a unique identifier to distinguish different between instances. The name contains a description, and an index for it’s order in the series. If you have 2 locations, they would have instance [.h-code]location_1[.h-code] and [.h-code]location_2[.h-code]
  • At least one instance will have the value [.h-code]“required_for”: [”quote”][.h-code].This is because the parameter requires at least one value. If the parameter requires a minimum of one value, the first instance would be required for [.h-code][”quote”][.h-code] and the second would be required for [.h-code][ ][.h-code], since the second value is not required.

In this example, those parameters would look like this:

Copied

{	
	"risk_parameter_id": "rsk_yor8_location",
	"instance": "location_1"
	"creates_array": true,
	"required_for": ["quote"],
	"value": null,
	...
},
{	
	"risk_parameter_id": "rsk_yor8_location",
	"instance": "location_2"
	"creates_array": true,
	"required_for": [],
	"value": null,
	...
}
 

When formatting parameters that can have multiple values on a front-end application, it’s important to give an applicant the option to create new instances. Some applicants may have 1 location, and others may have 20. Read our guide on building a front-end application to learn more. You can also read our guide to using instances to map values to their correct instance.