Bind Applications: Step-by-Step

A bind application contains all of the relevant information required to bind a specific quote, along with all of the information needed to render and submit each value. Bind applications operate similarly to creating and submitting applications for quotes. There are 3 main steps when using [.h-endpoint-link]/bind_applications[.h-endpoint-link] :

1. Create a Bind Application ([.h-code]POST[.h-code] [.h-endpoint-link]/bind_applications[.h-endpoint-link])
2. Update a Bind Application ([.h-code]PUT[.h-code] [.h-endpoint-link]/bind_applications/{bind_application_id}[.h-endpoint-link])
3. Submit a Bind Order([.h-code]POST[.h-code] [.h-endpoint-link]/bind_orders[.h-endpoint-link])

Step 1: Creating a bind application

[.h-code]POST[.h-code] [.h-endpoint-link]/bind_applications[.h-endpoint-link]

Creating a bind application requires the [.h-code]id[.h-code] of a quote with a [.h-code]bind_status[.h-code] of [.h-code]available[.h-code]. Bind availability depends on a number of factors, like the product or the quote status. We recommend checking the [.h-code]bind_status[.h-code] of each quote before creating a bind application.

[.icon-circle-blue][.icon-circle-blue] Herald is continuously expanding the set of products that support bind. Reach out to our team at hello@heraldapi.com to see which products allow bind today.

All that is needed to create a bind application is the [.h-code]quote_id[.h-code] of the quote you would like to bind. Create the bind application by submitting the [.h-code]quote_id[.h-code] like this:

POST /bind_applications

Copied

{
    "quote_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
 

The response includes all of the relevant parameters required to bind the quote. Similar to creating an application, the response includes metadata for each parameter to format these questions on your front-end, as well as a [.h-code]status[.h-code].

Bind applications have 2 core differences from applications:

• Admin Parameters: Both applications and bind applications contain risk and coverage parameters, but admin parameters are unique to bind applications. Admin parameters are nested within the [.h-code]admin_values[.h-code] array, and collect different types of information than risk and coverage parameters. Admin parameters collect information that is not related to an applicants risks (we collect that information via risk parameters) or desired coverages (we collect that information via coverage parameters). They can be used to collect information such as a brokers license number, or payment intervals for the policy.
• Automatic Pre-filling: Unlike applications, a newly created bind application may have a status of [.h-code]complete[.h-code] before submitting any values. Not all products require additional, unique information in order to bind a quote. For example, some products offer quotes without providing an effective date, but require an effective date to bind. If you provided the effective date when submitting the application for a quote, Herald will pre-fill that value when you create a bind application. Obviously, you can change those pre-filled values when filling out your bind application if you need to.

Below are example bind application responses where the application can be incomplete or complete.

Incomplete Bind Application Complete Bind Application

In this example, the bind application that was created has a status of incomplete. You can see that the required coverage value for the Cyber Effective Date already has a value, which was pre-filled from the application. The reason the bind application is incomplete is because admin parameters are required, which are null. These admin parameters, such as adm_6evk_surplus_broker_license_number, are not relevant when getting a quote and cannot be submitted until you create the bind application.

Submitting values for these parameters, which will cover in Step 2, will update this bind application to complete.

POST /bind_applications

Copied

{
    "bind_application": {
        "id": "7108cec8-61b9-46d9-93e4-d192450f4609",
        "quote_id": "96d7c27b-dd73-46f1-9d33-c7c43e812527",
        "status": "incomplete",
        "product_id": "prd_0050_herald_cyber",
        "risk_values": [],
        "coverage_values": [
            {
                "coverage_parameter_id": "cvg_o3mw_cyb_effective_date",
                "value": "2023-07-28",
                "section": "Coverages",
                "parameter_text": {
                    "applicant_facing_text": "Cyber Effective Date",
                    "agent_facing_text": "Cyber Effective Date"
                },
                "input_type": "date",
                "relevant_products": [
                    "prd_0050_herald_cyber"
                ],
                "creates_array": false,
                "affects_conditions": false,
                "required_for": [
                    "policy"
                ],
                "schema": {
                    "type": "string",
                    "format": "date",
                    "title": "Cyber Effective Date"
                }
            }
        ],
        "admin_values": [
            {
                "admin_parameter_id": "adm_5k6f_surplus_brokerage_name",
                "value": null,
                "section": "Admin Values",
                "parameter_text": {
                    "applicant_facing_text": "Surplus line brokerage name",
                    "agent_facing_text": "Surplus line brokerage name"
                },
                "input_type": "short_text",
                "relevant_products": [
                    "prd_0050_herald_cyber"
                ],
                "creates_array": false,
                "affects_conditions": false,
                "required_for": [
                    "policy"
                ],
                "schema": {
                    "type": "string",
                    "title": "Surplus line brokerage name",
                    "min_length": 1,
                    "max_length": 140
                }
            },
            {
                "admin_parameter_id": "adm_6evk_surplus_broker_license_number",
                "value": null,
                "section": "Admin Values",
                "parameter_text": {
                    "applicant_facing_text": "Surplus broker's license number",
                    "agent_facing_text": "Surplus broker's license number"
                },
                "input_type": "short_text",
                "relevant_products": [
                    "prd_0050_herald_cyber"
                ],
                "creates_array": false,
                "affects_conditions": false,
                "required_for": [
                    "policy"
                ],
                "schema": {
                    "type": "string",
                    "title": "Surplus broker's license number",
                    "min_length": 1,
                    "max_length": 140
                }
            },
        ]
    }
}
 

In this example, the bind application that was created already has a status of complete. You can see that the only required coverage value, which is for the Cyber Effective Date, already has a value. This can happen in the case that a product does not require any new information to bind a quote, and all of the values that were optional to quote were already submitted.

Basically: If you leave optional values null when submitting an application to get a quote, you will likely have to submit them at the bind application step.

POST /bind_applications

Copied

{
    "bind_application": {
        "id": "919d34f8-6299-470d-b93d-8579413ed4ce",
        "quote_id": "a124a10c-fbda-4f4d-8bdc-017fc7e44fc9",
        "status": "complete",
        "product_id": "prd_0050_herald_cyber",
        "risk_values": [ ],
        "coverage_values": [
            {
                "coverage_parameter_id": "cvg_o3mw_cyb_effective_date",
                "value": "2023-07-28",
                "section": "Coverages",
                "parameter_text": {
                    "applicant_facing_text": "Cyber Effective Date",
                    "agent_facing_text": "Cyber Effective Date"
                },
                "input_type": "date",
                "relevant_products": [
                    "prd_0050_herald_cyber"
                ],
                "creates_array": false,
                "affects_conditions": false,
                "required_for": [
                    "policy"
                ],
                "schema": {
                    "type": "string",
                    "format": "date",
                    "title": "Cyber Effective Date"
                }
            }
        ],
        "admin_values": []
    }
}
 

In both examples, the response includes all of the risk, coverage, and admin parameters that are relevant for to bind the quote, as well as a status. Some things to call out:

• The parameters include metadata like text, described in more detail in our risk and coverage parameter doc.
• The status must be [.h-code]complete[.h-code] in order to place the bind order.

‍

Step 2: Updating a bind application

[.h-code]PUT[.h-code] [.h-endpoint-link]/bind_applications/{bind_application_id}[.h-endpoint-link]

‍

Once a bind application has been created, it can be updated using [.h-code]PUT[.h-code]. In order to submit a bind application to get a policy (via placing a bind order), you need to continue to update the bind application until the status is [.h-code]complete[.h-code]. A bind application can have a [.h-code]complete[.h-code] status depending on the values you submitted when getting a quote and the product you are trying to bind.

While risk, coverage, and admin parameters adhere to the same principals in bind applications and applications, they tend to be less complex at the bind application stage. If you are not caught up on those complexities, take a look at our doc on parameter relationships.

Where there’s less complexity:

• Less Conditional Relationships: When filling out an application to get a quote, there are a lot of conditional relationships between parameters which Herald communicates as [.h-code-link]affects_conditions: true[.h-code-link]. By the time an institution has provided a quote, they have already collected all of the risks associated with an applicant and decided they are willing to insure them. The remaining information that institutions collect when binding the quote is fairly straight forward. In fact, some products only require an effective date to bind the policy. ‍Practically speaking: This means you will rarely receive additional, conditionally questions when making a [.h-code]PUT[.h-code] request to update a bind application.‍
• No Parent / Child Relationships: Similar to the bullet above, this is mostly a result of the types of information being collected. There are currently no parent/child relationships in bind applications.‍
• No Parameters with Multiple Values: Same as above! As you know, Herald uses the property [.h-code]creates_array: true[.h-code] to communicate that a parameter supports multiple values. Currently, there are no parameters relevant in bind applications with [.h-code]creates_array: true[.h-code].

Where there is new complexity:

• Parameters that Collect Files: It’s not uncommon for an institution to require a file when trying to bind a quote. For example, many institutions will require a signed and dated copy of the application in order to bind. Files are collected during bind applications just like all of the other information being collected- via parameters! We communicate that a parameter is expecting a file using an input type of [.h-code]file[.h-code]. Read our guide to uploading files.
• Post-Bind Actions: It’s also not uncommon for an institution to require certain information after providing a policy. While some institutions require a signed application (see above) in order to bind, other institutions allow you to provide it post-bind. It can be overwhelming to download, sign, and re-upload an application during the bind process. In the case that an institution allows you to provide the signed application post-bind, providing a file is optional in the bind application. This optionality is communicated as [.h-code]required_for: [post_policy][.h-code], whereas required information is required for [.h-code]policy[.h-code]. If you leave an optional parameter as [.h-code]null[.h-code] when filling out a bind application, the same information will be collected later on as an action on the policy.

[.icon-circle-blue][.icon-circle-blue] You can see the full list of parameters that are relevant when creating a bind application in our Policy Appendix.

‍

To update the bind application, simply make a [.h-code]PUT[.h-code] with values for each parameter. In the [.h-code]incomplete[.h-code] bind application above, there are two required admin values that are currently [.h-code]null[.h-code], and a coverage value for effective date that has a value of [.h-code]2023-07-28[.h-code]. To submit values for all required parameters, our request would look like this:

PUT /bind_applications/{bind_application_id}

Copied

{
	  "risk_values": [],
	  "coverage_values": [
	      {
	          "coverage_parameter_id": "cvg_o3mw_cyb_effective_date",
	          "value": "2023-07-28"
	      }
	  ],
	  "admin_values": [
	      {
	          "admin_parameter_id": "adm_5k6f_surplus_brokerage_name",
	          "value": "Harold Insurance"
	      },
	      {
	          "admin_parameter_id": "adm_6evk_surplus_broker_license_number",
	          "value": "1835566"
	      }
	  ]
}
 

‍

As stated above, there is rarely conditionality associated with the parameters in a bind application. In this example, all of the parameters have [.h-code]affects_conditions: false[.h-code], meaning they will not yield conditional questions. This results in a [.h-code]complete[.h-code] bind application.

‍

Response

Copied

{
  "bind_application": {
      "id": "7108cec8-61b9-46d9-93e4-d192450f4609",
      "quote_id": "96d7c27b-dd73-46f1-9d33-c7c43e812527",
      "status": "complete",
      "product_id": "prd_0050_herald_cyber",
      "risk_values": [],
      "coverage_values": [
          {
              "coverage_parameter_id": "cvg_o3mw_cyb_effective_date",
              "value": "2023-07-28",
              "section": "Coverages",
              "parameter_text": {
                  "applicant_facing_text": "Cyber Effective Date",
                  "agent_facing_text": "Cyber Effective Date"
              },
              "input_type": "date",
              "relevant_products": [
                  "prd_0050_herald_cyber"
              ],
              "creates_array": false,
              "affects_conditions": false,
              "required_for": [
                  "policy"
              ],
              "schema": {
                  "type": "string",
                  "format": "date",
                  "title": "Cyber Effective Date"
              }
          }
      ],
      "admin_values": [
          {
              "admin_parameter_id": "adm_5k6f_surplus_brokerage_name",
              "value": "Harold Insurance",
              "section": "Admin Values",
              "parameter_text": {
                  "applicant_facing_text": "Surplus line brokerage name",
                  "agent_facing_text": "Surplus line brokerage name"
              },
              "input_type": "short_text",
              "relevant_products": [
                  "prd_0050_herald_cyber"
              ],
              "creates_array": false,
              "affects_conditions": false,
              "required_for": [
                  "policy"
              ],
              "schema": {
                  "type": "string",
                  "title": "Surplus line brokerage name",
                  "min_length": 1,
                  "max_length": 140
              }
          },
          {
              "admin_parameter_id": "adm_6evk_surplus_broker_license_number",
              "value": "1835566",
              "section": "Admin Values",
              "parameter_text": {
                  "applicant_facing_text": "Surplus broker's license number",
                  "agent_facing_text": "Surplus broker's license number"
              },
              "input_type": "short_text",
              "relevant_products": [
                  "prd_0050_herald_cyber"
              ],
              "creates_array": false,
              "affects_conditions": false,
              "required_for": [
                  "policy"
              ],
              "schema": {
                  "type": "string",
                  "title": "Surplus broker's license number",
                  "min_length": 1,
                  "max_length": 140
              }
          },
      ]
  }
}
 

If you submit values incrementally, you’ll have to continually update the application until the status is [.h-code]complete[.h-code].

‍

Step 3: Placing a bind order

[.h-code]POST[.h-code] [.h-endpoint-link]/bind_orders[.h-endpoint-link]

‍

Once a bind application's status is [.h-code]complete[.h-code], you can submit a bind order to the institution to request a policy. To submit your bind application, simply make a [.h-code]POST[.h-code] request to [.h-endpoint-link]/bind_orders[.h-endpoint-link] with the completed bind application [.h-code]id[.h-code]. The request should look like this:

POST /bind_orders

Copied

{
    "bind_application": {
        "id": "7108cec8-61b9-46d9-93e4-d192450f4609"
    }
}
 

All done! Your bind application has been submitted to the institution to request a policy. To learn what happens next, read our docs on bind orders and policies.

[.icon-circle-blue][.icon-circle-blue] The status of a bind application can change from [.h-code]complete[.h-code] to [.h-code]invalid[.h-code] if some of the submitted values are no longer valid. Read more about bind application statuses.

‍