How To Use Instances

Learn how to submit values for parameters that have multiple instances.

As discussed in our risk and coverage parameter doc, some risk and coverage parameters can have multiple values. In the Dynamic Application, we communicate that a parameter can have multiple values using 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.

Let’s look at an example where an applicant hasmultiple locations. The applicant has a manufacturing location in Los Angeles, and a sales and marketing center in San Francisco. In this example:

  • The parameter [.h-code]rsk_yor8_location[.h-code] for Location appears twice. The first contains values for the Los Angeles address, and the second for the San Francisco address.
  • Each instance of location has [.h-code]rsk_km7k_gl_class_code_by_location[.h-code] for class code nested below it. The location in Los Angeles has a class code for manufacturing below it, and the location in San Francisco has 2 class codes below it- for marketing and for sales.
  • Each instance of class code also has a child nested below it, because each instance of class code has a conditional question for exposure basis- either total sales for that class code or total payroll for that class code.

Here’s how Herald expects to receive that information when using the Dynamic Application endpoint.

POST /applications
Copied

{
  "risk_parameter_id": "rsk_yor8_location",
  "value": {
      "line1": "3325 Wilshire Blvd",
      "city": "Los Angeles",
      "state": "CA",
      "postal_code": "90010",
      "country_code": "USA"
  },
  "child_risk_values": [
    {
      "risk_parameter_id": "rsk_km7k_gl_class_code_by_location",
      "value": "53731",
      "child_risk_values": [
        {
            "risk_parameter_id": "rsk_w72m_gross_sales_by_gl_class_code",
            "value": 1000000
        }
    ]
    }
  ]
},
{
  "risk_parameter_id": "rsk_yor8_location",
  "value": {
      "line1": "308 Eddy St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94102",
      "country_code": "USA"
  },
  "child_risk_values": [
    {
      "risk_parameter_id": "rsk_km7k_gl_class_code_by_location",
      "value": "16900",
      "child_risk_values": [
        {
            "risk_parameter_id": "rsk_w72m_gross_sales_by_gl_class_code",
            "value": 1000000
        }
      ]
    }
  ]
}
 

Using instances with the Dynamic Application

Let’s go through the same example, but in a case where you haven’t collected this information yet. When you create the application, you’ll receive a blank application with all of the relevant risk and coverage parameters. You you’re using a surplus General Liability product, like we are in this example, that response will include:

  • 2 blank instances for Location
  • 2 blank instances of class code, one nested below each location.

Here’s how that information would look in the response.

Copied

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

When using the Dynamic Application you need to submit the [.h-code]child_risk_values[.h-code] with the correct parent, in real time. In order to map these values to the proper parent, you can use [.h-code]instance[.h-code]. In the response above, you can see the following:

  • Every instance of location and class code has the property [.h-code]creates_array: true[.h-code]. This is always the case for parameters that can have multiple values.
  • Each parameter has an [.h-code]instance[.h-code], containing a description and the index of its order in the series. The first instance of location is [.h-code]location_1[.h-code], and the second is [.h-code]location_2[.h-code].
  • The instance for the child parameter, class code, also contains the parent parameter. The class code under [.h-code]location_1[.h-code] is [.h-code]location_1.gl_class_code_by_location_1[.h-code], and the second is [.h-code]location_2.gl_class_code_by_location_1[.h-code].
  • The first instance of each unique parameter also has [.h-code]required_for: ["quote"][.h-code], while the following instances have [.h-code]required_for: [ ][.h-code]. This means that a minimum of 1 value is required for each parameter. The second, and any further instances, are optional.
When rendering this on screen, you’ll want to want to visually place the child parameters below the parent, and you may want to hide the 2nd [.h-code]instance[.h-code] of all [.h-code]creates_array: true[.h-code] parameters. All of these instructions are documented in our guide to building a front end.

As you collect these values on your front-end, you’ll need to submit each value in the [.h-code]child_risk_values[.h-code] beneath the parent.

  • To submit a class code for the Los Angeles address, you would map it under [.h-code]child_risk_values[.h-code] below the correct [.h-code]instance: location_1[.h-code]
  • To submit a class code for the San Francisco address, you would map it under [.h-code]child_risk_values[.h-code] below the correct [.h-code]instance: location_2[.h-code]

Your [.h-code]PUT[.h-code] request to [.h-endpoint-link]/application/{application_id}[.h-endpoint-link] should look like this:

POST /applications
Copied

{
  "risk_parameter_id": "rsk_yor8_location",
  "value": {
      "line1": "3325 Wilshire Blvd",
      "city": "Los Angeles",
      "state": "CA",
      "postal_code": "90010",
      "country_code": "USA"
  },
  "child_risk_values": [
    {
      "risk_parameter_id": "rsk_km7k_gl_class_code_by_location",
      "value": "53731",
    }
  ]
},
{
  "risk_parameter_id": "rsk_yor8_location",
  "value": {
      "line1": "308 Eddy St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94102",
      "country_code": "USA"
  },
  "child_risk_values": [
    {
      "risk_parameter_id": "rsk_km7k_gl_class_code_by_location",
      "value": "16900",
    }
  ]
}
 

Standard to the rest of the Dynamic Application flow, documented in our step-by-step guide, you’ll receive any conditional questions after submitting the class codes which have [.h-code-link]affects_conditions: true[.h-code-link]. You would follow the same instructions above to map the conditional question below a class code. If you need to submit a value such as payroll for the 1st class code below the 2nd location, you would map it as a child_risk_value below the instance [.h-code]location_2.gl_class_code_by_location_1[.h-code].

How instances are generated

Each instance is automatically generated by Herald. The [.h-code]instance[.h-code] value has a relevant description based on the question, and a number based on its instance in the series. Submitting 4 individual values for location would automatically assign the instances [.h-code]location_1[.h-code], [.h-code]location_2[.h-code], [.h-code]location_3[.h-code], and [.h-code]location_4[.h-code].

You do not have to submit [.h-code]instance[.h-code] in your request. Submitting this value will be ignored by Herald.