> For the complete documentation index, see [llms.txt](https://docs.insurehero.io/shield-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.insurehero.io/shield-api/claims/workflows-management.md).

# Workflows Management

***

This page will introduce you to **workflows**. But what do we mean by workflows? **Workflows** are the sequences of steps that certain claims go through. In other words, the process doesn't end once a claim is created. There are specific steps that must be completed.

Let's consider an example: suppose there is a theft claim. The first step is to create the claim, but then two things need to be validated—a police report confirming the theft occurred and the amount to be covered. These aspects can't be verified at the time of creating the claim because you don't have the theft report, and without it, we can't validate what will be covered.

Therefore, the claim enters a system of steps where the necessary information can be requested to fulfill the requirements, allowing for much more granular and asynchronous management of each case. This may involve agents and communication with third parties. This documentation will guide you on how to integrate **workflows**, always keeping in mind that this process takes place after the claim has been created.

## Endpoints

<table><thead><tr><th width="113">Method</th><th>Endpoint</th></tr></thead><tbody><tr><td><mark style="color:green;">POST</mark></td><td><a href="#post-a-step"><code>https://app.insurehero.io/api/shield/v1/claims/:claimId/workflow</code></a></td></tr><tr><td><mark style="color:green;">POST</mark></td><td><a href="#post-a-step"><code>https://app.insurehero.io/api/shield/v2/claims/:claimId/workflow</code></a></td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><a href="#get-step-information"><code>https://app.insurehero.io/api/shield/v1/claims/:claimId/workflow</code></a></td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><a href="#get-step-information"><code>https://app.insurehero.io/api/shield/v2/claims/:claimId/workflow</code></a></td></tr></tbody></table>

## How to interact with a workflow

To interact with a **workflow**, it's necessary to know the **claim ID**. Therefore, we recommend understanding how **claim gets** work.

### Post a step

{% tabs %}
{% tab title="v1" %} <mark style="color:green;">`POST`</mark> `https://app.insurehero.io/api/shield/v1/claims/:claimId/workflow`
{% endtab %}

{% tab title="v2" %} <mark style="color:green;">`POST`</mark> `https://app.insurehero.io/api/shield/v2/claims/:claimId/workflow`
{% endtab %}
{% endtabs %}

#### Headers

| Name                                            | Type   | Description                                                                                          |
| ----------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token                                                                                  |
| User-Authorization                              | string | [User unique token to create claims](https://docs.insurehero.io/shield-api/policies/user-management) |
| Content-Type<mark style="color:red;">\*</mark>  | string | `application/json` or `multipart/form-data`, depending on the step                                   |

`User-Authorization` is required only in channels that are not enabled for handshake. Send the user token returned by `POST /v1/users/:userId/verify-otp` as is, without the `Bearer` prefix; it is valid for 1 hour. Without a valid user token, those channels get `400` with details `"Missing user token"`. In channels enabled for handshake the header is not checked.

#### Request Body

This endpoint support raw and form-data depending upon the kind of requirement of the step. To know more about what kind of data you can send use the get workflow endpoint.

{% tabs %}
{% tab title="raw" %}

| Name                                                  | Type   | Description                                                                                     |
| ----------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------- |
| WorkflowStepRequest<mark style="color:red;">\*</mark> | object | The data requested by the current step. It is validated against the `inbound` rules of the step |
| {% endtab %}                                          |        |                                                                                                 |

{% tab title="form-data" %}

| Key                                    | Value | Description                                                                                                               |
| -------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------- |
| file<mark style="color:red;">\*</mark> | File  | All files must have "file" as key to be processed succesfully. Only one file per step, with the extension in `typeOfFile` |
| {% endtab %}                           |       |                                                                                                                           |
| {% endtabs %}                          |       |                                                                                                                           |

**Types of responses**

{% tabs %}
{% tab title="200: OK Step received" %}

```json
{
    "data": "Data validated correctly and status updated."
}
```

If the step needs the approval of an agent, `data` is `"Data validated and information updated. Approval needed from agent."`
{% endtab %}

{% tab title="400: Bad Request Request contains malformed data" %}

```json
{
    "error": "Request contains malformed data",
    "details": "Missing user token"
}
```

When the claim does not have a workflow yet, `details` is `"Workflow is undefined"`.
{% endtab %}

{% tab title="401: Unauthorized Invalid or expired access token" %}

{% endtab %}

{% tab title="404: Not Found Claim not found" %}

```json
{
    "error": "Resource not found",
    "details": "Claim not found"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Internal validation failed" %}

```json
{
    "error": "Internal validation failed",
    "details": "This workflow is already completed."
}
```

Other cases that return `422`:

* The current step does not expect any data: `"This workflow step does not need to receive anything."`
* The step expects a file and the request is JSON: `"This workflow step needs a file."`
* The request sends a file and the step does not expect one: `"This workflow step does not needs a file."`
* The file does not have the expected extension, more than one file is sent, or the file could not be uploaded. `details` explains the reason.
* `WorkflowStepRequest` does not match the `inbound` rules of the step. `details` contains the validation error.
* The body is not valid JSON or `multipart/form-data`. `details` contains a validation issue on `body` with the message `"Invalid request body"`.
* Internal failure. `details` contains `"message": "Internal error"` and an `event_id` that identifies the incident for support.

See [Error Handling](https://docs.insurehero.io/shield-api/data-dictionary#error-handling) for the general format.
{% endtab %}
{% endtabs %}

### Get step information

Fetch the information needed to pass the step

{% tabs %}
{% tab title="v1" %} <mark style="color:blue;">`GET`</mark> `https://app.insurehero.io/api/shield/v1/claims/:claimId/workflow`
{% endtab %}

{% tab title="v2" %} <mark style="color:blue;">`GET`</mark> `https://app.insurehero.io/api/shield/v2/claims/:claimId/workflow`
{% endtab %}
{% endtabs %}

#### Path Parameters

| Name                                      | Type   | Description                                         |
| ----------------------------------------- | ------ | --------------------------------------------------- |
| claimId<mark style="color:red;">\*</mark> | string | Claim identifier. Its meaning depends on `searchBy` |

#### Query Parameters

| Name     | Type                                 | Description                                                                                                 |
| -------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| searchBy | id \| uid \| internal\_claim\_number | Field used to search for a matching claim. Defaults to 'id'                                                 |
| all      | string                               | When present with any value, `workflow` contains every step of the workflow instead of only the current one |

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

{% tabs %}
{% tab title="200: OK Retrieved successfully" %}

```json
{
    "data": {
        "id": "9df4ab78-1275-5ea6-8e7e-0c10caa1f30d",
        "current_step": "step_2",
        "workflow": {
            "step_2": {
                "name": "Upload the police report",
                "inbound": {
                    "undefined": {
                        "type": "file",
                        "typeOfFile": ".png"
                    }
                }
            }
        }
    }
}
```

{% endtab %}

{% tab title="400: Bad Request Request contains malformed data" %}
The claim has no workflow or no current step:

```json
{
    "error": "Request contains malformed data",
    "details": "Workflow is undefined"
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid or expired access token" %}

{% endtab %}

{% tab title="422: Unprocessable Entity Internal validation failed" %}
An invalid `searchBy` value returns `422` with the validation issues in `details`.
{% endtab %}

{% tab title="404: Not Found Claim not found" %}

```json
{
    "error": "Resource not found",
    "details": "Claim not found"
}
```

{% endtab %}
{% endtabs %}

If the current step does not expect information from the client, `inbound` is the text `"We are not waiting information from the client to complete this step"` instead of an object.

#### Attributes

| Name          | Type   | Description (English)                                                                      |
| ------------- | ------ | ------------------------------------------------------------------------------------------ |
| data          | object | Contains the workflow data.                                                                |
| id            | uuid   | Unique identifier of the claim.                                                            |
| current\_step | string | Indicates the current step in the workflow.                                                |
| workflow      | object | Defines the steps and their configurations.                                                |
| step\_2       | object | Represents a specific step within the workflow.                                            |
| name          | string | Name of the step.                                                                          |
| inbound       | object | Defines the expected input requirements. It is a text when the step does not expect input. |
| undefined     | object | Contains details about required files or inputs.                                           |
| type          | string | Specifies the input type (e.g., file).                                                     |
| typeOfFile    | string | Specifies the expected file type (e.g., .png).                                             |