Heralds version of underwriting, rating, and coverage questions.

When requesting a quote or policy, institutions gather information on the business to determine eligibility and calculate pricing. With Herald, this information is collected in the form of parameters, which are relevant for applications and bind applications.

  • Parameters in applications: Used to collect information related to the business’s operations, exposure to risks, and desired coverages. This information is sent to an institution to request a quote.
  • Parameters in bind applications: Used to collect any remaining information required to get a policy. This can include contact information, payment terms for the policy, and more. Information that was optional to quote typically becomes required to get a policy.

Types of Parameters

Every parameter is documented in our Appendix, but relevant parameters are provided dynamically through [.h-endpoint-link]/applications[.h-endpoint-link] and [.h-endpoint-link]/bind_applications[.h-endpoint-link].  We categorize parameters into one of three categories: [.h-code]risk_values[.h-code], [.h-code]coverage_values[.h-code], and [.h-code]admin_values[.h-code].

[.icon-circle-blue][.icon-circle-blue] Admin values are currently only relevant in bind applications, unless you are leveraging our proxies feature in beta.
Type Description Relevance
risk_values The values needed to describe a business and its operations. Each question that falls under the risk value umbrella is a risk_parameter Applications, Bind Applications
coverage_values The values that describe the nature of coverage for an insurance policy. Each question that falls under the coverage value umbrella is a coverage__parameter Applications, Bind Applications
admin_values The values needed from an administration perspective, such as the brokers license number or billing terms for a policy. Each question that falls under the admin value umbrella is an admin__parameter Bind Applications

All parameters, regardless of the type of parameter, behave the same. Make sure to read about the relationships and complexities of parameters before creating applications. The set of parameters needed to get a quote or a policy which will vary depending on the product(s) you are using. Here are some examples:

Risk Values

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 Values

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)

Admin Values

(Only relevant for bind applications)

admin_parameter_id Description
adm_6evk_surplus_broker_license_number Surplus broker's license number
adm_5k6f_surplus_brokerage_name Surplus line brokerage name

Using Parameters

Getting quotes and policies from any institution involves submitting values for risk, coverage, and admin parameters. Every individual parameter has metadata associated with it such as the products it is relevant for, the text to render on screen, acceptable values and validation…the list goes on.

If you are building a static experience, 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. However, you can get relevant parameters for the products you are using by creating applications and bind applications.

Let’s take a look at an example of how risk and coverage parameters are shown when creating an application to get a quote. You can create an application by submitting a product, or multiple products, to [.h-endpoint-link]/applications[.h-endpoint-link] like this:

POST /application

  "products": [

The response would include all relevant parameters to get a quote for this product.


  "application": {
    "id": "6e7c1486-9720-4135-b2b3-44e46df0404c",
    "status": "incomplete",
    "products": [
    "risk_values": [
        "risk_parameter_id": "rsk_m4p9_insured_name",
        "value": null,
        "text": "Insured name",
        "input_type": "short_text",
        "relevant_products": [
        "affects_conditions": false,
        "required_for": [
        "schema": {
          "type": "string"
    "coverage_values": [
        "coverage_parameter_id": "cvg_14fb_gl_damages_premises_limit",
        "value": null,
        "text": "Damages to Premises Rented Limit",
        "input_type": "integer",
        "relevant_products": ["prd_mc4r_herald_general_liability"],
        "affects_conditions": false,
        "required_for": [],
        "schema": {
          "type": "number",
          "minimum": 0,
          "maximum": 5000000

Read our full guides on creating applications and creating bind applications.

Parameter Metadata

The following metadata is provided for every parameter when creating applications and bind applications (this information is also available in the Appendix):

[.icon-circle-blue][.icon-circle-blue] Learn how to use these properties to build your application in our guide to building a front-end application.
Property Type Description
parameter_text object Object containing agent-facing and applicant-facing text for the parameter that you can render on a front-end..
affects_conditions Boolean true if the value potentially impacts the relevance of other values.
affects_conditions_if Object JSON schema describing what values can cause new parameters to become relevant. Only returned if affects_conditions is true. Can be used to minimize PUT requests, by only make a PUT when the submitted value meets the conditions described in this object.
conditional_on Object Array of risk parameters that triggered this question, only relevant if the parameter is conditional on another parameter.
section String String meant to assist in organizing similar parameters together in sections.
creates_array Boolean true if multiple values can be submitted for the same parameter. 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 parameters that have the same 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, select_one, address. Full list of input types.
required_for Array Array of concepts that require this value. For example, an empty array [] represents an optional field, ["quote"] means that the value is required to get a quote, ["policy"] means the value is required to get a policy. If a parameter optional to get a quote but required to get a policy, it will appear in the application as required for ["policy"].
relevant_products Array Array of product id's the parameter is relevant for. For example, ['prd_mc4r_herald_general_liability'] means that this parameter is relevant for the Herald General Liability product. Some parameters are relevant for all products, but some are unique to a certain product.
child_risk_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. Currently, there are no admin_parameters with parent/child relationships. Learn more about the parent/child relationship.


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 in our parameter relationships doc.

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