Interact with a policy by performing actions

With Herald, you can create insurance offerings like quotes and policies by submitting applications (where applications are submitted to institutions to create quotes, bind applications are submitted to institutions to create policies). To interact with an existing policy, you perform actions.

[.icon-circle-blue][.icon-circle-blue] Actions are currently only available to interact with policies. This feature will be extended to quotes in the near future.

Essentially, actions allow you to submit additional information to institutions after the policy has been created. It’s not uncommon for an institution to request additional information after providing a quote or policy, and actions allow you to submit this information.

Actions on Policies

After providing a policy, an institution may require you to pay for the policy, upload a file, or answer additional questions. All of these requests are communicated as actions on a policy.

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

In most scenarios, the actions that appear on a policy were agreed upon before the policy was provided. Some institutions will provide a policy (or a binder) with contingencies. This allows applicants to get coverage before providing all of the information required by the institution. For example, many institutions require a signed and dated copy of the application, which is then manually reviewed, in order to receive a policy. Since this reviewal process can take time, some institutions will provide a policy before receiving the signed application. In this case, providing the signed application by a certain date is then listed as a contingency on the policy, and appears as an action on the policy. While this is just one example, it’s a fairly common one. Learn more about uploading signed applications.

Some important notes about actions:

  • Impact: Completing actions, or failing to complete actions, will have a direct impact on your policy. In most cases, actions on a policy have specific due dates, where failing to complete the action on time results in a termination of the policy. Using the example above, failing to provide a signed application by the due date can result in a termination of the policy. These timeframes can vary depending on the product you are using.
  • Reviewal Process: The information collected in actions tends to require a more tedious reviewal process. After submitting an action to the institution, it may take a few hours or days for the action to be reviewed and [.h-code]accepted[.h-code].
  • Methods: In some cases, there are multiple methods available to complete the action. Herald currently supports 2 methods (submitting applications and using links) to complete actions. Read more about action methods.

Using Actions

If actions are required for a policy, they are communicated on the policy in the [.h-code]actions[.h-code] array. Incomplete actions will have an [.h-code]open[.h-code] status, and you can get the details of the action using [.h-code]GET[.h-code] [.h-endpoint-link]/actions/{action_id}[.h-endpoint-link]. Learn how to complete actions in our guide to completing actions.


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

If no actions are required, the actions array will be [.h-code]null[.h-code].