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:
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.
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.
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.
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:
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:
Since the signed application was the only value required for this application, the status is now [.h-code]complete[.h-code].