Thanks! Someone from our team will reach out to you soon.
Oops! Something went wrong while submitting the form.
Completing Actions: Step-by-Step
All the steps to filling out and submitting actions
Actions allow you to submit additional information to institutions after a policy or quote has been created. An action functions similarly to an application or bind application in the sense that the required information is communicated dynamically. In other words, getting an action will dynamically provide the full picture regarding what the institution is requesting. There are 3 main steps when using [.h-endpoint-link]/actions[.h-endpoint-link]:
Get an Action ([.h-code]GET[.h-code] [.h-endpoint-link]/actions/{action_id}[.h-endpoint-link])
Complete the Action ([.h-code]PUT[.h-code] [.h-endpoint-link]/actions/{action_id}[.h-endpoint-link])
Unlike applications and bind applications, actions do not need to be created. Actions are assigned by the institution, as outlined in our actions doc. If actions are required for a policy, they are communicated on the policy in the actions array, beginning with an [.h-code]open[.h-code] status. Details of an action can be retrieved using the [.h-code]id[.h-code] of the action provided in the policy response, like this:
The details of that action can be retrieved using [.h-code]GET[.h-code] [.h-endpoint-link]/actions/{action_id}[.h-endpoint-link], which will provide the following information:
GET/actions/{action_id}
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"
}
]
},
{
"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": []
}
}
]
}
}
As you can see above, the action response includes the [.h-code]id[.h-code], [.h-code]status[.h-code], [.h-code]text[.h-code] to describe the action, and an array of [.h-code]methods[.h-code]. The methods array contains individual methods that can be used to complete the action, which is limited to a method of type [.h-code]application[.h-code] and a method of type [.h-code]link[.h-code].
[.icon-circle-blue][.icon-circle-blue] The available methods will depend on the action. Some actions may only offer a [.h-code]link[.h-code] method or [.h-code]application[.h-code] method, and some actions offer both methods.
The application method: Allows you to provide information the same way you provide information on an application to get quotes- by submitting values for parameters! Submitting values for the [.h-code]application[.h-code] method is nearly identical to submitting values to [.h-endpoint-link]/applications[.h-endpoint-link], which will describe in more detail in step 2.
The link method: Allows you to complete the action by visiting a link provided by the institution. Links may be agent facing (for agents to visit) or applicant facing (for applicants to visit).
In order to submit the action to the institution, you must complete the action using one of the available methods. The steps to completing an action is very different depending on the method you use. Below are examples of how to complete an action with each method.
{
"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": []
}
}
],
....
}
}
Look familiar? The application method contains the type, text to communicate how to use this method, and an application! The structure of the application nested in the method is the same as the application resource. It’s comprised of a status, as well as risk, coverage, and admin values.
In this example above, the only value required to complete the action is a risk value for a signed application (parameter rsk_ms9x_signed_application). Read our guide to uploading files.
Submitting the value works similarly to submitting values on an application. The only difference is that the application is nested within the method array. Our request to update the value would look like this:
Since this is the only parameter required for the action, the response will show that the application method now has a status of complete. You can now move on to step 3.
Copied
{
"action": {
.....
"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": "complete",
"risk_values": [
.....
Completing an action via the link method involves surfacing the link to your users. Clicking the link will bring the user to a front-end provided by the institution to complete the action. Once the link is clicked, we recommend confirming with your users that they have completed the action correctly before submitting the action to the institution. In other words, using the link method relies heavily on the honor system.
In the example above, you would use the link located in the link method. Herald provides text to communicate the expected steps after bridging to the institutions front-end.
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"
}
]
},
]
}
}
Once the action is complete, you can submit it to the institution. When submitting an action, you send the [.h-code]method[.h-code] you 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 [.h-code]method[.h-code] 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. Immediately after submitting the action, the status will progress from [.h-code]open[.h-code] to [.h-code]pending[.h-code] as Herald communicates with the institution. Similar to checking for updates on quotes and bind orders, the time it takes for an institution to review the action can vary depending on the product. If everything is submitted correctly, the action will progress to an [.h-code]accepted[.h-code] status.
You can find more details on the progression of an action in our action statuses doc.
