Methods

After providing a policy, an institution may require you to complete additional actions. For example, many institutions will require a signed and dated copy of the application in order to get a policy. There are 2 different methods to providing the signed application and completing the action:

• The [.h-code]application[.h-code] method: Allows you to provide information the same way you provide information on an application to get quotes- by submitting values for parameters! The application method is essentially the “API” method, where you can complete the action via API.
• The [.h-code]link[.h-code] method: Allows you to complete the action by visiting a link provided by the institution. This is the “Non-API” method, in which the action is completed outside of Heralds ecosystem.

The available methods will depend on the action. Some actions may only offer a link method or application method, and some actions offer both methods. The list of available methods are communicated in the [.h-code]methods[.h-code] array of the action.

The application method

If you’ve made it to the point where you are completing actions, then you’ve already submitted an application to get quotes, and submitted a bind application to get a policy. So, you know all about submitting values for parameters! The [.h-code]application[.h-code] method allows you to complete an action by submitting values, functioning exactly the same as filling out an application. Let’s take a look at this method in the action response:

Copied

{
    "action": {
        "id": "5d17ac07-915c-440a-b6ee-403be4ad7c02",
        "status": "open",
        "status_details": null,
        "text": {
            "applicant_facing_text": "Upload a signed and dated application",
            "agent_facing_text": "Upload a signed and dated application with the applicant's signature"
        },
        "methods": [
            {
                "type": "application",
                "text": {
                    "applicant_facing_text": "Download and sign the application PDF, and upload it here.",
                    "agent_facing_text": "Download and have the applicant sign the application PDF, and upload it here."
                },
                "application": {
                    "status": "incomplete",
                    "risk_values": [
                        {
                            "risk_parameter_id": "rsk_ms9x_signed_application",
                            "value": null,
                            "section": "Files",
                            "parameter_text": {
                                "applicant_facing_text": "Upload a signed and dated version of the submitted cyber application.",
                                "agent_facing_text": "Upload a signed and dated version of the submitted cyber application."
                            },
                            "input_type": "file",
                            "relevant_products": [],
                            "creates_array": false,
                            "affects_conditions": false,
                            "required_for": [
                                "post-policy"
                            ],
                            "schema": {
                                "type": "string",
                                "format": "uuid",
                                "title": "Upload a signed and dated version of the submitted cyber application."
                            }
                        }
                    ],
                    "coverage_values": [],
                    "admin_values": []
                }
            }
        ],
        ....
    }
}
 

As you can see, the [.h-code]application[.h-code] method includes risk, coverage, and admin values as well as a [.h-code]status[.h-code], just like applications and bind applications. The one difference is that the application method also include [.h-code]text[.h-code] to explain how to complete the action with this method.

To complete an action using the [.h-code]application[.h-code] method, you submit values using [.h-code]PUT[.h-code] [.h-endpoint-link]/actions/{action_id}[.h-endpoint-link]. Once the status of the method is complete, you can submit the action. Read more in our guide to completing actions.

The link method

[.icon-circle-blue][.icon-circle-blue] Some actions can only be completed using the [.h-code]link[.h-code] method. You can choose to only show the application method when available (which we recommend), but make sure you are able to support the link method when necessary.

The [.h-code]link[.h-code] method allows you to complete actions using links providing by the institution. Most institutions offer agent-facing an applicant-facing portals to manage quotes, make payments, and complete actions.

The link method contains an array of links, each with a [.h-code]type[.h-code] to communicate if it is agent-facing or applicant-facing. For example, an institution may allow an agent (producer) to complete an action in the institutions standard agent portal that offers quoting and managing all of the agents clients. For applicants, they may offer a non-logged in experience with the sole purpose of completing the action.

Let’s take a look at this method in the action response:

Copied

{
    "action": {
        "id": "5d17ac07-915c-440a-b6ee-403be4ad7c02",
        "status": "open",
        "status_details": null,
        "text": {
            "applicant_facing_text": "Upload a signed and dated application",
            "agent_facing_text": "Upload a signed and dated application with the applicant's signature"
        },
        "methods": [
            {
                "type": "link",
                "links": [
                    {
                        "link": "www.herald-ins.com/quotes/1234",
                        "text": "Download and sign the application PDF in the Herald portal",
                        "type": "agent_facing_link"
                    }
                ]
            },
        ]
    }
}
 

As you can see, the [.h-code]link[.h-code] method includes an array of links. For each individual link, Herald offers the [.h-code]link[.h-code], the [.h-code]type[.h-code], and [.h-code]text[.h-code] to communicate what is expected after clicking the link.

Important to Note: As you can imagine, there is one very big difference between the link method and the application method- The link method relies on the honor system. Once the user has completed the action using the link method, you can submit the action using [.h-code]POST[.h-code] [.h-endpoint-link]/actions/{action_id}/submit[.h-endpoint-link], which triggers Herald to confirm with the institution that the action was successfully completed. We recommend you ask users to confirm that they have completed the action after clicking the link, such as:

Completing Actions

Once you’ve completed the action, you send the method [.h-code]type[.h-code] used to complete the action to [.h-code]POST[.h-code] [.h-endpoint-link]/actions/{action_id}/submit[.h-endpoint-link]. Submitting an action behaves differently depending on the method you use.

• Submitting Application methods: When you submit an [.h-code]application[.h-code] method, Herald submits the values to the institution. This is similar to what happens when you make a submission, which submits the application to the institution.
• Submitting Link methods: When you submit a [.h-code]link[.h-code] method, Herald checks with the institution to confirm that the action was completed properly.

Here’s an example of how you would submit an application method:

POST /actions/{action_id}/submit

Copied

{
  "action": {
    "method": "application"
  }
}
 

In either case, once the action is submitted, the response simply communicates that the action was submitted properly.

Copied

{
  "result": "success"
}
 

Once the action is submitted, you have to poll [.h-code]GET[.h-code] [.h-endpoint-link]/actions/{action_id}[.h-endpoint-link] to check for updates. Read more about what happens next in our guide to completing actions.