A guide to getting policies through Herald

A policy represents an agreement between an insured and an institution that has underwritten the insured’s risk, such as an insurance carrier or Managing General Agent (MGA) . Policies outline the coverage afforded to the insured along with operational details around claims handling. In practice, a policy exists when the institution provides a file of the contract outlining this agreement. Our API enables you to issue policies by downloading these files from the insurance institutions that provide them after successful completion of a bind order.

Policies at Herald

You can create policies at Herald by submitting bind orders to institutions. When you submit a bind order, a bind application is sent to the institution to review, which may require a manual review from an underwriter. The bind order will have a status of [.h-code]pending[.h-code] until the institution has made a decision, either accepting the bind order (and providing the policy) or rejecting it.

Once a bind order is [.h-code]accepted[.h-code], the [.h-code]id[.h-code] of the policy will be available in the bind order response. You can use this [.h-code]id[.h-code] to get the details of the policy using [.h-code]GET[.h-code] [.h-endpoint-link]/policies[.h-endpoint-link]. Every policy includes a number of policy related files provided by the institution, you can read the full list of supported file types here. Additional information such as the policy number, coverage values, and created at time are also available for policies.

[.icon-alert][.icon-alert]Note that Herald does not currently provide a status for policies. The status shown in the bind order is a point-in-time status, communicating if the the institution decided to provide a policy when the request was made.

Learn how to get policies in our guide to getting policies.

Policy Actions

It is common for institutions to collect additional information after providing a policy. A basic example is payment- many institutions will provide a policy before collecting payment, with terms as to when the payment must be made to prevent a termination of the policy. Herald surfaces these requirements as actions on the policy.

[.icon-alert][.icon-alert]Herald currently does not support payments to institutions. All post-policy payments transactions are managed between your existing relationship with the institution.

Post-policy actions typically serve as a way to satisfy contingencies that were agreed upon in the contract. For example, an institution may provide coverage with terms stating that a signed application must be provided within 30 days. Failure to provide the signed application in 30 days would result in a termination of the contract, whereas providing the signed application in the agreed upon timeline would result in the policy being provided as promised.

Some institutions will provide the full policy prior to contingencies being satisfied, while other institutions will provide coverage in the form of a binder with contingencies. A binder serves as temporary proof of coverage until the contingencies, such as providing a signed application, are fulfilled. Fulfilling these contingencies in the agreed upon time will result in the policy being issued, and failure to fulfill these contingencies will result in the contract being terminated.

All of the examples above are communicated through actions on a policy. If actions are required, they will be communicated on the policy in the [.h-code]actions[.h-code] array like this:


  "policy": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "policy_number": "EHJ-ADK00460738",
    "product_id": "prd_0050_herald_cyber",
    "portal_link": "https://heraldapi.com",
    "actions": [
        "id": "5d17ac07-915c-440a-b6ee-403be4ad7c02",
        "status": "open"

If no actions are required, the actions array will be [.h-code]null[.h-code]. Learn more about completing actions on a policy.