> 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/integrations/fetch-risk-items.md).

# Fetch Risk items

## Endpoints

<table><thead><tr><th width="113">Method</th><th>Endpoint</th></tr></thead><tbody><tr><td><mark style="color:blue;">GET</mark></td><td><a href="#get-the-data-of-a-given-risk-item"><code>https://app.insurehero.io/api/shield/integrations/v1/risk-items/:riskItemId</code></a></td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><a href="#get-all-risk-items"><code>https://app.insurehero.io/api/shield/integrations/v1/risk-items</code></a></td></tr></tbody></table>

## How to get the data

### Get the data of a given Risk Item

<mark style="color:blue;">`GET`</mark> `https://app.insurehero.io/api/shield/integrations/v1/risk-items/:riskItemId`

#### Headers

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

#### Path Parameters

| Name                                         | Type   | Description          |
| -------------------------------------------- | ------ | -------------------- |
| riskItemId<mark style="color:red;">\*</mark> | string | Risk item identifier |

#### Example response

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

```json
{
    "data": {
        "id": "943511e3-de9a-4afb-a126-b434ebd1f84e",
        "authorized_claimants": [
            {
                "email": "luciamartinez@example.com",
                "name": "Lucia Martinez",
                "phone": "593999002823"
            },
            {
                "email": "marcoreyes@example.com",
                "name": "Marco Reyes",
                "phone": "593999002824"
            }
        ],
        "package_id": "12e02904-0ab6-41e5-a66f-14fe5d981960",
        "start_date": "2024-03-15T00:00:00+00:00",
        "end_date": "2024-03-31T23:59:59.999+00:00",
        "beneficiaries": [
            {
                "email": "anatorres@example.com",
                "phone": "593999002825"
            }
        ],
        "insured_subject": {
            "identifier_value": "GN789",
            "identifier_type": "Guide Number",
            "ruc": "1711186642001",
            "driver_id": "1714486642",
            "group_uid": "yourUID01",
            "group_name": "Ecuador Transport",
            "policy_note": "Insured against theft and damage",
            "guide_number": "GN789",
            "plate_number": "PICH1234",
            "subject_type": "cargo",
            "invoice_count": 10,
            "departure_city": "Guayaquil",
            "departure_date": "2024-01-24T09:00:00Z",
            "content_category": "Clothing",
            "departure_coords": "-2.170998, -79.922359",
            "destination_city": "Quito",
            "driver_full_name": "Luis Andrade",
            "primary_category": "Men's Apparel",
            "business_industry": "Consumo Masivo",
            "policy_observations": "Fragile items inside",
            "total_insured_value": 75000
        },
        "status": "ACTIVE",
        "uid": null,
        "assets": [],
        "metadata": {
            "delivery_stops": {
                "Delivery 1": {
                    "items": [
                        {
                            "item_sku": "LAP1234A",
                            "item_cost": 1200,
                            "item_name": "Laptop",
                            "item_expiry": "2024-12-31",
                            "item_quantity": 10
                        }
                    ],
                    "final_coords": "-0.180653, -78.467838",
                    "destination_invoice_id": "INV1001"
                }
            }
        },
        "policy_id": "c42a9583-9a58-4b0c-b332-21499780a35b"
    }
}
```

{% endtab %}

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

{% endtab %}

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

{% endtab %}

{% tab title="402: Payment Required Pending payment" %}

{% endtab %}

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

{% endtab %}

{% tab title="429: Too Many Requests API rate limit" %}

{% endtab %}

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

{% endtab %}
{% endtabs %}

### Get all Risk Items

Paginated list of all risk items. Page size cannot exceed 100 records at a time.

<mark style="color:blue;">`GET`</mark> `https://app.insurehero.io/api/shield/integrations/v1/risk-items`

#### Headers

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

#### Query Parameters

<table><thead><tr><th>Name</th><th width="261">Type</th><th>Description</th></tr></thead><tbody><tr><td>from<mark style="color:red;">*</mark></td><td>string</td><td>Starting record index</td></tr><tr><td>to<mark style="color:red;">*</mark></td><td>string</td><td>Ending record index</td></tr></tbody></table>

#### Example response

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

```json
{
    "data": [
        {
            "id": "943511e3-de9a-4afb-a126-b434ebd1f84e",
            "authorized_claimants": [
                {
                    "email": "luciamartinez@example.com",
                    "name": "Lucia Martinez",
                    "phone": "593999002823"
                },
                {
                    "email": "marcoreyes@example.com",
                    "name": "Marco Reyes",
                    "phone": "593999002824"
                }
            ],
            "package_id": "12e02904-0ab6-41e5-a66f-14fe5d981960",
            "start_date": "2024-03-15T00:00:00+00:00",
            "end_date": "2024-03-31T23:59:59.999+00:00",
            "beneficiaries": [
                {
                    "email": "anatorres@example.com",
                    "phone": "593999002825"
                }
            ],
            "insured_subject": {
                "identifier_value": "GN789",
                "identifier_type": "Guide Number",
                "ruc": "1711186642001",
                "driver_id": "1714486642",
                "group_uid": "yourUID01",
                "group_name": "Ecuador Transport",
                "policy_note": "Insured against theft and damage",
                "guide_number": "GN789",
                "plate_number": "PICH1234",
                "subject_type": "cargo",
                "invoice_count": 10,
                "departure_city": "Guayaquil",
                "departure_date": "2024-01-24T09:00:00Z",
                "content_category": "Clothing",
                "departure_coords": "-2.170998, -79.922359",
                "destination_city": "Quito",
                "driver_full_name": "Luis Andrade",
                "primary_category": "Men's Apparel",
                "business_industry": "Consumo Masivo",
                "policy_observations": "Fragile items inside",
                "total_insured_value": 75000
            },
            "status": "ACTIVE",
            "uid": null,
            "assets": [],
            "metadata": {
                "delivery_stops": {
                    "Delivery 1": {
                        "items": [
                            {
                                "item_sku": "LAP1234A",
                                "item_cost": 1200,
                                "item_name": "Laptop",
                                "item_expiry": "2024-12-31",
                                "item_quantity": 10
                            }
                        ],
                        "final_coords": "-0.180653, -78.467838",
                        "destination_invoice_id": "INV1001"
                    }
                }
            },
            "policy_id": "c42a9583-9a58-4b0c-b332-21499780a35b"
        },
        {
            "id": "4729a579-7121-4926-92eb-19f9f0ed1158",
            "authorized_claimants": [
                {
                    "email": "luciamartinez@example.com",
                    "name": "Lucia Martinez",
                    "phone": "593999002823"
                },
                {
                    "email": "marcoreyes@example.com",
                    "name": "Marco Reyes",
                    "phone": "593999002824"
                }
            ],
            "package_id": "12e02904-0ab6-41e5-a66f-14fe5d981960",
            "start_date": "2024-03-15T00:00:00+00:00",
            "end_date": "2024-03-31T23:59:59.999+00:00",
            "beneficiaries": [
                {
                    "email": "anatorres@example.com",
                    "name": "Ana Torres",
                    "phone": "593999002825",
                    "group_uid": "yourUID01"
                }
            ],
            "insured_subject": {
                "identifier_value": "GN789",
                "identifier_type": "Guide Number",
                "ruc": "1711186642001",
                "driver_id": "1714486642",
                "group_uid": "yourUID01",
                "group_name": "Ecuador Transport",
                "policy_note": "Insured against theft and damage",
                "guide_number": "GN789",
                "plate_number": "PICH1234",
                "subject_type": "cargo",
                "invoice_count": 10,
                "departure_city": "Guayaquil",
                "departure_date": "2024-01-24T09:00:00Z",
                "content_category": "Clothing",
                "departure_coords": "-2.170998, -79.922359",
                "destination_city": "Quito",
                "driver_full_name": "Luis Andrade",
                "primary_category": "Men's Apparel",
                "business_industry": "Consumo Masivo",
                "policy_observations": "Fragile items inside",
                "total_insured_value": 75000
            },
            "status": "ACTIVE",
            "uid": null,
            "assets": [],
            "metadata": {
                "delivery_stops": {
                    "Delivery 1": {
                        "items": [
                            {
                                "item_sku": "LAP1234A",
                                "item_cost": 1200,
                                "item_name": "Laptop",
                                "item_expiry": "2024-12-31",
                                "item_quantity": 10
                            }
                        ],
                        "final_coords": "-0.180653, -78.467838",
                        "destination_invoice_id": "INV1001"
                    }
                }
            },
            "policy_id": "c42a9583-9a58-4b0c-b332-21499780a35b"
        }
    ]
}
```

{% endtab %}

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

{% endtab %}

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

{% endtab %}

{% tab title="402: Payment Required Pending payment" %}

{% endtab %}

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

{% endtab %}

{% tab title="429: Too Many Requests API rate limit" %}

{% endtab %}

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

{% endtab %}
{% endtabs %}

Additional Attributes

#### Risk Item Details

| Name                  | Type       | Description                                                         |
| --------------------- | ---------- | ------------------------------------------------------------------- |
| id                    | string     | Unique identifier for the risk item.                                |
| authorized\_claimants | object \[] | List of people authorized to make claims related to this risk item. |
| package\_id           | string     | Identifier of the associated package.                               |
| start\_date           | string     | Date when the coverage starts.                                      |
| end\_date             | string     | Date when the coverage ends.                                        |
| beneficiaries         | object\[]  | List of beneficiaries covered by the insurance.                     |
| insured\_subject      | object     | Information about the insured cargo or item.                        |
| status                | string     | Current status of the risk item.                                    |
| uid                   | string     | Unique identifier assigned to the risk item.                        |
| assets                | object\[]  | Additional assets related to the risk item.                         |
| metadata              | object     | Additional metadata including delivery stops.                       |
| policy\_id            | string     | Identifier of the associated policy.                                |

#### Insured Subject Details

| Name                  | Type   | Description                                         |
| --------------------- | ------ | --------------------------------------------------- |
| identifier\_value     | string | Unique identifier for the insured subject.          |
| identifier\_type      | string | Type of identifier.                                 |
| ruc                   | string | RUC number of the insured company.                  |
| driver\_id            | string | Identifier of the driver responsible for transport. |
| group\_uid            | string | Group unique identifier.                            |
| group\_name           | string | Name of the insured group.                          |
| policy\_note          | string | Special notes related to the policy.                |
| guide\_number         | string | Reference guide number.                             |
| plate\_number         | string | License plate number of the insured vehicle.        |
| subject\_type         | string | Type of insured subject.                            |
| invoice\_count        | number | Number of invoices related to this risk item.       |
| departure\_city       | string | City of departure for the insured item.             |
| departure\_date       | string | Date and time of departure.                         |
| content\_category     | string | Category of the insured content.                    |
| departure\_coords     | string | GPS coordinates of the departure location.          |
| destination\_city     | string | City of destination for the insured item.           |
| driver\_full\_name    | string | Full name of the responsible driver.                |
| primary\_category     | string | Primary category of the insured item.               |
| business\_industry    | string | Industry sector related to the insured subject.     |
| policy\_observations  | string | Additional observations about the policy.           |
| total\_insured\_value | number | Total insured value of the risk item.               |

#### Metadata - Delivery Stops

| Name                     | Type   | Description                                        |
| ------------------------ | ------ | -------------------------------------------------- |
| delivery\_stops          | object | Information about the delivery stops.              |
| final\_coords            | string | GPS coordinates of the final delivery destination. |
| destination\_invoice\_id | string | Invoice ID related to the delivery stop.           |

#### Delivery Items

| Name           | Type   | Description                                      |
| -------------- | ------ | ------------------------------------------------ |
| item\_sku      | string | Stock Keeping Unit (SKU) identifier of the item. |
| item\_cost     | number | Cost of the item.                                |
| item\_name     | string | Name of the item.                                |
| item\_expiry   | string | Expiration date of the item.                     |
| item\_quantity | number | Quantity of items being delivered.               |

To access these resources, please remember to visit the [**Links and Resources**](/shield-api/links-and-resources.md) section of the documentation.