A small check-mark with a yellow gradient background
Thanks!
Someone from our team will reach out to you soon.
Oops! Something went wrong while submitting the form.
A black X

Uploading Files

Upload files to share with institutions

[.icon-square-blue][.icon-square-blue] Uploading files is currently only relevant when filling out bind applications or submitting actions to get policies.

An institution can require an applicant to provide a file in order to get a policy. For example, many institutions will require a signed and dated copy of the application in order to get a policy (this application is originally provided by the institution, learn more about getting files). You can upload files to Herald using [.h-code]POST[.h-code] [.h-endpoint-link]/files[.h-endpoint-link].

When to Upload

When an uploaded file is required, it will be communicated as a parameter in the resources. Today, file uploads are only relevant when filling out bind applications or submitting actions to get policies. If a file is required for a bind application or action, the parameter will have an input type of [.h-code]file[.h-code].

Let’s walk through an example where we are filling out a bind application. In the example below, we have just created a bind application for a quote. The response includes all of the relevant parameters required to bind the quote:

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": [
            {
                "risk_parameter_id": "rsk_ms9x_signed_application",
                "value": null,
                "section": "Files",
                "parameter_text": {
                    "applicant_facing_text": "Upload a signed and dated version of the submitted cyber application.",
                    "agent_facing_text": "Upload a signed and dated version of the submitted cyber application."
                },
                "input_type": "file",
                "source_file": "33a5ff38-5e72-4cd2-86cf-bea643dc697d",
                "relevant_products": [
                    "prd_0050_herald_cyber"
                ],
                "creates_array": false,
                "affects_conditions": false,
                "required_for": [
                    "policy"
                ],
                "schema": {
                    "type": "string",
                    "format": "uuid",
                    "title": "Upload a signed and dated version of the submitted cyber application."
                }
            }
        ],
        "coverage_values": [],
        "admin_values": []
    }
}

As you can see, only one value is required for this bind application: a signed application via the risk parameter [.h-code]rsk_ms9x_signed_application[.h-code]. Some things to note:

  • This parameter has an [.h-code]input_type[.h-code] of [.h-code]file[.h-code]. Learn more about using input types to render parameters on screen.
  • This parameter has a [.h-code]source_file[.h-code]. Source files are provided when the file to be uploaded is a file that must first be downloaded. As stated above, this example requires a signed application, so the source file includes the [.h-code]id[.h-code] of the application provided by the institution. You can use the [.h-code]id[.h-code] to get the file.
  • The [.h-code]schema[.h-code] object includes a format of [.h-code]uuid[.h-code]. The actual value this parameter expects is the [.h-code]id[.h-code] the file was assigned after you upload it. Read more below on using uploaded files.

Just remember that a file can be relevant for filling out bind applications and completing actions. In other words, parameters with an input type of [.h-code]file[.h-code] can appear in both the bind application and action response.

Uploading Files

Once you know a file is required, you can upload the file using [.h-code]POST[.h-code] [.h-endpoint-link]/files[.h-endpoint-link]. Herald supports file uploads sent with a content type of [.h-code]multipart/form-data[.h-code]. The [.h-code]POST[.h-code] request should include the contents of the file, and the [.h-code]type[.h-code] of file being uploaded. See the supported file types, formats, and size in our reference.

POST /files
Copied 

curl --request POST \
  --url https://sandbox.heraldapi.com/files \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: multipart/form-data' \
  --form file="@/path/to/a/file.jpg" \
  --form type=signed_application

The response includes the same information made available when you get a file. The file will be assigned an [.h-code]id[.h-code], which can be used to get metadata or the contents of the file again. More importantly, the [.h-code]id[.h-code] can of the file is used as the value when files are required. See more on that in the next section.

Copied 

{
  "file": {
    "id": "d7c4579a-5450-4e79-bcfc-e918b3c8a564",
    "type": "signed_application",
    "format": "pdf",
    "file_name": "signed_application_d7c4579a-5450-4e79-bcfc-e918b3c8a564",
    "text": "Signed Application",
    "created_at": "2022-08-11",
    "size": 2470,
    "status": "available"
  }
}

Using Files

Above, we showed that parameters are used to communicate when you are required to upload a file for a bind application or action, and how to upload a file. Once you’ve successfully uploaded the file, you can use the [.h-code]id[.h-code] of the uploaded file as the value for the parameter.

In the example above, we walked through an example where a signed application was required on a bind application. Let’s look at it again:

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": [
            {
                "risk_parameter_id": "rsk_ms9x_signed_application",
                "value": null,
                "section": "Files",
                "parameter_text": {
                    "applicant_facing_text": "Upload a signed and dated version of the submitted cyber application.",
                    "agent_facing_text": "Upload a signed and dated version of the submitted cyber application."
                },
                "input_type": "file",
                "source_file": "33a5ff38-5e72-4cd2-86cf-bea643dc697d",
                "relevant_products": [
                    "prd_0050_herald_cyber"
                ],
                "creates_array": false,
                "affects_conditions": false,
                "required_for": [
                    "policy"
                ],
                "schema": {
                    "type": "string",
                    "format": "uuid",
                    "title": "Upload a signed and dated version of the submitted cyber application."
                }
            }
        ],
        "coverage_values": [],
        "admin_values": []
    }
}

Submitting a file as a value is exactly the same as submitting any other value, you can see our step-by-step guide here. To submit the file, we make a [.h-code]PUT[.h-code] request to update the bind application with the value:

PUT /bind_applications/{bind_application_id}
Copied 

{
    "products": [
        "prd_0050_herald_cyber"
    ],
    "risk_values": [
        {
            "risk_parameter_id": "rsk_ms9x_signed_application",
            "value": "d7c4579a-5450-4e79-bcfc-e918b3c8a564"
        }
    ]
}

Since the signed application was the only value required for this application, the status is now [.h-code]complete[.h-code].

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": [
            {
                "risk_parameter_id": "rsk_ms9x_signed_application",
                "value": "d7c4579a-5450-4e79-bcfc-e918b3c8a564",
                ....
[.icon-alert][.icon-alert] Parameters that collect files are still parameters, meaning they may trigger conditional questions. Learn more about parameter relationships.