Risk Item management
Adding a Risk Item to a policy defines the "insured subject," such as personal items (eyewear, bicycles), larger assets (vehicles), an individual's life or health, and shipping cargo. This step tailors the subject to specific coverage plans, optimizing pricing and operational efficiency.
For practical guidance, we encourage you to explore our Risk Item creation examples, showcasing pre-configured payloads. These examples are illustrative, and adjustments may be necessary based on the insurance product and jurisdiction.
How to get the data
To gather the requisite data for creating a risk-item, it's advisable to utilize the endpoints detailed in the policy management section. There, you can access information on available policies, enabling you to procure the necessary details for the required package. This facilitates obtaining insights into the package's variants and coverages.
Add a Risk Item to a policy
POST https://app.insurehero.io/api/shield/v1/risk-items
Headers
Request Body
Example response
{
"data": {
"id": "4729a579-7121-4926-92eb-19f9f0ed1158",
"policy_id": "c42a9583-9a58-4b0c-b332-21499780a35b",
"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"
}
}
}
}
}Add Event to Risk Item
Add a new event with asynchronous data to a risk item
POST https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/events
Headers
Path Parameters
Request Body
Example response
{
"data": {
"id": "e680dd13-99d4-42a9-bd67-40e3069cfc6c",
"risk_item_id": "2140618c-522c-493c-a81d-c28ccfa9d86e",
"event_data": {
"start_date": "2024-03-15T00:00:00.000Z",
"end_date": "2024-06-15T00:00:00.000Z"
},
"metadata": {
"description": "Event description"
}
}
}Get all Risk Items
Paginated list of all risk items. Page size cannot exceed 100 records at a time.
GET https://app.insurehero.io/api/shield/v1/risk-items
Headers
Query Parameters
Example response
{
"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"
}
]
}Get the data of a given Risk Item
GET https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId
Headers
Path Parameters
Example response
{
"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"
}
}Additional resources
Get Risk Item events
GET https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/events
Events in a risk item
Headers
Path Parameters
Example response
{
"data": {
"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",
"events": [
{
"id": "e680dd13-99d4-42a9-bd67-40e3069cfc6c",
"risk_item_id": "4729a579-7121-4926-92eb-19f9f0ed1158",
"metadata": {
"clientName": "ABC Logistics Inc.",
"policyNote": "Insured against theft, damage, and loss during transportation.",
"guideNumber": "GN789",
"plateNumber": "CA4567",
"invoiceCount": 10,
"departureCity": "Los Angeles",
"contentCategory": "Clothing",
"destinationCity": "New York",
"primaryCategory": "Men's Apparel",
"totalInsuredValue": 75000,
"policyObservations": "Fragile items inside"
},
"event_data": {
"invoiceCount": 3,
"contentCategory": "Shirt"
}
},
{
"id": "cb3ef0d6-0939-42fc-b8cf-1dcac6aebed5",
"risk_item_id": "4729a579-7121-4926-92eb-19f9f0ed1158",
"metadata": {
"clientName": "ABC Logistics Inc.",
"policyNote": "Insured against theft, damage, and loss during transportation.",
"guideNumber": "GN789",
"plateNumber": "CA4567",
"invoiceCount": 10,
"departureCity": "Los Angeles",
"contentCategory": "Clothing",
"destinationCity": "New York",
"primaryCategory": "Men's Apparel",
"totalInsuredValue": 75000,
"policyObservations": "Fragile items inside"
},
"event_data": {
"invoiceCount": 3,
"contentCategory": "Shirt"
}
}
]
}
}Get Risk Item by user
GET https://app.insurehero.io/api/shield/v1/users/:userId/risk-items
Headers
Path Parameters
Example response
{
"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"
}
]
}Update end date of a Risk Item
You can cancel a Risk Item by modifying its end-date
PATCH https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/cancel
Headers
Path Parameters
Body
Example response
{
"data": {
"id": "943511e3-de9a-4afb-a126-b434ebd1f84e",
"policy_id": "c42a9583-9a58-4b0c-b332-21499780a35b",
"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"
}
}
}
}
}Risk Item Rescission
This endpoint is useful to cancel a risk-item immediately
DELETE https://app.insurehero.io/api/shield/v1/risk-items/:riskItemId/rescission
Headers
Path Parameters
Example response
{
"data": {
"id": "943511e3-de9a-4afb-a126-b434ebd1f84e",
"policy_id": "c42a9583-9a58-4b0c-b332-21499780a35b",
"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-06-10T17:33:41.524+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": "INACTIVE",
"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"
}
}
}
}
}Last updated