Application Data Extractions

Herald enables you to apply extracted values to a Herald application.

Herald supports populating an application using data extracted from files by the implementation below. These files could be anything from an applicants financial statements, a prefilled application PDF, or other sources of risk and coverage information.

Upload [.h-code]files[.h-code] containing the information to extract
Create a [.h-code]data_extraction[.h-code] using the desired uploaded [.h-code]files[.h-code]
Choose or create a new [.h-code]application[.h-code]
Apply the [.h-code]data_extraction[.h-code] values to the [.h-code]application[.h-code]

Upload files to extract

Start by uploading all files for which you would like to extract. This can be done using [.h-code]POST[.h-code] [.h-endpoint-link]/files[.h-endpoint-link] One data extraction can accept many files, and you will be able to re-use files for multiple different extractions. Currently, Herald supports one file upload per API call. See uploading files to learn more details of this implementation.

Example of successful file upload:

POST /files

Copied


{
    "file": {
        "id": "9f5ecb01-a0d6-43a9-a205-312fe83736fd",
        "type": null,
        "format": "pdf",
        "file_name": "9f5ecb01-a0d6-43a9-a205-312fe83736fd.pdf",
        "text": "",
        "created_at": "2026-01-27",
        "size": 205294,
        "status": "available",
        "associations": null
    }
}

Create a data extraction

Once you have uploaded all files you wish to use for an extraction use our [.h-code]POST[.h-code] [.h-endpoint-link]/data_extractions[.h-endpoint-link] endpoint to create your [.h-code]data_extraction[.h-code]. We’ll use the file ID from above and another sample file ID.

POST /data_extractions

Copied


{
    "file_ids": [
    	"9f5ecb01-a0d6-43a9-a205-312fe83736fd", 
      "dc0f7ce2-75d6-417c-82ff-113ac006046c"
    ]
}

You can also optionally pass in [.h-code]context[.h-code] at this step to give some context to the extraction. In this example we are influencing the line of business we want to extract values for. In this case we want to specify we want a cyber quote:

POST /data_extractions

Copied


{
    "file_ids": [
    	"9f5ecb01-a0d6-43a9-a205-312fe83736fd", 
      "dc0f7ce2-75d6-417c-82ff-113ac006046c"
    ],
    "context": "This is a Cyber quote"
}

Now that you have created your [.h-code]data_extraction[.h-code] ID you can use [.h-code]GET[.h-code][.h-endpoint-link]/data_extractions/{data_extraction_id}[.h-endpoint-link] to check when the extraction will be available. This step may take a few minutes. Once the extraction is completed you will receive a response similar to the following:

GET /data_extractions/{data_extraction_id}

Copied


{
    "data_extraction": {
        "id": "64c82268-fd86-4cc6-8189-bac2a393b466",
        "status": "available",
        "file_ids": [
            "601048b5-1e50-433d-8f1c-292ad7c7eb7a"
        ],
        "risk_values": [
            {
                "value": "Marilyn Ha Collective",
                "risk_parameter_id": "rsk_m4p9_insured_name"
            },
            {
                "value": "7812953333",
                "risk_parameter_id": "rsk_14kt_insured_contact_phone"
            },
            {
                "value": {
                    "city": "Somerville",
                    "line1": "1070 Broadway Ave",
                    "line2": "Suite 505",
                    "state": "MA",
                    "postal_code": "02144",
                    "country_code": "USA"
                },
                "risk_parameter_id": "rsk_jsy2_primary_address"
            }
        ],
        "coverage_values": null,
        "context": null,
        "created_at": "2026-01-28T14:10:10.766Z",
        "updated_at": "2026-01-28T14:11:32.590Z"
    }
}

Note that a status of [.h-code]available[.h-code] will indicate the extraction has been completed.

Choose or create an application

In order to apply our extracted values from our [.h-code]data_extraction[.h-code] to an application we will first need to identify an application we wish to apply the values too. This could be an existing application that hasn't been submitted or you can create a new application to target using [.h-code]POST[.h-code][.h-endpoint-link]/applications[.h-endpoint-link]. An example of application creation is shown below, visit applications overview for more information about application creation and updating.

POST /applications

Copied


{
    "products": [
        "prd_7ita_beazley_cyber",
        "prd_c4ow_cowbell_cyber_surplus"
    ]
}

Apply a data_extraction to an application

Now that we have our completed [.h-code]data_extraction[.h-code] and have a target application we can use [.h-code] POST[.h-code] [.h-endpoint-link]/applications/{application_id}/data_ extraction[.h-endpoint-link] to apply these values to an application.

POST /applications/{application_id}/data_extraction

Copied


{
  "data_extraction_id": [
    "afebb7b5-638d-4c30-ab5e-1f4d55032be9"
  ]
}

By default, applying extracted values to an application will overwrite any existing application values, however this is configurable using the Override-Values header. If set to off, extraction values will only be applied to parameters with null values. In addition, the source of all values applied this way will be updated to [.h-code]data_extraction[.h-code]. Let's go through a few examples in the next section to understand how applying extracted values to an application will work.

Let's consider an existing application with the following properties:

GET /applications/{application_id}

Copied


{
    "application": {
        "id": "15d1f4b6-9f7b-43a6-867d-9c9a78fe7975",
        "status": "incomplete",
        "products": [
            "prd_7ita_beazley_cyber"
        ],
        "risk_values": [
            {
                "risk_parameter_id": "rsk_m4p9_insured_name",
                "value": "Jimmy's Lobster",
                "source": null
            },
            {
                "risk_parameter_id": "rsk_vrb1_total_annual_revenue",
                "value": null,
                "source": null
            }
        ]
    }
}

Notice how the existing application has one parameter with a null value, [.h-code]rsk_vrb1_total_annual_revenue[.h-code], and one parameter, [.h-code]rsk_m4p9_insured_name[.h-code], with a value populated already. Now consider we create a data extraction with the following extracted values:

GET /data_extractions/{data_extraction_id}

Copied


{
    "data_extraction": {
        "id": "64c82268-fd86-4cc6-8189-bac2a393b466",
        "status": "available",
        "risk_values": [
            {
                "risk_parameter_id": "rsk_m4p9_insured_name",
                "value": "Roberto's Pizza"
            },
            {
                "risk_parameter_id": "rsk_vrb1_total_annual_revenue",
                "value": 10000000
            }
        ]
    }
}

Applying the extracted values to the [.h-code]application[.h-code] with no configuration will result in the following [.h-code]application[.h-code] state:

POST /applications/{application_id}/data_extraction

Copied


{
    "application": {
        "id": "15d1f4b6-9f7b-43a6-867d-9c9a78fe7975",
        "status": "incomplete",
        "products": [
            "prd_7ita_beazley_cyber"
        ],
        "risk_values": [
            {
                "risk_parameter_id": "rsk_m4p9_insured_name",
                "value": "Roberto's Pizza",
                "source": "data_extraction"
            },
            {
                "risk_parameter_id": "rsk_vrb1_total_annual_revenue",
                "value": 10000000,
                "source": "data_extraction"
            }
        ]
    }
}

Notice how [.h-code]rsk_m4p9_insured_name[.h-code] has been updated to [.h-code]Roberto's Pizza[.h-code] and [.h-code]rsk_vrb1_total_annual_revenue[.h-code] has been updated to 10,000,000 using the extracted values.

You now have an updated [.h-code]application[.h-code] and can submit it if it's complete, apply an [.h-code]autofill_profile[.h-code], apply another [.h-code]data_extraction[.h-code], or manually update values!

Configure override of values to application

In the case that you want to only update values on an existing application that are currently null, you can configure the [.h-code]Override-Values[.h-code] header to only apply values from an extraction to null values on an application. This may be useful if you applied a data extraction to anapplication, but created a new extraction with some updated document information (financial statements for example) and want to only update the values you were not able to extract previously. Let's use the previous example and apply the same extraction. As a reminder, the existing target application has the following:

GET /applications

Copied


{
    "application": {
        "id": "15d1f4b6-9f7b-43a6-867d-9c9a78fe7975",
        "status": "incomplete",
        "products": [
            "prd_7ita_beazley_cyber"
        ],
        "risk_values": [
            {
                "risk_parameter_id": "rsk_m4p9_insured_name",
                "value": "Jimmy's Lobster",
                "source": null
            },
            {
                "risk_parameter_id": "rsk_vrb1_total_annual_revenue",
                "value": null,
                "source": null
            }
        ]
    }
}

And our data_extraction has extracted the following information:

GET /data_extractions/{data_extraction_id}

Copied


{
    "data_extraction": {
        "id": "64c82268-fd86-4cc6-8189-bac2a393b466",
        "status": "available",
        "risk_values": [
            {
                "risk_parameter_id": "rsk_m4p9_insured_name",
                "value": "Roberto's Pizza"
            },
            {
                "risk_parameter_id": "rsk_vrb1_total_annual_revenue",
                "value": 10000000
            }
        ]
    }
}

If you now apply the [.h-code]data_extraction[.h-code] to this [.h-code]application[.h-code] including a value of "off" for the [.h-code]Override-Values[.h-code] header, you will result in the following [.h-code]application[.h-code] state:

POST /applications/{application_id}/data_extraction

Copied


{
    "application": {
        "id": "15d1f4b6-9f7b-43a6-867d-9c9a78fe7975",
        "status": "incomplete",
        "products": [
            "prd_7ita_beazley_cyber"
        ],
        "risk_values": [
            {
                "risk_parameter_id": "rsk_m4p9_insured_name",
                "value": "Jimmy's Lobster",
                "source": null
            },
            {
                "risk_parameter_id": "rsk_vrb1_total_annual_revenue",
                "value": 10000000,
                "source": "data_extraction"
            }
        ]
    }
}

Notice how the value [.h-code]rsk_m4p9_insured_name[.h-code] has NOT been updated and remains [.h-code]Jimmy's Lobster[.h-code] but the value for [.h-code]rsk_vrb1_total_annual_revenue[.h-code] WAS updated and the resulting application value contains [.h-code]10000000[.h-code]. In addition, note the value for the source on both parameters. [.h-code]rsk_m4p9_insured_name[.h-code] has NOT been updated and remains [.h-code]null[.h-code], while the value for [.h-code]rsk_vrb1_total_annual_revenue[.h-code] WAS updated and is now [.h-code]data_extraction[.h-code].

FAQ

Q: Does Herald support application creation and extraction value application in one API call?
- A: No, Herald does not yet support [.h-code]application[.h-code] creation and [.h-code]data_extraction[.h-code] value application in a single API call. You need to create an [.h-code]application[.h-code] separately using our [.h-code]POST[.h-code][.h-endpoint-link]/applications[.h-endpoint-link] endpoint, and then separately apply an extraction using our [.h-code] POST[.h-code] [.h-endpoint-link]/applications/{application_id}/data_ extraction[.h-endpoint-link] endpoint.
Q: Will the [.h-code]context[.h-code] field guarantee the desired behavior for my extraction?
- A: No, the [.h-code]context[.h-code] field cannot guarantee any specific behavior. This field passes information to our AI extractions tool which will use it as an input to decision making, but the influence of this input is variable.
Q: Can I apply extracted values to a submission using the POST/ [.h-endpoint-link]submissions[.h-endpoint-link] endpoint?
- A: No, Herald only provides this feature set for our applications. Some implementations of Herald use only our POST/ [.h-endpoint-link]submissions[.h-endpoint-link] endpoint. We do not yet support applying a [.h-code]data_extraction[.h-code] for those implementations.

/applications/{application_id}/data_extraction