Getting Files

[.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.

Herald returns files in the [.h-code]files[.h-code] array. The [.h-code]files[.h-code] array can contain a single file or multiple files, while a null value 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 from the [.h-code]quote[.h-code] 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]. The [.h-code]status[.h-code] of a file can be available, processing, unresponsive or deleted.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.

*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 can only get temporary links for files with an [.h-code]available[.h-code] status

You can get a temporary link to 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 the file that expires in 15 minutes. With each request, you will receive a new temporary link that expires 15 minutes after it is generated.

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 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]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 24 hours after the quote expires.

You can download and store files in your own file system. If you would like to store files on your own system, you can use [.h-code]file_name[.h-code] when saving the file.

‍

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-code]GET[.h-code][.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",
        "associations": [
         {
             "object_type": "quote",
             "object_id": "5193ce22-7f33-4c13-9077-7587e0e2dc3a"
         }
    }
}
 

‍

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.