How to Build a Dynamic Application: Step by Step

Our Dynamic Application provides you with all of the relevant questions for a set of products, along with all of the information needed to render and submit each question. There are 3 main steps when using [.h-endpoint-link]/applications[.h-endpoint-link] to submit applications.

1. Create an Application ([.h-code]POST[.h-code] [.h-endpoint-link]/applications[.h-endpoint-link])
2. Update an Application ([.h-code]PUT[.h-code] [.h-endpoint-link]/applications/{application_id}[.h-endpoint-link])
3. Submit an Application ([.h-code]POST[.h-code] [.h-endpoint-link]/submissions[.h-endpoint-link])

Step 1: Creating an application

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

The only thing required to create an application is at least one [.h-code]product_id[.h-code]. A single application can be for multiple products, so you can include any products you have access to in the [.h-code]products[.h-code] array. If you already know some of the applicants information and would like to pre-fill those values, you have the option to include any known risk or coverage values when creating an application.

Below are example requests for creating a blank application (including only products) and creating an application with some pre-filled values.

Blank Application Pre-filled Application

To create an application only including products, your request should look like the example below.

POST /application

Copied

{
  "products": [
    "prd_mq3r_herald_general_liability"
  ]
}
 

In this case, each risk_value has value: null.

Response

Copied

{
  "application": {
    "id": "6e7c1486-9720-4135-b2b3-44e46df0404c",
    "status": "incomplete",
    "products": [
      "prd_mc4r_herald_general_liability"
    ],
    "risk_values": [
      
      {
        "risk_parameter_id": "rsk_m4p9_insured_name",
        "value": null,
        "text": "Insured name",
        "input_type": "short_text",
        "relevant_products": [
          "prd_mc4r_herald_general_liability"
        ],
        "affects_conditions": false,
        "required_for": [
          "quote"
        ],
        "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
        }
      },
      ...
    ]
  }
}
 

If you already have information on your applicants, such as name or payroll, you can include it when creating an application. Sending in this information on application creation allows you to default and pre-fill information that you may not want to show to the applicant.

To pre-fill information, you would simply include any of this information in your initial POST request. It’s essentially the same as updating the application, detailed in Step 2. In order to do this, you would need to know the correct id for the parameter you are trying to pre-fill. You can get this information from the Appendix, or take it from your sandbox requests during testing. If you were trying to pre-fill an applicants name on creating an application, your request would look like this:

POST /application

Copied

{
  "products": [
    "prd_mq3r_herald_general_liability"
  ],
	"risk_values": [
    {
      "risk_parameter_id": "rsk_m4p9_insured_name",
      "value": "Steve Smith"
    }
	]
}
 

In this case, the initial response would have value: “Steve Smith” for rsk_m4p9_insured_name, instead of the null value you receive for other parameters.

Response

Copied

{
  "products": [
    "prd_mq3r_herald_general_liability"
  ],
  "risk_values": [
    {
      "risk_parameter_id": "rsk_m4p9_insured_name",
      "value": "Steve Smith",
      .....
    },
    {
      "risk_parameter_id": "rsk_1rdc_home_state",
      "value": null,
      .....
    },
....
 

In both examples, the response includes all of the [.h-code]risk_parameters[.h-code] and [.h-code]coverage_parameters[.h-code] that are relevant for the requested products, as well as a status. Some things to call out:

• The returned risk and coverage values include metadata like text, described in more detail in our risk and coverage parameter doc.
• The status here is [.h-code]incomplete[.h-code] since no risk or coverage values have been set.

‍

Step 2: Updating an application

[.h-code]PUT[.h-code] [.h-endpoint-link]/applications/{application_id}[.h-endpoint-link]

Once an application has been created, it can be updated using [.h-code]PUT[.h-code]. In order to submit an application for a quote, you need to continue to update the application until the status is [.h-code]complete[.h-code]. It’s important to note that conditionally relevant values are only returned when the required conditions are met.

Example: If gross sales are only relevant for a specific class code, the risk value for gross sales will only be returned once the risk value for class code has been set.

Questions that can yield additional questions are given the property [.h-code-link]affects_conditions: true[.h-code-link]. If this is [.h-code]false[.h-code], then no conditional questions can be sent back, regardless of the value. You can choose to only make a [.h-code]PUT[.h-code] for cases where this is [.h-code]true[.h-code], which is detailed in our guide for building a front-end with the Dynamic Application.

Additionally, Herald can enable an optional field, [.h-code]affects_conditions_if[.h-code], which will provide details on the value that triggers the conditional parameter. Read more about this field and conditional relationships.

To update the application, simply make a [.h-code]PUT[.h-code] with values for each parameter. Following the example from above, we know that the applicants name is Steve Smith, and home state is required, but currently [.h-code]null[.h-code]. Our request to update this would look like this:

PUT /applications/{application_id}

Copied

{
  "products": [
    "prd_mc4r_herald_general_liability"
  ],
  "risk_values": [
    {
      "risk_parameter_id": "rsk_m4p9_insured_name",
      "value": "Steve Smith",
    },
    {
      "risk_parameter_id": "rsk_1rdc_home_state",
      "value": "MA",
    },
  ]
}
 

If the risk parameter [.h-code]rsk_1rdc_home_state[.h-code] has [.h-code-link]affects_conditions: true[.h-code-link], there’s a chance that the response will have an additional question. For example, the carrier that offers the product you are using may require that you ask every applicant in the state MA for their legal entity type. In that case, the response would be:

Response

Copied

{
  "application": {
    "id": "6e7c1486-9720-4135-b2b3-44e46df0404c",
    "status": "incomplete",
    "products": [
      "prd_mc4r_herald_general_liability"
    ],
    "risk_values": [
      {
        "risk_parameter_id": "rsk_m4p9_insured_name",
        "value": "Steve Smith",
        ......
      },
      {
        "risk_parameter_id": "rsk_1rdc_home_state",
        "value": "MA",
        "affects_conditions": true,
        ......
      },
      {
        "risk_parameter_id": "rsk_837r_legal_entity",
        "value": null,
        "schema": {
            "type": "string",
            "enum": [
                "Government/Public Entity",
                "Non-Profit Corporation",
                "Association",
                "Estate",
                "Individual",
                "C Corporation",
                "S Corporation",
                "General Partnership",
                "Limited Partnership",
                "Limited Liability Company",
                "Trust",
                "Sole Proprietorship",
                "Joint Venture",
                "Religious Organization",
                "Trustee"
            ]
        }
        ......
      },
    ]
  }
}
 

You’ll have to continually update the application until the status is [.h-code]complete[.h-code]. Some things to call out:

• It can take a number of iterations in order to reach a complete status. Depending on the products you are using, and the values for the applicant, any number of conditional questions could be returned.
• There are multiple levels of conditionality. A parameter that has [.h-code-link]affects_conditions: true[.h-code-link] can yield additional questions where this is also [.h-code]true[.h-code]. For example, if an applicant is a contractor, the carrier may need to ask “Do they use sub-contractors?”. If the applicant does use sub-contractors, they may need to ask “How many?”.
• Some questions are children of another parameter, for scenarios like an applicant with multiple class codes, who needs to submit payroll for each one. A parameter that is a parent would have a [.h-code]child_risk_values[.h-code] or [.h-code]child_coverage_values[.h-code] array containing all the child parameters, and the children need to be formatted below the parent in the request body. Learn how to work with parent/child relationships.
• Questions can be conditional on multiple values, such as a question conditional for certain class codes in certain states.
• If a new question is returned, it will always appear in the response as [.h-code]value: null[.h-code].

[.icon-circle-blue][.icon-circle-blue] You can also get an individual application using [.h-code]GET[.h-code] [.h-endpoint-link]/applications/{application_id}[.h-endpoint-link]

Step 3: Submitting an application

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

Once an application's status is [.h-code]complete[.h-code], you can submit it to carriers to get quotes. Similar to applications, a submission can be for multiple products. To submit your application, simply make a [.h-code]POST[.h-code] to [.h-endpoint-link]/submissions[.h-endpoint-link] with the [.h-code]application_id[.h-code] and a [.h-code]producer_id[.h-code]. The request should look like this:

POST /submissions

Copied

{
  "producer_id": "c5358d67-9692-43e7-a64a-5fd8d5760fd2",
  "application": {
    "id": "6e7c1489-9720-4135-b2b3-44e46df0404c"
  }
}
 

All done! Your application has been submitted to carriers to get quotes. To learn what happens next, read our docs on submissions and quotes.