Risk and Coverage Parameters

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

• 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:

Complexities

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 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.
2. 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.
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.

‍

‍

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 and coverage parameters are only required under certain conditions. For every parameter, Herald specifies the conditions that make a conditional parameter relevant in the conditions column of the Appendix, and in the [.h-code]conditional_on[.h-code] property of the Dynamic Application. If a parameter does not have any conditions listed, then it is always relevant for that product.

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. If a conditional parameter is returned, the [.h-code]conditional_on[.h-code] property will contain the parameter(s) that caused it to be relevant. Some things to note:

• Parameters that may yield conditional questions: If a parameter has [.h-code]affects_conditions: true[.h-code], this means the risk or coverage parameter may yield conditional questions. This is dependent on the value you submit for the parameter.
• Parameters that are conditional: If a parameter is conditionally relevant based on the value for another parameter, the property [.h-code]conditional_on[.h-code] will show you which parameter(s) triggered this parameter. If a parameter is conditional on more than one value, all of the parameters that triggered this question will be listed in the [.h-code]conditional_on[.h-code] object in a priority order defined by Herald. The [.h-code]conditional_on[.h-code] value can be used to render conditional questions below the question that triggered it on your front end.
• Sort Order: Herald will return all conditional questions at the bottom of the dynamic app. This means that every time you update the application, Herald will determine which new questions need to be answered and sort them at the bottom, making them easy to find.

Let’s walk through an example where [.h-code]rsk_aml3_new_residential_construction[.h-code] triggers a conditionally relevant value.

Copied

{
    "risk_parameter_id": "rsk_aml3_new_residential_construction",
    "value": null,
    "text": "Does the applicant work on any new residential construction?",
    "input_type": "select_one",
    "affects_conditions": true,
    "schema": {
        "type": "string",
        "enum": [
            "yes",
            "no"
        ]
    }
}
 

As you can see, the value for [.h-code]affects_conditions[.h-code] is [.h-code]true[.h-code], which means that it may yield additional parameters based on the value the applicant submits. Let's say the applicant does work on new residential construction, so we submit the value [.h-code]yes[.h-code] and update the application using [.h-code]PUT[.h-code].

Copied

{
    "risk_parameter_id": "rsk_aml3_new_residential_construction",
    "value": "yes"
}
 

The Application response will now include the additional, conditionally relevant risk parameter [.h-code]rsk_mrs0_new_residential_portion[.h-code] at the bottom because of the value we submitted. As you can see below, this risk parameter has the [.h-code]conditional_on[.h-code] property with the value [.h-code]rsk_aml3_new_residential_construction[.h-code], because that is the parameter that triggered it. Since the conditional question is question is clearly related to parameter that triggered it, you can choose to use this value to format the new question below the parameter that triggered it on your front-end. Read more in our guide to building a front-end.

Copied

{
    "risk_parameter_id": "rsk_aml3_new_residential_construction",
    "value": "yes",
    "affects_conditions": true,
    ...
},
...
{
    "risk_parameter_id": "rsk_mrs0_new_residential_portion",
    "value": null,
    "text": "Approximate portion of residential work that is new construction (versus renovation):",
    "input_type": "select_one",
    "affects_conditions": false,
    "conditional_on": {
        ["rsk_aml3_new_residential_construction"]
    },
    "schema": {
        "type": "string",
        "enum": [
            "more than 75% new",
            "50% - 75% new",
            "25% - 50% new",
            "10% - 25% new",
            "less than 10% new"
        ]
    }
}
 

‍

‍

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 with 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 above involved an applicant that has multiple locations. In this case, the application should include multiple instances of the parameter for location, [.h-code]rsk_yor8_location[.h-code].

When using the Dynamic Application, the application only returns 1 instance of each parameter by default. Each carrier only requires 1 instance of a parameter, but additional instances are optional to support applicants with multiple locations, class codes, past claims, etc. You can create additional instances by following the steps in our guide to using instances.

A few things to note for these situations:

• Each instance of a parameter that supports multiple values has the property [.h-code]creates_array: true[.h-code].
• 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 its 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.

Location is a parameter that can have multiple values, and only 1 location is required by the carrier. In the application response, the parameter for location would look like this:

Copied

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

If the applicant has 2 locations, you would create an additional instance of location. As documented above, the second location would have a unique instance, but would not be required for a quote. The parameters for location 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. Learn more in our guide to using instances.