Flexible Submissions

We created Flexible Submissions to reduce the impact of institution question changes on Static Applications

The best way to be ready for institutions adding required questions to their applications is to build with Herald’s Dynamic Application. The [.h-endpoint-link]/applications[.h-endpoint-link] endpoint dynamically provides you the required questions (parameters) for each [.h-code]institution[.h-code]. Building a Static Application requires you to manage and submit required questions. In the case that an [.h-code]institution[.h-code] adds an additional required question:

  • Creating a Dynamic Application would automatically return this new additional question to your application, no changes need.
  • Creating a Static Application would require you to update your application collect this new required question.

If there is a period before you are able to update your Static Application with a new required question, Flexible Submissions allows you to use our [.h-code]POST[.h-code][.h-endpoint-link]/submissions[.h-endpoint-link] endpoint and get quotes. Without Flexible Submissions, you cannot get quotes until you have 100% of the required questions answered in your [.h-code]submission[.h-code]..

Using Flexible Submissions

If you include the header [.h-code]flexible_submissions[.h-code] with the value [.h-code]on[.h-code] in your [.h-code]submission[.h-code], Herald allows you to submit incomplete question sets and get quotes for any product in that [.h-code]application[.h-code] whose required questions are all answered. Without the header [.h-code]flexible_submissions[.h-code] set to [.h-code]on[.h-code], submissions that do not have every required question for every product will return an error and not generate quotes.

Let’s say you have a very simple Static Application for Pigeon Cyber and Herald Cyber. The example below is the [.h-code]submission[.h-code] request you sent to our [.h-code]POST[.h-code][.h-endpoint-link]/submissions[.h-endpoint-link] endpoint. Note the [.h-code]flexible_submissions[.h-code] header.

curl Example

curl --location 'https: //sandbox.heraldapi.com/submissions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer s8h5U74ufcfwMYbZVy7UKeZV5enw0IyAtt2BkAMVVNw=' \
--header 'flexible_submissions: on' \
--data '{
    "producer_id": "99385c34-8729-4215-b35f-e1855e83835e",
    "application": {
        "products": [
        "coverage_values": [
                "coverage_parameter_id": "cvg_o3mw_cyb_effective_date",
                "value": "2023-12-21"
        "risk_values": [
                "risk_parameter_id": "rsk_4b4z_business_name",
                "value": "Herald"
                "risk_parameter_id": "rsk_dy7r_domain_names",
                "value": "heraldapi.com"

[.icon-circle-blue][.icon-circle-blue] Note: We developed Flexible Submissions as a header so that engineers can omit the header while integrating to get helpful error messages more quickly and then enable it when they want to mimic their higher environments.

Now let’s say Pigeon Cyber has added a new required question:  phone number. You have not yet had time to update your Static Application.

With Flexible Submissions, the [.h-code]POST[.h-code][.h-endpoint-link]/submissions[.h-endpoint-link] endpoint will return the same response you’re used to (no error messages); however, when you use our [.h-code]GET[.h-code][.h-endpoint-link]/quotes[.h-endpoint-link] endpoint the for Pigeon Cyber, the quote status will be [.h-code]rejected[.h-code] with [.h-code]status_details[.h-code] that say, “The application for this quote is missing information.” While the other institution (Herald in this case) will return quotes as usual.

GET /quotes

"quote": {
    "id": "8c996c19-6714-45a6-837a-a18e9f50b03c",
    "product": {
        "id": "prd_0450_pigeon_cyber",
        "name": "Pigeon Cyber",
        "product_line": "cyber",
        "institution": {
            "id": "ins_8xi6_pigeon",
            "name": "Pigeon"
    "status": "rejected",
    "status_details": [
            "status_text": {
                "agent_facing_text": "The application for this quote is missing information",
                "applicant_facing_text": "The application for this quote is missing information"
            "source": "herald"


Without Flexible Submissions (in the curl example you would NOT have included the flexible_submissions header) you’d see an error from our [.h-code]POST[.h-code][.h-endpoint-link]/submissions[.h-endpoint-link] endpoint. If you see this error, it means no quotes were generated for this submission. So you would not have quotes for Herald Cyber or Pigeon Cyber until you add the new required question.

POST /submissions

    "errors": [
            "id": "d523e1f0-8f44-4ea7-b397-9e3d50b3e0a6",
            "code": "invalid_format",
            "message": "\"application.risk_values\" does not contain at least one required match for type \"rsk_14kt_insured_contact_phone\"",
            "path": "application.risk_values",
            "display_message": "does not contain at least one required match for type \"rsk_14kt_insured_contact_phone\""
        } "display_message": "does not contain at least one required match for type \"rsk_ggy8_cyb_warranty\""