Creating Custom Lines of Business in BindHQ

Last updated: July 5, 2025

Applies to:

  • Admins
  • Heads of Underwriting building new insurance products 
  • IT professionals and consultants aiding clients in launching new products
Last Updated: April 2025

 

Introduction

There are several types of lines of business that are available by default in BindHQ like General Liability, Commerical Property and Homeowners which have like predefined screens and functionality.

We offer several ancillary lines of business that, while they may not require extensive details, provide the ability to capture essential coverage information.

As of 2024 BindHQ now allows the creation of Custom Lines of Business to better accommodate the unique needs of Excess and Surplus lines insurance companies. This feature uses a JSON-based schema to define how forms are structured, validated, and rendered, enabling the customization of product forms for different lines of business.

The JSON schema configures key details such as field labels, data types, input validation, and how different sections and fields in an insurance application are grouped and displayed. It ensures consistency and flexibility in designing forms that meet the specific requirements of each insurance product.

Key Components

1. Sections 

Sections, are logical groupings of fields that may represent a section of the form, such as "Driver Information" or "Coverage Details." Each collection contains one or more rows, where each row holds one or more fields.

Example: Motor Truck Cargo Schedule

 

 

{
"cargo_schedule": {
  "label": "Cargo Schedule",
    "rows": [
     {
      "cargo_items": {
        "type": "collection",
        "label": "Cargo Items",
         "rows": [
          {
          "type_of_cargo": {
           "type": "choice",
           "label": "Type of Cargo Hauled",
              "options": {
                "dry_bulk": "Commodities Dry Bulk",
                "flatbed": "Commodities Flatbed"
               },
               "width": 6,
               "required": true,
               "expanded": false,
               "multiple": true,
               "help": null
               }
            }
          ]
        }
     }
    ]
  }
}
 
2. Fields

A field is an input element within a row and can be of various types, such as text, choice, number, or checkbox. Each field in the JSON schema is defined by several attributes like type, label, width, required, and help.

Example: Number of Years' Experience Field

 
 
{
  "years_experience_trucking": {
    "type": "number",
    "label": "Number of Years' Experience in the Trucking Business",
    "width": 6,
    "required": true,
    "scale": 0,
    "help": null
  }
}

 

Common Field Types

  • Text: A standard text input field.
  • Number: Numeric input with optional precision (scale).
  • Money: Numeric input formatted for currency values.
  • Choice: Dropdown or radio button selection fields, often requiring predefined options.
  • Checkbox: A boolean toggle for yes/no responses.
  • Collection: A group of nested fields that represent repeatable data entries (e.g., vehicles, drivers).

Example: Choice Field

 
 
{
  "cargo_deductible_requested": {
    "type": "choice",
    "label": "Cargo Deductible Requested",
    "options": {
      "one_thousand": "$1,000",
      "two_thousand_five_hundred": "$2,500"
    },
    "width": 6,
    "required": true,
    "expanded": false,
    "multiple": false,
    "help": null
  }
}

 

3. Rows and Widths

Each row in a section defines how fields are laid out horizontally. Fields within a row must have a width between 1 and 12, and the total width of fields in a single row must not exceed 12.

Example: Row with Two Fields

 
 
{
  "mc_number": {
    "type": "text",
    "label": "MC Number",
    "width": 6,
    "required": true,
    "help": null
  },
  "dot_number": {
    "type": "text",
    "label": "DOT Number",
    "width": 6,
    "required": true,
    "help": null
  }
}

 

4. Collections

A collection allows for repeating a set of fields. This is often used when a form requires multiple similar entries, such as adding multiple vehicles or drivers.

Example: Driver Collection

 
 
{
  "driver_items": {
    "type": "collection",
    "label": "Drivers",
    "rows": [
      {
        "driver_name": {
          "type": "text",
          "label": "Driver Name",
          "width": 6,
          "required": true,
          "help": null
        },
        "date_of_birth": {
          "type": "date",
          "label": "Date of Birth",
          "width": 6,
          "required": true,
          "help": null
        }
      }
    ]
  }
}

 

5. Handling Choice Fields

For fields that allow users to make selections, the options attribute is used. Each option is defined with a key and a label. Note that keys cannot start with numbers to avoid validation errors.

Correct Example:

 
 
{
  "cargo_deductible_requested": {
    "type": "choice",
    "label": "Cargo Deductible Requested",
    "options": {
      "one_thousand": "$1,000",
      "two_thousand_five_hundred": "$2,500"
    },
    "width": 6,
    "required": true,
    "expanded": false,
    "multiple": false,
    "help": null
  }
}

 

6. Key Constraints and Common Errors

  • Field Labels: Labels must be non-empty strings.
  • Width Constraint: The sum of field widths in a row must not exceed 12.
  • Non-Empty Strings: Attributes like label and type must not be empty.
  • Choice Options: Keys in choice fields must start with a lowercase letter, not numbers.

Example of Incorrect JSON (Numeric Keys)

 
 
{
  "cargo_deductible_requested": {
    "type": "choice",
    "label": "",
    "options": {
      "1000": "$1,000",  // Incorrect: Numeric keys are not allowed
      "2500": "$2,500"
    },
    "width": 6,
    "required": true,
    "expanded": false,
    "multiple": false,
    "help": null
  }
}

 

7. Error Handling

While constructing the JSON schema, it's important to watch out for:

  • Invalid data types: Ensure that fields like label are non-empty strings.
  • Options format: Avoid numeric keys in choice fields.
  • Required fields: Ensure that fields marked as required are properly configured with labels and types.

 

________________________________________________________________________

 

Optional Fields

 

Using help and default

  • help is used to provide users with additional guidance on what to input in a field. It is optional and often displayed as small text or a tooltip.
  • default is used to pre-populate a field with a value. This value differs depending on the field type (e.g., strings for text fields, booleans for checkboxes, and specific values for choice fields).

This ensures that users are guided throughout the form-filling process and that commonly used values can be pre-selected, reducing friction and potential errors.

 

Help Text (help)

The help attribute provides additional context or guidance for the user in the form of a tooltip or small descriptive text next to the input field. This is optional and can be very useful for explaining what kind of data should be entered or why a certain field is important.

  • Type: String (can be null if not needed).
  • Purpose: Offers additional clarity or instructions to the user.

Example:

 
 
{
  "years_experience_trucking": {
    "type": "number",
    "label": "Number of Years' Experience in the Trucking Business",
    "width": 6,
    "required": true,
    "scale": 0,
    "help": "Enter the number of years of experience in full years only."
  }
}

Here, the help text instructs the user that they should only enter whole years in the field.

Default Values (default)

The default attribute specifies a pre-selected or pre-filled value for a field. This is useful when you want to provide users with a starting point or common value, saving time or reducing errors from manual input.

  • Type: Depends on the field type (could be a string for text fields, a boolean for checkboxes, or a value matching one of the keys in a choice field).
  • Purpose: Pre-populates the field with a value to make data entry easier.

For Text, Number, and Money Fields:

  • Default is the initial value displayed in the input field.

Example for a Number Field:

json
 
{
  "years_experience_trucking": {
    "type": "number",
    "label": "Number of Years' Experience in the Trucking Business",
    "width": 6,
    "required": true,
    "scale": 0,
    "default": "5",
    "help": "Enter the number of years of experience."
  }
}

Here, the field will be pre-filled with the value 5.

For Choice Fields:

  • Default must be one of the keys from the options map.

Example for a Choice Field:

 
 
{
  "cargo_deductible_requested": {
    "type": "choice",
    "label": "Cargo Deductible Requested",
    "options": {
      "one_thousand": "$1,000",
      "two_thousand_five_hundred": "$2,500"
    },
    "width": 6,
    "required": true,
    "expanded": false,
    "multiple": false,
    "default": "one_thousand",
    "help": "Select the cargo deductible requested."
  }
}

In this example, the choice field will have the $1,000 option selected by default.

For Checkbox Fields:

  • Default is a boolean, indicating whether the checkbox is selected (true) or not (false).

Example for a Checkbox Field:

 
 
{
  "agree_to_terms": {
    "type": "checkbox",
    "label": "Agree to Terms and Conditions",
    "width": 6,
    "required": true,
    "default": true,
    "help": "Please agree to the terms and conditions."
  }
}

In this case, the checkbox will be selected (true) by default.

 

Layout

 

Field Widths and Layout Constraints

When configuring fields within a row, the width attribute defines how much horizontal space each field will take. The layout is based on a 12-column grid, and each field’s width must be a multiple of 3. This design ensures that fields are laid out consistently and align properly across the form.

Key Rules:

  1. Field Width Values: Supported widths are 3, 6, 9, and 12. This represents how much of the 12-column grid each field will occupy.
  2. Sum of Field Widths: The total width of all fields in a single row cannot exceed 12. If the combined width of the fields exceeds 12, an error will occur.
  3. Multiple of 3: Field widths must be multiples of 3 (3, 6, 9, or 12), ensuring proper layout in the form.

Examples of Field Width Usage

Example of Two Fields in One Row (Each Taking Half the Row)

 
 
{
"mc_number": {
"type": "text",
"label": "MC Number",
"width": 6,
"required": true,
"help": null
},
"dot_number": {
"type": "text",
"label": "DOT Number",
"width": 6,
"required": true,
"help": null
}
}

In this example:

  • Both fields (MC Number and DOT Number) are given a width of 6, meaning they take up half of the row each (totaling 12).

Example of a Single Field Spanning the Full Width of the Row

 
 
{
  "gross_receipts": {
    "type": "money",
    "label": "Gross Receipts",
    "width": 12,
    "required": true,
    "help": "Enter the total gross receipts."
  }
}

In this example:

  • The gross_receipts field occupies the full width of the row (12 columns).

Example of Three Fields in One Row

 
 
{
  "truck_weight": {
    "type": "number",
    "label": "Truck Weight",
    "width": 3,
    "required": true,
    "help": "Enter the weight of the truck."
  },
  "truck_value": {
    "type": "money",
    "label": "Truck Value",
    "width": 6,
    "required": true,
    "help": "Enter the value of the truck."
  },
  "truck_year": {
    "type": "number",
    "label": "Truck Year",
    "width": 3,
    "required": true,
    "help": null
  }
}

In this example:

  • The truck_weight, truck_value, and truck_year fields are laid out in a single row.
    • truck_weight takes up 3 columns.
    • truck_value takes up 6 columns.
    • truck_year takes up 3 columns.
  • The total width of the row equals 12 (3 + 6 + 3), ensuring the layout works correctly.

Constraints and Errors:

  • Exceeding 12 columns: If the sum of the fields’ widths in a row exceeds 12, the form will throw an error and will not display properly.
  • Non-multiples of 3: Any width that is not a multiple of 3 (such as 5, 7, or 8) will also cause an error, as the layout system requires fields to fit into a 12-column grid based on 3-column increments.

Example of an Invalid Field Configuration (Exceeds 12 Columns):

 
 
{
  "mc_number": {
    "type": "text",
    "label": "MC Number",
    "width": 9,
    "required": true,
    "help": null
  },
  "dot_number": {
    "type": "text",
    "label": "DOT Number",
    "width": 6,  
    "required": true,
    "help": null
  }
}

In this example:

  • The total width of mc_number and dot_number is 9 + 6 = 15, which exceeds the allowable 12 columns, leading to a validation error.

Recap of Supported Widths

  • Valid field widths: 3, 6, 9, and 12.
  • Row width limit: The sum of all field widths in a row cannot exceed 12.
  • Multiple of 3 rule: Field widths must always be a multiple of 3 to align with the grid system.

This ensures that the layout of fields remains consistent and user-friendly across the application.

 

 

Conclusion

BindHQ's custom line of business feature allows you to configure highly flexible and structured forms using JSON. By properly defining sections, fields, and collections, you can ensure that your product forms are both functional and user-friendly. Make sure to follow the rules for field widths, identifiers, and choice field options to avoid common errors during form configuration.