Getting Files

Get files for each policy.

[.icon-triangle-yellow][.icon-triangle-yellow]Herald only offers Quote Summary PDFs today, and they are not yet available for every product. We are actively expanding our file offering and will update our documentation as we add new file types.

When a Quote Summary PDF is available from the carrier, and Herald has ingested and stored this document, the API response will include the Quote Summary document and metadata in the files array. Each file returned by Herald in the files array will have a unique id and relevant information. Here’s an example:

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"
    }
  ],
  ....
}
 

When a file is accessible, the files array will include:

  • An [.h-code]id[.h-code] that is always unique and can be used to retrieve the file's contents and file's metadata.
  • The file [.h-code]type[.h-code] so you know which file you are retrieving.
  • The [.h-code]text[.h-code] of the file that can be used to render a front end description of the file.
  • [.h-code]Status[.h-code] of the file which can be:
    - [.h-code]available[.h-code] when the [.h-code]quote_status[.h-code] is [.h-code]active[.h-code], [.h-code]referral[.h-code], or [.h-code]referred[.h-code] and the quote has a corresponding file.
    - [.h-code]deleted[.h-code] when the [.h-code]quote_status[.h-code] has become [.h-code]expired[.h-code] because it has been more than 60 days since the quote was generated.

Herald stores the files we get from carriers for a maximum of 60 days. You are able to see the availability of each file via the [.h-code]status[.h-code] field in the files array. While you can get the metadata for files at any time, the actual contents of a file is not accessible once it has been deleted.

While many carriers return files when getting a policy, not all carriers have made this information available. Herald easily indicates that a file isn’t available by returning [.h-code]null[.h-code].

GET /quotes/{quote_id}
Copied

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbbahd76",
  "product_id": "prd_mc4r_herald_general_liability",
  "status": "active",
  "files": null,
  ....
}
 

Get File Metadata

The files array already includes basic information about each file (seen in the example above), and using the id returned in the files array you can get the full metadata for each file with the  [.h-code]GET[.h-code] [.h-endpoint-link]/files/{file_id}[.h-endpoint-link] endpoint. The additional information included in this request is: the format, file name, creation date, and size.

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"
    }
}
 

You can use this metadata to gain granular insights in to each file at any point in the process, when the file is available, or after the file has expired.

File Content

You can get the content of each file returned from a carrier using the temporary link provided by Herald. Upon using the temporary link, you can view the file in the format specific to what you are accessing.

To access the temporary file link, you can use the id returned in the files array, in the [.h-code]POST[.h-code][.h-endpoint-link]/files/{file_id}/get_temporary_link[.h-endpoint-link] endpoint. Here’s an example:

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 link expires within 15 minutes, but if you would like to retrieve the link again, you can make a call to the [.h-code]POST[.h-code][.h-endpoint-link]/files/{file_id}/get_temporary_link[.h-endpoint-link],using the file id, as many times as you would like and each time the new link will last for 15 minutes.

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.

If there is a file type that isn’t available that you would like to see in the quote response, please reach out to our team at hello@heraldapi.com.