Parameter Relationships

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

1. Parameters can have conditional relationships. In many cases, a parameter is relevant and further required 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. 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 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.

Conditional Relationships

Risk and coverage parameters become relevant and further required under specific conditions. Many parameters are required simply when you are creating an application for a specific product, while the relevance of others is determined by the value of a different parameter. Meaning the answer to one parameter yields another parameter.

Herald represents these relationships in the following ways:

Conditions in the Appendix

The Conditions column of the Appendix, lists the product condition and any additional conditions that must be met in order for the parameter to be required in a submission or bind order.

Conditions in the Dynamic Application

When using the Dynamic Application, there are three properties that can be used to determine if there is a relationship between parameters: [.h-code]affects_conditions[.h-code], [.h-code]affects_conditions_if[.h-code], and [.h-code]conditional_on[.h-code]. This information can be used to determine if you need to make a [.h-code]PUT[.h-code] [.h-endpoint-link]/applications/{application_id}[.h-endpoint-link] request to get the additional parameter in your application.

[.icon-circle-yellow][.icon-circle-yellow] After making a [.h-code]PUT[.h-code] [.h-endpoint-link]/applications/{application_id}[.h-endpoint-link] request, conditional questions are returned at the bottom of the Dynamic Application to ensure they are easily accessible after updates.

affects_conditions

Every parameter that can yield another parameter is assigned the property [.h-code]affects_conditions: true[.h-code]. This signals that the value submitted for this parameter affects whether or not another parameter will be required.

Consider parameter [.h-code]rsk_aml3_new_residential_construction[.h-code]:

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"
        ]
    }
}
 

Since [.h-code]affects_conditions: true[.h-code], an answer to [.h-code]rsk_aml3_new_residential_construction[.h-code] can yield another parameter, meaning you need to make a [.h-code]PUT[.h-code] [.h-endpoint-link]/applications/{application_id}[.h-endpoint-link] request.

affects_conditions_if

Herald can optionally enable  [.h-code]affects_conditions_if[.h-code] which provides additional details. The value of [.h-code]affects_conditions_if[.h-code] is a schema that adheres to the JSON Schema specification. If value of the present parameter is updated to something that conforms to the provided schema, then it will yield another parameter.

Consider the same parameter [.h-code]rsk_aml3_new_residential_construction[.h-code]:

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,
    "affects_conditions_if": {
       "type": "string",
       "enum": [
          "yes"
       ]
     },
     "schema": {
        "type": "string",
        "enum": [
            "yes",
            "no"
        ]
    }
 }
 

Given the additional information, you only need to make a [.h-code]PUT[.h-code] [.h-endpoint-link]/applications/{application_id}[.h-endpoint-link] request if the value for [.h-code]rsk_aml3_new_residential_construction[.h-code] is [.h-code]"yes"[.h-code].

[.icon-circle-yellow][.icon-circle-yellow] Let your Customer Success Representative know if you’d like this enabled or reach out to hello@heraldapi.com.

Special Cases:

• Multiple Conditions: When quoting for multiple products, there can be multiple conditions. For example, if gross sales ≥ $1M, Product A requires a follow-up question, and if gross sales ≥ $3M, Product B requires a follow-up question. Schemas are logically combined. In these cases, we logically combine the schemas and the [.h-code]affects_conditions_if[.h-code] schema in the example would only indicate  ≥ $1M.‍


Copied

{
  "type": "integer",
  "minimum": 1000000
}
 

• Complex Conditionality: For highly complex conditionalities, default [.h-code]affects_conditions_if: true[.h-code] with a simple schema may be used to avoid excessive complexity. For example, parameter [.h-code]rsk_b3jm_2017_naics_index[.h-code] involves different conditions for hundreds or thousands of specific NAICS index codes.

Copied

{ "type": "string" }
or 
{ "type": "array" }
or
{ "type": "object" }
etc
 

• Catch-All Schema: To manage complexity, a catch-all schema [.h-code]{ "type": "any" }[.h-code] may be used.

conditional_on‍

The [.h-code]conditional_on[.h-code] property returned with a parameter, contain the parameter(s) that caused it to be required. Multiple triggering parameters will be listed in priority order and the present parameter should be listed below those on your front end. If there are no parameters listed, then the parameters relevance does not depend on another parameter.

Consider parameter [.h-code]rsk_mrs0_new_residential_portion[.h-code]:

Copied

{
    "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.

‍