Getting Files

Get additional data and the contents of a file.

[.icon-square-blue][.icon-square-blue]Herald is continuously expanding our file offering. If you would like a file that is not listed in our list of supported file types, please reach out to our team at hello@heraldapi.com.

When a file is available, it will be in the [.h-code]files[.h-code] array. The [.h-code]files[.h-code] array can contain a single file or multiple files, while an empty array means there are no relevant files available.

The [.h-code]files[.h-code] array is currently returned in quotes and policies. Here’s an example of what a files look like in the quote response:

GET /quotes/{quote_id}
Copied

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "product_id": "prd_mc4r_herald_general_liability",
  "status": "active",
  "files": [
    {
      "id": "d7c4579a-5450-4e79-bcfc-e918b3c8a564",
      "type": "quote_summary",
      "text": "Quote Summary",
      "status": "available"
    },
    {
      "id": "138fcedd-c394-46e6-b025-3f62a191223d",
      "type": "application",
      "text": "Application",
      "status": "processing"
    }
  ],
  ....
}
 

In the response above, there are two types of files for this quote: a [.h-code]quote_summary[.h-code] and an [.h-code]application[.h-code]. Using the file’s [.h-code]id[.h-code], you can:

  • Get a temporary link to access the contents of the file, using [.h-endpoint-link]/files/{file_id}/get_temporary_link[.h-endpoint-link]. This provides you with a temporary link to access the content of a file that expires in 15 minutes.
  • Get more details on the file, using [.h-endpoint-link]/files/{file_id}[.h-endpoint-link]. This provides you with additional information like the files [.h-code]size[.h-code] and [.h-code]file_name[.h-code]. Read the full list of file metadata.

The [.h-code]status[.h-code] of a file can be available or deleted. Once a file is deleted, you can no longer create a temporary link to access the contents of a file, but you can still access the metadata. For quotes, all files are deleted 24 hours after the quote expires.

Getting a Temporary Link

[.icon-alert][.icon-alert] You cannot get temporary links for files with a [.h-code]deleted[.h-code] status. Files are hosted by Herald, and stored for a certain amount of time based on the [.h-code]type[.h-code] of file.

You can get a temporary link to access the contents of a file using [.h-endpoint-link]/files/{file_id}/get_temporary_link[.h-endpoint-link]. Making a [.h-code]POST[.h-code] request to this endpoint will generate a temporary link to access the content of the file that expires in 15 minutes. With each request, you will receive a new temporary link that expires in 15 minutes.

In the example above, we have a file_id for a Quote Summary. Making a [.h-code]POST[.h-code] request with the file [.h-code]id[.h-code] will return the following:

POST /files/{file_id}/get_temporary_link
Copied

{
    "temporary_link": {
        "link": "https://files-sandbox.heraldapi.com/quote_summary/herald_quote_summary_05aefd0b-0dea-4c35-8248-7084cc7b247f.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=DO00KTMX4NHPECHT8VNW%2F20221219%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20221219T080446Z&X-Amz-Expires=900&X-Amz-Signature=1d572ab767fc963f3b16573fa68ece5ff9431c46f38598b444ecaf8cd00ce5a9&X-Amz-SignedHeaders=host&x-id=GetObject"
    }
}
 

The temporary [.h-code]link[.h-code] can be used to retrieve the contents of a file without authentication. Since these links are temporary, they are best created at the intent to access a file. On your front-end, you may choose to allow users to download the file directly to their computer or open the file’s link in a browser. To avoid stale links in these scenarios, it’s best to get the temporary link when those buttons are clicked.

[.icon-alert][.icon-alert] Herald recommends you do not display the URL of a temporary link on your front-end

All files are hosted by Herald, and are periodically [.h-code]deleted[.h-code]. Once a file is deleted, you can no longer get a temporary link to access the contents of the file. Files are deleted after a certain amount of time based on the files [.h-code]type[.h-code]. For example, a Quote Summary is deleted when the quote expires.

Obviously, Herald customers have the option to download and store the files in their own filesystem. If you would like to store the files on your own system, you can use [.h-code]file_name[.h-code] when saving the file to a filesystem.

Getting File Details

When a file is represented within the [.h-code]files[.h-code] array of another resource, only a subset of the file details are present. You can get the full details of a file using [.h-endpoint-link]/files/{file_id}[.h-endpoint-link], regardless of the files [.h-code]status[.h-code].

The response contains all of the metadata for the file, which is documented here.

GET /files/{file_id}
Copied

{
    "file": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "type": "quote_summary",
        "format": "pdf",
        "file_name": "herald_quote_summary_05aefd0b-0dea-4c35-8248-7084cc7b247f.pdf",
        "text": "Quote Summary",
        "created_at": "2022-12-19",
        "size": 124212,
        "status": "available"
    }
}
 

Using Files

When you are setting up files on your front end, we recommend that you create a button to retrieve the file. Once you click the button, you make a [.h-code]POST[.h-code] request to [.h-endpoint-link]/files/{file_id}/get_temporary_link[.h-endpoint-link] which will then direct the user to link which contains the file. This link can either download the file or open the file in a browser window.