Submissions

A submission sends an application associated with a producer to one or more insurance institutions (carriers) and creates a quote for each requested product. Creating the submission using [.h-code]POST[.h-code] [.h-endpoint-link]/submissions[.h-endpoint-link] sends the application to each relevant institution to create a quote, and provides you with a [.h-code]quote_preview[.h-code] object for each requested product in the response. After creating the submission, you can get the quote details using our quote endpoint.

[.icon-circle-blue][.icon-circle-blue] Both applications and submissions can contain multiple products, but each quote is specific to an individual product.

Creating a Submission

Creating a submission requires a [.h-code]producer_id[.h-code] and an application. The producer associated with the submission must have access to all of the requested products. The data you provide in the application object depends on which type of application you are using. If you are using a static application, you’ll need to include the products, risk values, and coverage values in the body of your request. If you are using the Dynamic Application, we pull the products, risk values, and coverage values using the application [.h-code]id[.h-code]. In order to make a submission with a Dynamic Application, the application must have a [.h-code]complete[.h-code] status.

Dynamic Applcation Static Applcation

Only requires producer_id and the application id

POST /submissions

Copied

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

Requires producer_id and the entire application object

POST /submissions

Copied

{
  "producer_id": "c5358d67-9692-43e7-a64a-5fd8d5760fd2",
  "application": {
    "products": [
      "prd_mc4r_herald_general_liability"
    ],
    "coverage_values": [
      {
        "coverage_parameter_id": "cvg_48oo_gl_effective_date",
        "value": "2022-05-03"
      },
      {
        "coverage_parameter_id": "cvg_45pv_gl_tria",
        "value": "included"
      }
    ],
    "risk_values": [
      {
        "risk_parameter_id": "rsk_m4p9_insured_name",
        "value": "DeLorean Real Estate, LLC"
      },
      {
        "risk_parameter_id": "rsk_1rdc_home_state",
        "value": "CA"
      },
      {
        "risk_parameter_id": "rsk_tvm3_mailing_address",
        "value": {
          "line1": "1640 Riverside Drive",
          "line2": "#3",
          "city": "Hill Valley",
          "state": "CA",
          "postal_code": "95420",
          "country_code": "USA"
        }
      },
      {
        "risk_parameter_id": "rsk_yor8_location",
        "value": {
          "line1": "1640 Riverside Drive",
          "line2": "#3",
          "city": "Hill Valley",
          "state": "CA",
          "postal_code": "95420",
          "country_code": "USA"
        },
        "child_risk_values": [
          {
            "risk_parameter_id": "rsk_km7k_gl_class_code_by_location",
            "value": "63011",
            "child_risk_values": [
              {
                "risk_parameter_id": "rsk_j6y7_dwellings_by_gl_class_code",
                "value": 2
              },
              {
                "risk_parameter_id": "rsk_j4a3_has_pools_by_gl_class_code",
                "value": "no"
              }
            ]
          }
        ]
      }
    ]
  }
}
 

The submission response always contains the [.h-code]producer_id[.h-code] and application you sent in, as well as a submission [.h-code]id[.h-code] and a [.h-code]quote_preview[.h-code] for each product. Each quote preview contains:

• A [.h-code]quote_id[.h-code] for that unique quote
• The [.h-code]product_id[.h-code] that the quote is for

Here’s an example of a submission response for multiple products.

Response

Copied

{
  "submission": {
    "id": "46f56b68-8276-470e-8f17-424f2739895b",
    "producer_id": "c5358d67-9692-43e7-a64a-5fd8d5760fd2",
    "quote_previews": [
      {
        "quote_id": "88fa7725-cd27-4672-a17f-506c83d1f821",
        "product_id": "prd_mc4r_herald_general_liability"
      },
			{
        "quote_id": "240476f9-2462-483d-9b0e-a7a5a4f4908c",
        "product_id": "prd_tv9r_herald_cyber"
      }
    ],
    "application": {
      "products": [
        "prd_mc4r_herald_general_liability",
				"prd_tv9r_herald_cyber"
      ],
      "coverage_values": [
        {
          "coverage_parameter_id": "cvg_48oo_gl_effective_date",
          "value": "2022-05-03"
        },
        {
          "coverage_parameter_id": "cvg_45pv_gl_tria",
          "value": "included"
        }
      ],
      "risk_values": [
        {
          "risk_parameter_id": "rsk_m4p9_insured_name",
          "value": "Thirsty Scholar Pub"
        },
        {
          "risk_parameter_id": "rsk_1rdc_home_state",
          "value": "MA"
        },
        {
          "risk_parameter_id": "rsk_tvm3_mailing_address",
          "value": {
            "city": "Somerville",
            "line1": "70 Beacon St",
            "state": "MA",
            "postal_code": "02143",
            "country_code": "USA"
          }
        },
        {
          "risk_parameter_id": "rsk_yor8_location",
          "value": {
            "city": "Somerville",
            "line1": "70 Beacon St",
            "state": "MA",
            "postal_code": "02143",
            "country_code": "USA"
          },
          "child_risk_values": [
            {
              "risk_parameter_id": "rsk_km7k_gl_class_code_by_location",
              "value": "16941",
              "child_risk_values": [
                {
                  "risk_parameter_id": "rsk_w72m_gross_sales_by_gl_class_code",
                  "value": 150000
                }
              ]
            }
          ]
        }
      ]
    }
  }
}
 

[.icon-circle-blue][.icon-circle-blue] You can also get an individual submission using [.h-code]GET[.h-code] [.h-endpoint-link]/submissions/{submission_id}[.h-endpoint-link]

Getting Quotes

When you make a submission, Herald submits the request to each individual carrier to get a quote for each product. The submission response provides you with a [.h-code]quote_id[.h-code] for each product that can be used to retrieve the quote.

The [.h-code]quote_previews[.h-code] array in the submissions response contains a [.h-code]quote_id[.h-code] for each product, which can be used to retrieve the actual details of the quote.

Copied

{
  "submission": {
    "id": "46f56b68-8276-470e-8f17-424f2739895b",
    "producer_id": "c5358d67-9692-43e7-a64a-5fd8d5760fd2",
    "quote_previews": [
      {
        "quote_id": "88fa7725-cd27-4672-a17f-506c83d1f821",
        "product_id": "prd_mc4r_herald_general_liability"
      },
			{
        "quote_id": "240476f9-2462-483d-9b0e-a7a5a4f4908c",
        "product_id": "prd_tv9r_herald_cyber"
      }
    ],
  }
}
 

As you can see in the response above, there is a [.h-code]quote_preview[.h-code] with a [.h-code]quote_id[.h-code] for each individual product included in the submission. You can get the details of each quote using [.h-endpoint-link]/quote[.h-endpoint-link] or webhooks, both of which require a [.h-code]quote_id[.h-code].

The amount of time it takes to get a quote can vary (by a few seconds) depending on the carrier. You can get the details of a quote as soon as you have a [.h-code]quote_id[.h-code], but the quote’s status may be [.h-code]pending[.h-code]. Read more about quotes and statuses in our quote doc.

‍

After the Submission

Once you've submitted an application, you cannot edit the submission. Each quote is generated based on that individual, unique submission. You can create new applications or resubmit an existing application, but this will always result in a new submission and new quotes (even thought the quote price may stay the same).

The downside is that most carriers track each individual submission in their agent portal. Editing and re-submitting applications may result in a number of duplicative quotes in the carriers portal, which makes it a little difficult to keep track of which policies you've bound and which you should follow up on.

‍