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
Name
Type
Description
Authorization*
string
Bearer access token
Request Body
Name
Type
Description
package_uid*
string
The uid of the package to subscribe to.
policy_uid*
string
The uid of the policy associated.
start_date*
string
Risk item starting date (ISO 8601 format)
end_date*
string
Risk item ending date (ISO 8601 format)
insured_subject*
object
Insured information to be included in the risk item. identifier_value and identifier_type are required fields.
uid*
string
Unique identifier
beneficiaries
object[]
List of users who could be beneficiaries. Email or phone are the only required field, the others are optional.
authorized_claimants
object[]
List of users who would be authorized claimants. Email is the only required field, the others are optional.
metadata
object
Additional data to include in the risk item
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
Name
Type
Description
Authorization*
string
Bearer access token
Path Parameters
Name
Type
Description
riskItemId*
string
Risk item identifier
Request Body
Name
Type
Description
event_data*
object
Additional data related to an event. "start_date" and "end_date" are obligatory
metadata
object
Additional data to include in the event
uid
text
Unique identifier for the event
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"
},
"uid": "uid-event-001"
}
}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
Name
Type
Description
Authorization*
string
Bearer access token
Query Parameters
Name
Type
Description
from*
string
Starting record index
to*
string
Ending record index
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
Name
Type
Description
Authorization*
string
Bearer access token
Path Parameters
Name
Type
Description
riskItemId*
string
Risk item identifier
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
Name
Type
Description
Authorization*
string
Bearer access token
Path Parameters
Name
Type
Description
riskItemId*
string
The id of the risk item associated with the events
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
Name
Type
Description
Authorization*
string
Bearer access token
Path Parameters
Name
Type
Description
userId*
string
user identifier
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
Name
Type
Description
Authorization*
string
Bearer access token
Path Parameters
Name
Type
Description
riskItemId*
string
Risk item identifier
Body
Name
Type
Description
end_date*
date
End date of the Risk item. If you send "cancel" the current date is sent.
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
Name
Type
Description
Authorization*
string
Bearer access token
Path Parameters
Name
Type
Description
riskItemId*
string
Risk item identifier
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